@kadi.build/core 0.0.1-alpha.3 → 0.0.1-alpha.5

package/src/transport/IpcMessageBuilder.js

@@ -1,1229 +0,0 @@
-// IpcMessageBuilder.js
-// ESM module
-// A unified message builder for Kadi ability communication supporting both
-// client-side (sending requests) and server-side (handling requests) operations.
-// Supports multiple transport modes: stdio (LSP-framed), broker (WebSocket), and custom.
-
-import { WebSocket } from 'ws';
-import { Broker, IdFactory } from './BrokerMessageBuilder.js';
-import crypto from 'node:crypto';
-//
-// CLIENT SIDE USAGE:
-//   import { Ipc } from './IpcMessageBuilder.js';
-//
-//   // Option A: bind once
-//   const IPC = Ipc.with(rpc);
-//   const initRes = await IPC.init({ api: '1.0' });
-//   const added = await IPC.call('add', { a: 1, b: 2 });
-//
-//   // Option B: inline (no binding)
-//   await Ipc.init({ api: '1.0' }, rpc);
-//   const sum = await Ipc.call('add', { a: 1, b: 2 }, rpc);
-//
-// SERVER SIDE USAGE:
-//   import { IpcServer, StdioTransport } from './IpcMessageBuilder.js';
-//
-//   const server = IpcServer.create()
-//     .method('add', async ({ a, b }) => ({ result: a + b }))
-//     .transport(new StdioTransport())
-//     .serve();
-//
-// ──────────────────────────────────────────────────────────────────────────────
-
-import { EventEmitter } from 'events';
-import { Readable, Writable } from 'stream';
-
-// Frame protocol constants - single source of truth
-const FRAME_HEADERS = {
-  CONTENT_LENGTH: 'Kadi-Content-Length',
-  CONTENT_TYPE: 'Content-Type'
-};
-
-const FRAME_VALUES = {
-  CONTENT_TYPE_VALUE: 'application/kadi-jsonrpc; charset=utf-8',
-  HEADER_DELIMITER: '\r\n\r\n'
-};
-
-/** Central wire method map (override via configureMethods). */
-const methodNames = {
-  init: '__kadi_init',
-  discover: '__kadi_discover'
-};
-
-// ──────────────────────────────────────────────────────────────────────────────
-// TRANSPORT LAYER CLASSES (extracted from KadiAbility)
-// ──────────────────────────────────────────────────────────────────────────────
-
-/**
- * Frame reader for LSP-style stdio communication with corruption recovery
- */
-export class StdioFrameReader {
-  constructor(input = process.stdin, options = {}) {
-    this.input = input;
-    this.buffer = Buffer.alloc(0);
-    this.maxBufferSize = options.maxBufferSize || 8 * 1024 * 1024; // 8MB default
-
-    // Pre-compile our delimiter buffers for efficiency
-    this.HEADER_DELIM = Buffer.from('\r\n\r\n');
-    this.CONTENT_LENGTH_MARKER = Buffer.from('Kadi-Content-Length:');
-  }
-
-  /**
-   * Set up event-driven message processing
-   */
-  onMessage(callback) {
-    this.input.on('data', (chunk) => {
-      this.buffer = Buffer.concat([this.buffer, chunk]);
-
-      if (this.buffer.length > this.maxBufferSize) {
-        this._trimBuffer();
-      }
-
-      // Try to extract messages from the buffer
-      let result;
-      while ((result = this._extractMessage())) {
-        callback(result);
-      }
-    });
-
-    this.input.on('end', () => {
-      // Process any remaining messages in buffer
-      let result;
-      while ((result = this._extractMessage())) {
-        callback(result);
-      }
-    });
-  }
-
-  _extractMessage() {
-    const contentLengthPos = this.buffer.indexOf(this.CONTENT_LENGTH_MARKER);
-    if (contentLengthPos === -1) return null;
-
-    if (contentLengthPos > 0) {
-      const garbage = this.buffer.subarray(0, contentLengthPos);
-      if (garbage.length > 100) {
-        const preview =
-          garbage.length > 50
-            ? garbage.subarray(0, 50).toString('utf8').replace(/\n/g, '\\n') +
-              '...'
-            : garbage.toString('utf8').replace(/\n/g, '\\n');
-        console.error(
-          `[StdioFrameReader] Skipping ${garbage.length} bytes of garbage: "${preview}"`
-        );
-      }
-      this.buffer = this.buffer.subarray(contentLengthPos);
-    }
-
-    const headerEndPos = this.buffer.indexOf(this.HEADER_DELIM);
-    if (headerEndPos === -1) return null;
-
-    const headerBytes = this.buffer.subarray(0, headerEndPos);
-    const headerText = headerBytes.toString('ascii');
-    const headers = this._parseHeaders(headerText);
-
-    const contentLength = parseInt(
-      headers[FRAME_HEADERS.CONTENT_LENGTH] || '0',
-      10
-    );
-    if (!Number.isFinite(contentLength) || contentLength < 0) {
-      console.error(
-        `[StdioFrameReader] Invalid Content-Length: "${headers[FRAME_HEADERS.CONTENT_LENGTH]}" - discarding frame`
-      );
-      this.buffer = this.buffer.subarray(
-        headerEndPos + this.HEADER_DELIM.length
-      );
-      return {
-        success: false,
-        error: 'INVALID_CONTENT_LENGTH',
-        message: `Invalid Content-Length: "${headers[FRAME_HEADERS.CONTENT_LENGTH]}"`,
-        corruption_type: 'WRONG_LENGTH',
-        content_length: headers[FRAME_HEADERS.CONTENT_LENGTH],
-        raw: headerBytes.subarray(0, 100)
-      };
-    }
-
-    const bodyStart = headerEndPos + this.HEADER_DELIM.length;
-    const bodyEnd = bodyStart + contentLength;
-
-    if (this.buffer.length < bodyEnd) return null; // Wait for more body bytes
-
-    const bodyBytes = this.buffer.subarray(bodyStart, bodyEnd);
-    this.buffer = this.buffer.subarray(bodyEnd);
-
-    try {
-      const data = JSON.parse(bodyBytes.toString('utf8'));
-      return {
-        success: true,
-        data
-      };
-    } catch (err) {
-      console.error(
-        `[StdioFrameReader] Failed to parse JSON body: ${err.message}`
-      );
-      console.error(
-        `[StdioFrameReader] Body preview: ${bodyBytes.subarray(0, 100).toString('utf8')}...`
-      );
-      return {
-        success: false,
-        error: 'JSON_PARSE_FAILED',
-        message: err.message,
-        corruption_type: 'INVALID_JSON',
-        content_length: parseInt(
-          headers[FRAME_HEADERS.CONTENT_LENGTH] || '0',
-          10
-        ),
-        actual_length: bodyBytes.length,
-        raw: bodyBytes.subarray(0, 200) // First 200 bytes for debugging
-      };
-    }
-  }
-
-  _parseHeaders(headerText) {
-    const headers = {};
-    const lines = headerText.split('\r\n');
-    for (const line of lines) {
-      const [name, value] = line.split(/:\s*/);
-      if (name && value) {
-        headers[name] = value;
-      }
-    }
-    return headers;
-  }
-
-  _trimBuffer() {
-    console.warn(
-      `[StdioFrameReader] Buffer size (${this.buffer.length}) exceeds max (${this.maxBufferSize}), trimming...`
-    );
-    const lastMarkerPos = this.buffer.lastIndexOf(this.CONTENT_LENGTH_MARKER);
-    if (lastMarkerPos > this.maxBufferSize / 2) {
-      const keepFrom = Math.max(lastMarkerPos - 1024, 0);
-      this.buffer = this.buffer.subarray(keepFrom);
-      console.warn(
-        `[StdioFrameReader] Trimmed to ${this.buffer.length} bytes, preserved from last frame marker`
-      );
-    } else {
-      const keepBytes = Math.floor(this.maxBufferSize / 2);
-      this.buffer = this.buffer.subarray(this.buffer.length - keepBytes);
-      console.warn(
-        `[StdioFrameReader] Emergency trim: kept last ${keepBytes} bytes`
-      );
-    }
-  }
-}
-
-/**
- * Frame writer for LSP-style stdio communication
- */
-export class StdioFrameWriter {
-  constructor(output = process.stdout) {
-    this.output = output;
-  }
-
-  async write(message) {
-    const body = Buffer.from(JSON.stringify(message), 'utf-8');
-    const header = `${FRAME_HEADERS.CONTENT_LENGTH}: ${body.length}\r\n${FRAME_HEADERS.CONTENT_TYPE}: ${FRAME_VALUES.CONTENT_TYPE_VALUE}\r\n\r\n`;
-
-    // Make the write atomic by combining header and body into a single buffer
-    const fullFrame = Buffer.concat([Buffer.from(header, 'ascii'), body]);
-
-    await this.writeBuffer(fullFrame);
-  }
-
-  writeBuffer(buffer) {
-    return new Promise((resolve, reject) => {
-      this.output.write(buffer, (err) => {
-        if (err) reject(err);
-        else resolve();
-      });
-    });
-  }
-}
-
-/** Allow consumers to override one or more method strings. */
-export function configureMethods(overrides = {}) {
-  for (const [k, v] of Object.entries(overrides)) {
-    if (!(k in methodNames)) throw new Error(`Unknown method key: ${k}`);
-    if (typeof v !== 'string' || !v.length)
-      throw new Error(`Bad method string for ${k}`);
-    methodNames[k] = v;
-  }
-  return { ...methodNames };
-}
-
-/**
- * Lightweight, chainable message builder that *doesn't* manage ids.
- * It mirrors your transport, which already assigns ids on `rpc.call`.
- */
-class MsgBuilder {
-  /** @param {string} method */
-  constructor(method) {
-    this._method = method;
-    this._params = undefined;
-    this._isNotification = false;
-  }
-
-  /** Attach/override params. */
-  params(obj) {
-    this._params = obj ?? undefined;
-    return this;
-  }
-
-  /** Mark as a notification (fire‑and‑forget). */
-  asNotification(on = true) {
-    this._isNotification = !!on;
-    return this;
-  }
-
-  /** Plain call tuple for your `rpc.call(method, params)` */
-  forCall() {
-    return { method: this._method, params: this._params };
-  }
-
-  /** Plain notify tuple for your `rpc.notify(method, params)` */
-  forNotify() {
-    return { method: this._method, params: this._params };
-  }
-
-  /** Convenience: send with your existing rpc. */
-  send(rpc) {
-    const { method, params } = this.forCall();
-    return rpc.call(method, params);
-  }
-  notifyWith(rpc) {
-    const { method, params } = this.forNotify();
-    return rpc.notify(method, params);
-  }
-
-  /** Optional: build a raw JSON-RPC object (supply your own id). */
-  toJsonRpc(id) {
-    const obj = { jsonrpc: '2.0', method: this._method };
-    if (this._params !== undefined) obj.params = this._params;
-    if (!this._isNotification) obj.id = id;
-    return obj;
-  }
-  /** Convenience: full LSP frame (headers + body) as a string. */
-  toJsonRpcFrame(id) {
-    const body = JSON.stringify(this.toJsonRpc(id));
-    return (
-      `Kadi-Content-Length: ${Buffer.byteLength(body, 'utf8')}\r\n\r\n` + body
-    );
-  }
-}
-
-// ──────────────────────────────────────────────────────────────────────────────
-// TRANSPORT ABSTRACTION
-// ──────────────────────────────────────────────────────────────────────────────
-
-/**
- * Base transport interface that all transports must implement
- */
-export class BaseTransport extends EventEmitter {
-  /**
-   * Start listening for incoming messages
-   * @returns {AsyncIterator} Async iterator of incoming messages
-   */
-  async *listen() {
-    throw new Error('Transport must implement listen()');
-  }
-
-  /**
-   * Send a message
-   * @param {Object} message - JSON-RPC message to send
-   */
-  async send(message) {
-    throw new Error('Transport must implement send()');
-  }
-
-  /**
-   * Close the transport
-   */
-  async close() {
-    // Default implementation - transports can override
-  }
-}
-
-/**
- * Stdio transport using LSP framing
- */
-export class StdioTransport extends BaseTransport {
-  constructor(options = {}) {
-    super();
-    this.reader = new StdioFrameReader(options.stdin, options);
-    this.writer = new StdioFrameWriter(options.stdout);
-    this._messageQueue = [];
-    this._listeners = [];
-  }
-
-  async *listen() {
-    // Set up the message handler
-    this.reader.onMessage((result) => {
-      if (!result.success) {
-        // Frame parsing failed - emit error and skip
-        this.emit(
-          'error',
-          new Error(`Frame corruption: ${result.error} - ${result.message}`)
-        );
-        return;
-      }
-
-      this._messageQueue.push(result.data);
-      this._notifyListeners();
-    });
-
-    // Yield messages as they arrive
-    while (true) {
-      if (this._messageQueue.length > 0) {
-        yield this._messageQueue.shift();
-      } else {
-        // Wait for the next message
-        await new Promise((resolve) => {
-          this._listeners.push(resolve);
-        });
-      }
-    }
-  }
-
-  _notifyListeners() {
-    const listeners = this._listeners.splice(0);
-    listeners.forEach((resolve) => resolve());
-  }
-
-  async send(message) {
-    await this.writer.write(message);
-  }
-
-  /**
-   * Start serving requests using this transport
-   *
-   * Creates an internal IpcServer instance and delegates serving to it.
-   * This makes StdioTransport self-contained like BrokerTransport.
-   *
-   * @param {Object} ability - KadiAbility instance with handlers and metadata
-   */
-  async serve(ability) {
-    if (!ability) {
-      throw new Error('StdioTransport.serve() requires an ability instance');
-    }
-
-    // Create an internal IpcServer with the ability's metadata
-    const server = new IpcServer({
-      name: ability.name,
-      version: ability.version,
-      description: ability.description
-    });
-
-    // Copy all handlers from the ability to the server
-    for (const [methodName, handler] of ability._handlers) {
-      server.method(methodName, handler);
-    }
-
-    // Set this transport and start serving
-    server.transport(this);
-
-    // Forward events from server to ability
-    server.on('start', (data) => ability.emit('start', data));
-    server.on('error', (error) => ability.emit('error', error));
-    server.on('stop', () => ability.emit('stop'));
-    server.on('request', (data) => ability.emit('request', data));
-    server.on('response', (data) => ability.emit('response', data));
-
-    await server.serve();
-  }
-}
-
-/**
- * Broker transport using native broker protocol
- *
- * This transport connects abilities to the Kadi broker via WebSocket
- * and speaks the broker's native protocol directly (agent.message/ability.result),
- * bypassing JSON-RPC translation entirely.
- */
-export class BrokerTransport extends BaseTransport {
-  constructor(options = {}) {
-    super(); // Call BaseTransport constructor
-
-    this.brokerUrl = options.brokerUrl || 'ws://localhost:8080';
-    this.abilityName = options.abilityName || 'unnamed-ability';
-    this.abilityVersion = options.abilityVersion || '1.0.0';
-    this.description = options.description || 'A Kadi ability';
-    this.ability = options.ability || null; // Reference to KadiAbility instance
-
-    this._ws = null;
-    this._isConnected = false;
-    this._idFactory = new IdFactory();
-    this._isServing = false;
-    this._requestMetadata = new Map(); // Store broker metadata by request ID
-  }
-
-  /**
-   * Start serving - connects to broker and handles incoming tool calls directly
-   * This method preserves the original working behavior while making BrokerTransport
-   * inherit from BaseTransport for consistency.
-   *
-   * @param {Object} ability - KadiAbility instance with handlers and metadata
-   */
-  async serve(ability) {
-    // If ability is passed, use it; otherwise fall back to constructor option
-    if (ability) {
-      this.ability = ability;
-    }
-    console.error('[BrokerTransport] Starting broker service...');
-
-    // Connect to broker and complete handshake
-    await this._connect();
-    await this._handshake();
-
-    this._isServing = true;
-
-    // Set up message handler for incoming ability calls
-    this._ws.on('message', async (data) => {
-      try {
-        const message = JSON.parse(data.toString());
-        console.error(
-          `[BrokerTransport] Received message:`,
-          JSON.stringify(message, null, 2)
-        );
-
-        // Handle incoming tool calls directly using the ability reference
-        if (message.method === 'agent.message' && message.params) {
-          console.error(
-            '[BrokerTransport] Detected agent.message, handling tool call...'
-          );
-          await this._handleToolCallDirect(message);
-        } else if (message.method === 'ability.result') {
-          // This would be responses to tools we called - not needed for basic abilities
-          console.error(
-            '[BrokerTransport] Received ability.result (not handling)'
-          );
-        } else {
-          console.error(
-            '[BrokerTransport] Message not handled:',
-            message.method
-          );
-        }
-      } catch (err) {
-        console.error(
-          '[BrokerTransport] Failed to parse message:',
-          err.message
-        );
-      }
-    });
-
-    // Keep the connection alive
-    this._startHeartbeat();
-
-    console.error(
-      '[BrokerTransport] Broker service started, ready to receive tool calls'
-    );
-
-    // Keep the process alive
-    return new Promise((resolve, reject) => {
-      this._ws.on('close', () => {
-        this._isServing = false;
-        console.error('[BrokerTransport] Connection closed');
-        resolve();
-      });
-
-      this._ws.on('error', (err) => {
-        this._isServing = false;
-        console.error('[BrokerTransport] WebSocket error:', err);
-        reject(err);
-      });
-    });
-  }
-
-  /**
-   * Listen for incoming broker messages and yield them as JSON-RPC requests
-   *
-   * This method connects to the broker, performs handshake, and then yields
-   * incoming tool calls as standard JSON-RPC requests that can be handled
-   * by the IpcServer.serve() loop.
-   */
-  async *listen() {
-    // Ensure we're connected and registered
-    if (!this._isConnected) {
-      await this._connect();
-      await this._handshake();
-    }
-
-    console.error('[BrokerTransport] Starting message listening...');
-
-    // Create a queue for incoming messages
-    const messageQueue = [];
-    const listeners = [];
-
-    // Set up message handler for incoming ability calls
-    this._ws.on('message', async (data) => {
-      try {
-        const message = JSON.parse(data.toString());
-
-        // Handle incoming tool calls - convert to JSON-RPC format
-        if (message.method === 'agent.message' && message.params) {
-          const { toolName, args, requestId, from } = message.params;
-
-          console.error(`[BrokerTransport] Received tool call: ${toolName}`);
-
-          // Store broker metadata for response handling
-          this._requestMetadata.set(requestId, { requestId, from });
-
-          // Convert broker message to JSON-RPC request format
-          const jsonRpcRequest = {
-            jsonrpc: '2.0',
-            id: requestId, // Use broker's requestId as JSON-RPC id
-            method: toolName,
-            params: args || {}
-          };
-
-          messageQueue.push(jsonRpcRequest);
-          this._notifyListeners(listeners);
-        }
-        // Handle other broker messages (ping responses, etc.)
-        else if (message.method === 'ability.result') {
-          console.error(
-            '[BrokerTransport] Received ability.result (not handling in listen)'
-          );
-        } else {
-          console.error(
-            '[BrokerTransport] Message not handled:',
-            message.method
-          );
-        }
-      } catch (err) {
-        console.error(
-          '[BrokerTransport] Failed to parse message:',
-          err.message
-        );
-      }
-    });
-
-    // Keep the connection alive
-    this._startHeartbeat();
-
-    console.error('[BrokerTransport] Ready to receive tool calls via listen()');
-
-    // Yield messages as they arrive
-    while (true) {
-      if (messageQueue.length > 0) {
-        yield messageQueue.shift();
-      } else {
-        // Wait for the next message
-        await new Promise((resolve) => {
-          listeners.push(resolve);
-        });
-      }
-    }
-  }
-
-  /**
-   * Send response back to broker using the broker protocol
-   *
-   * Converts JSON-RPC response back to broker protocol format and sends it.
-   * Uses the broker metadata stored in the original request to route the response.
-   */
-  async send(message) {
-    if (!this._ws || !this._isConnected) {
-      throw new Error('BrokerTransport: WebSocket not connected');
-    }
-
-    // If this is a JSON-RPC response, convert it to broker protocol
-    if (message.jsonrpc === '2.0' && message.id !== undefined) {
-      // Get the broker metadata for this request
-      const brokerMeta = this._requestMetadata.get(message.id);
-      if (!brokerMeta) {
-        console.error(
-          `[BrokerTransport] No broker metadata found for request ${message.id}`
-        );
-        return;
-      }
-
-      // Clean up the metadata after use
-      this._requestMetadata.delete(message.id);
-
-      let brokerResponse;
-
-      if (message.error) {
-        // Error response
-        brokerResponse = {
-          jsonrpc: '2.0',
-          method: 'ability.result',
-          params: {
-            requestId: brokerMeta.requestId,
-            toSessionId: brokerMeta.from,
-            error: message.error.message || 'Unknown error'
-          }
-        };
-      } else {
-        // Success response
-        brokerResponse = {
-          jsonrpc: '2.0',
-          method: 'ability.result',
-          params: {
-            requestId: brokerMeta.requestId,
-            toSessionId: brokerMeta.from,
-            result: message.result
-          }
-        };
-      }
-
-      console.error(
-        `[BrokerTransport] Sending broker response:`,
-        JSON.stringify(brokerResponse, null, 2)
-      );
-
-      this._ws.send(JSON.stringify(brokerResponse));
-    } else {
-      // Fallback: send the message directly as JSON-RPC over WebSocket
-      this._ws.send(JSON.stringify(message));
-    }
-  }
-
-  /**
-   * Start heartbeat to keep connection alive
-   */
-  _startHeartbeat() {
-    setInterval(() => {
-      if (this._isConnected && this._ws.readyState === 1) {
-        this._ws.send(
-          JSON.stringify({
-            jsonrpc: '2.0',
-            method: 'kadi.ping'
-          })
-        );
-      }
-    }, 25000); // 25 seconds as per agentA.js
-  }
-
-  /**
-   * Close the broker connection
-   */
-  async close() {
-    if (this._ws) {
-      this._isConnected = false;
-      this._isServing = false;
-      this._ws.close();
-      this._ws = null;
-    }
-  }
-
-  /**
-   * Handle incoming tool calls from the broker using the original direct approach
-   * This preserves the working behavior while keeping the new listen()/send() methods available
-   */
-  async _handleToolCallDirect(message) {
-    const { toolName, args, requestId, from } = message.params;
-
-    console.error(`[BrokerTransport] Handling tool call: ${toolName}`);
-
-    try {
-      // Get the handler directly from the ability
-      if (!this.ability || !this.ability._handlers) {
-        throw new Error('No ability or handlers available');
-      }
-
-      const handler = this.ability._handlers.get(toolName);
-      if (!handler) {
-        throw new Error(`Tool '${toolName}' not found`);
-      }
-
-      // Call the handler directly with the arguments
-      console.error(
-        `[BrokerTransport] Calling handler for ${toolName} with args:`,
-        args
-      );
-      const result = await handler(args || {});
-      console.error(`[BrokerTransport] Handler result:`, result);
-
-      // Send the result back to the broker using native broker protocol
-      const response = {
-        jsonrpc: '2.0',
-        method: 'ability.result',
-        params: {
-          requestId,
-          toSessionId: from,
-          result
-        }
-      };
-
-      console.error(
-        `[BrokerTransport] Sending response:`,
-        JSON.stringify(response, null, 2)
-      );
-      this._ws.send(JSON.stringify(response));
-    } catch (error) {
-      console.error(`[BrokerTransport] Error handling tool call:`, error);
-
-      // Send error response
-      const errorResponse = {
-        jsonrpc: '2.0',
-        method: 'ability.result',
-        params: {
-          requestId,
-          toSessionId: from,
-          error: error.message
-        }
-      };
-
-      this._ws.send(JSON.stringify(errorResponse));
-    }
-  }
-
-  /**
-   * Helper function to notify listeners waiting for messages
-   */
-  _notifyListeners(listeners) {
-    const listenersToNotify = listeners.splice(0);
-    listenersToNotify.forEach((resolve) => resolve());
-  }
-
-  async _connect() {
-    return new Promise((resolve, reject) => {
-      this._ws = new WebSocket(this.brokerUrl);
-
-      this._ws.on('open', () => {
-        this._isConnected = true;
-        console.error(
-          `[BrokerTransport] Connected to broker at ${this.brokerUrl}`
-        );
-        resolve();
-      });
-
-      this._ws.on('error', (err) => {
-        console.error('[BrokerTransport] WebSocket error:', err.message || err);
-        console.error(
-          '[BrokerTransport] Failed to connect to broker at:',
-          this.brokerUrl
-        );
-        reject(
-          new Error(
-            `Failed to connect to broker at ${this.brokerUrl}: ${err.message || err}`
-          )
-        );
-      });
-
-      this._ws.on('close', () => {
-        this._isConnected = false;
-        console.error('[BrokerTransport] Disconnected from broker');
-      });
-    });
-  }
-
-  async _handshake() {
-    // Step 1: Send hello as agent (abilities connect as agents in the current broker)
-    const hello = Broker.hello({ role: 'agent' })
-      .id(this._idFactory.next())
-      .build();
-    this._ws.send(JSON.stringify(hello));
-
-    // Wait for hello response with nonce
-    const helloResponse = await this._waitForResponse(hello.id);
-    if (!helloResponse.result || !helloResponse.result.nonce) {
-      throw new Error('Invalid hello response from broker');
-    }
-
-    const nonce = helloResponse.result.nonce;
-    console.error(`[BrokerTransport] Received nonce: ${nonce}`);
-
-    // Step 2: Generate ephemeral keys and authenticate
-    const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
-    const publicKeyBase64 = publicKey
-      .export({ format: 'der', type: 'spki' })
-      .toString('base64');
-
-    const signature = crypto
-      .sign(null, Buffer.from(nonce), privateKey)
-      .toString('base64');
-
-    const authenticate = Broker.authenticate({
-      publicKeyBase64Der: publicKeyBase64,
-      privateKey, // This will be used to generate signature
-      nonce,
-      wantNewId: true
-    })
-      .id(this._idFactory.next())
-      .build();
-
-    console.error(`[BrokerTransport] Sending authentication...`);
-    this._ws.send(JSON.stringify(authenticate));
-
-    // Wait for authentication response
-    const authResponse = await this._waitForResponse(authenticate.id);
-    if (!authResponse.result || !authResponse.result.agentId) {
-      throw new Error(
-        `Authentication failed: ${JSON.stringify(authResponse.error)}`
-      );
-    }
-
-    console.error(
-      `[BrokerTransport] Authenticated as agent: ${authResponse.result.agentId}`
-    );
-
-    // Step 3: Register capabilities (extract tools from ability)
-    if (
-      this.ability &&
-      typeof this.ability.extractToolsForBroker === 'function'
-    ) {
-      try {
-        console.error('[BrokerTransport] Extracting tools from ability...');
-        const tools = await this.ability.extractToolsForBroker();
-        console.error(
-          `[BrokerTransport] Extracted tools:`,
-          JSON.stringify(tools, null, 2)
-        );
-
-        if (tools.length > 0) {
-          const registerCapabilities = Broker.registerCapabilities({
-            displayName: this.abilityName,
-            tools,
-            mailboxMode: 'persistent',
-            scopes: ['global']
-          })
-            .id(this._idFactory.next())
-            .build();
-
-          console.error(
-            `[BrokerTransport] Sending registration:`,
-            JSON.stringify(registerCapabilities, null, 2)
-          );
-          this._ws.send(JSON.stringify(registerCapabilities));
-
-          // Wait for registration response
-          const registrationResponse = await this._waitForResponse(
-            registerCapabilities.id
-          );
-          console.error(
-            `[BrokerTransport] Registration response:`,
-            JSON.stringify(registrationResponse, null, 2)
-          );
-
-          console.error(
-            `[BrokerTransport] Registered ${tools.length} capabilities with broker`
-          );
-        } else {
-          console.error(
-            '[BrokerTransport] No tools found, skipping capability registration'
-          );
-        }
-      } catch (err) {
-        console.error(
-          `[BrokerTransport] Failed to register capabilities: ${err.message}`
-        );
-        console.error(`[BrokerTransport] Error details:`, err);
-        throw err;
-      }
-    } else {
-      console.error(
-        '[BrokerTransport] No ability reference or extractToolsForBroker method not found'
-      );
-    }
-
-    console.error(
-      '[BrokerTransport] Handshake completed, ready to receive calls'
-    );
-
-    // Note: Authentication step would go here in a production system
-    // For now, abilities connect without explicit authentication
-  }
-
-  async _waitForResponse(messageId, timeoutMs = 5000) {
-    return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        reject(
-          new Error(`Timeout waiting for response to message ${messageId}`)
-        );
-      }, timeoutMs);
-
-      const handler = (data) => {
-        try {
-          const message = JSON.parse(data.toString());
-          if (message.id === messageId) {
-            clearTimeout(timeout);
-            this._ws.off('message', handler);
-            resolve(message);
-          }
-        } catch (err) {
-          // Ignore parsing errors for non-matching messages
-        }
-      };
-
-      this._ws.on('message', handler);
-    });
-  }
-
-  _notifyListeners() {
-    const listeners = this._listeners.splice(0);
-    listeners.forEach((resolve) => resolve());
-  }
-}
-
-// ──────────────────────────────────────────────────────────────────────────────
-// SERVER-SIDE COMPONENTS
-// ──────────────────────────────────────────────────────────────────────────────
-
-/**
- * Server-side message builders for responses
- */
-export const IpcResponse = {
-  /** Build a success response */
-  success(id, result) {
-    return { jsonrpc: '2.0', id, result };
-  },
-
-  /** Build an error response */
-  error(id, code, message, data = null) {
-    const error = { code, message };
-    if (data !== null) error.data = data;
-    return { jsonrpc: '2.0', id, error };
-  },
-
-  /** Common error responses */
-  methodNotFound(id, method) {
-    return this.error(id, -32601, `Method not found: ${method}`);
-  },
-
-  parseError(id) {
-    return this.error(id, -32700, 'Parse error');
-  },
-
-  internalError(id, message, data) {
-    return this.error(id, -32000, message || 'Internal error', data);
-  }
-};
-
-/**
- * Simple ability server that can work with any transport
- */
-export class IpcServer extends EventEmitter {
-  constructor(options = {}) {
-    super();
-    this.name = options.name || 'unnamed-ability';
-    this.version = options.version || '1.0.0';
-    this.description = options.description || '';
-    this._handlers = new Map();
-    this._transport = null;
-
-    // Register built-in discovery methods
-    this._registerBuiltins();
-  }
-
-  /**
-   * Register a method handler
-   */
-  method(name, handler) {
-    if (typeof name === 'object') {
-      // Batch registration
-      for (const [methodName, methodHandler] of Object.entries(name)) {
-        if (typeof methodHandler !== 'function') {
-          throw new TypeError(
-            `Handler for method "${methodName}" must be a function`
-          );
-        }
-        this._handlers.set(methodName, methodHandler);
-      }
-    } else {
-      if (typeof handler !== 'function') {
-        throw new TypeError(`Handler for method "${name}" must be a function`);
-      }
-      this._handlers.set(name, handler);
-    }
-    return this; // Chainable
-  }
-
-  /**
-   * Set the transport for this server
-   */
-  transport(transport) {
-    this._transport = transport;
-    return this;
-  }
-
-  /**
-   * Start serving requests
-   */
-  async serve() {
-    if (!this._transport) {
-      throw new Error(
-        'No transport configured. Use .transport(transport) first.'
-      );
-    }
-
-    this.emit('start', {
-      name: this.name,
-      version: this.version,
-      methods: Array.from(this._handlers.keys()).filter(
-        (m) => !m.startsWith('__kadi_')
-      )
-    });
-
-    try {
-      for await (const request of this._transport.listen()) {
-        await this._handleRequest(request);
-      }
-    } catch (error) {
-      this.emit('error', error);
-      throw error;
-    } finally {
-      this.emit('stop');
-    }
-  }
-
-  /**
-   * Handle a single request
-   */
-  async _handleRequest(request) {
-    try {
-      const { id, method, params = {} } = request;
-
-      this.emit('request', { id, method, params });
-
-      const handler = this._handlers.get(method);
-      if (!handler) {
-        const response = IpcResponse.methodNotFound(id, method);
-        await this._transport.send(response);
-        this.emit('response', { id, error: response.error });
-        return;
-      }
-
-      try {
-        const result = await handler(params);
-        const response = IpcResponse.success(id, result);
-        await this._transport.send(response);
-        this.emit('response', { id, result });
-      } catch (handlerError) {
-        const response = IpcResponse.internalError(
-          id,
-          handlerError.message,
-          handlerError.stack
-        );
-        await this._transport.send(response);
-        this.emit('response', { id, error: response.error });
-        this.emit('handler-error', { method, error: handlerError });
-      }
-    } catch (protocolError) {
-      this.emit('protocol-error', protocolError);
-
-      if (request?.id) {
-        try {
-          const response = IpcResponse.parseError(request.id);
-          await this._transport.send(response);
-        } catch {
-          // Ignore write errors - connection might be broken
-        }
-      }
-    }
-  }
-
-  /**
-   * Register built-in discovery methods
-   */
-  _registerBuiltins() {
-    this._handlers.set('__kadi_init', async () => ({
-      name: this.name,
-      version: this.version,
-      description: this.description,
-      functions: this._getFunctionDescriptions()
-    }));
-
-    this._handlers.set('__kadi_discover', async () => ({
-      functions: this._getFunctionDescriptions()
-    }));
-  }
-
-  /**
-   * Get function descriptions for discovery
-   */
-  _getFunctionDescriptions() {
-    const functions = {};
-    for (const [name, handler] of this._handlers) {
-      if (name.startsWith('__kadi_')) continue;
-
-      functions[name] = {
-        description: handler.description || `Handler for ${name}`,
-        inputSchema: handler.inputSchema || { type: 'object' },
-        outputSchema: handler.outputSchema || { type: 'object' }
-      };
-    }
-    return functions;
-  }
-
-  /**
-   * Add metadata to a handler function
-   */
-  describe(handler, metadata) {
-    Object.assign(handler, metadata);
-    return handler;
-  }
-
-  /**
-   * Static factory method
-   */
-  static create(options) {
-    return new IpcServer(options);
-  }
-}
-
-// ──────────────────────────────────────────────────────────────────────────────
-// CLIENT-SIDE COMPONENTS
-// ──────────────────────────────────────────────────────────────────────────────
-export const Ipc = {
-  /** __kadi_init — Initialize the child process context. */
-  init(params = {}, rpc) {
-    const b = new MsgBuilder(methodNames.init).params(params);
-    return rpc ? b.send(rpc) : b;
-  },
-
-  /** __kadi_discover — Ask the child to enumerate capabilities. */
-  discover(params = {}, rpc) {
-    const b = new MsgBuilder(methodNames.discover).params(params);
-    return rpc ? b.send(rpc) : b;
-  },
-
-  /** Call any ability method explicitly. */
-  call(method, params = {}, rpc) {
-    if (!method) throw new Error('Ipc.call: method is required');
-    const b = new MsgBuilder(String(method)).params(params);
-    return rpc ? b.send(rpc) : b;
-  },
-
-  /** Notification (fire‑and‑forget). */
-  notify(method, params = {}, rpc) {
-    if (!method) throw new Error('Ipc.notify: method is required');
-    const b = new MsgBuilder(String(method))
-      .params(params)
-      .asNotification(true);
-    return rpc ? b.notifyWith(rpc) : b;
-  },
-
-  /** Bind your rpc once and get call‑through functions. */
-  with(rpc) {
-    return {
-      init: (params = {}) => Ipc.init(params, rpc),
-      discover: (params = {}) => Ipc.discover(params, rpc),
-      call: (method, params = {}) => Ipc.call(method, params, rpc),
-      notify: (method, params = {}) => Ipc.notify(method, params, rpc)
-    };
-  }
-};
-
-const IpcMessageBuilder = {
-  // Client-side
-  MsgBuilder,
-  Ipc,
-
-  // Server-side
-  IpcServer,
-  IpcResponse,
-
-  // Transport layer
-  BaseTransport,
-  StdioTransport,
-  BrokerTransport,
-  StdioFrameReader,
-  StdioFrameWriter,
-
-  // Configuration
-  configureMethods,
-  _methodNames: methodNames
-};
-
-export default IpcMessageBuilder;
-export { FRAME_HEADERS, FRAME_VALUES };