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

package/src/transport/IpcMessageBuilder.js

@@ -0,0 +1,1229 @@
+// 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 };