@kadi.build/core 0.9.0 → 0.11.0

package/src/stdio-framing.ts

@@ -0,0 +1,227 @@
+/**
+ * Stdio message framing for kadi-core
+ *
+ * Shared Content-Length framing used by both the stdio transport (ability loading)
+ * and the ProcessManager (bridge mode).
+ *
+ * Protocol (same as LSP - Language Server Protocol):
+ * - Each message is prefixed with "Content-Length: <bytes>\r\n\r\n"
+ * - The content is JSON (JSON-RPC 2.0 format)
+ *
+ * This module is language-agnostic — any process that speaks this protocol
+ * can communicate with these readers/writers.
+ */
+
+import type { Readable, Writable } from 'stream';
+import type { JsonRpcRequest, JsonRpcResponse, JsonRpcNotification } from './types.js';
+import { KadiError } from './errors.js';
+
+export type { JsonRpcNotification };
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// MESSAGE READER (Content-Length framing)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Reads JSON-RPC messages from a stream using Content-Length framing.
+ *
+ * Uses Buffer (not string) for binary safety. Handles partial messages
+ * across chunks and recovers from malformed headers.
+ *
+ * Message format:
+ * ```
+ * Content-Length: 42\r\n
+ * \r\n
+ * {"jsonrpc":"2.0","id":1,"result":{...}}
+ * ```
+ */
+export class StdioMessageReader {
+  private buffer = Buffer.alloc(0);
+  private static readonly HEADER_END = '\r\n\r\n';
+  private static readonly HEADER_END_LENGTH = 4; // \r\n\r\n
+  private static readonly CONTENT_LENGTH_MARKER = Buffer.from('Content-Length:');
+  private static readonly CONTENT_LENGTH_PATTERN = /Content-Length:\s*(\d+)/;
+
+  private waiters: Array<{
+    id: string | number;
+    resolve: (response: JsonRpcResponse) => void;
+    reject: (error: Error) => void;
+    timeout: ReturnType<typeof setTimeout>;
+  }> = [];
+
+  /** Handler for event notifications */
+  private notificationHandler: ((notification: JsonRpcNotification) => void) | null = null;
+
+  constructor(stream: Readable, private timeoutMs: number = 600000) {
+    stream.on('data', (chunk: Buffer) => this.onData(chunk));
+  }
+
+  /**
+   * Set handler for notifications (messages without id).
+   */
+  setNotificationHandler(handler: (notification: JsonRpcNotification) => void): void {
+    this.notificationHandler = handler;
+  }
+
+  /**
+   * Handle incoming data from the stream.
+   */
+  private onData(chunk: Buffer): void {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+    this.processBuffer();
+  }
+
+  /**
+   * Process the buffer, extracting complete messages.
+   */
+  private processBuffer(): void {
+    let message: JsonRpcResponse | null;
+    while ((message = this.tryReadSingleMessage()) !== null) {
+      this.dispatchMessage(message);
+    }
+  }
+
+  /**
+   * Try to read a single complete message from the buffer.
+   * @returns Parsed message, or null if no complete message available
+   */
+  private tryReadSingleMessage(): JsonRpcResponse | null {
+    // Look for header end marker
+    const headerEndIndex = this.buffer.indexOf(StdioMessageReader.HEADER_END);
+    if (headerEndIndex === -1) {
+      return null; // No complete header yet
+    }
+
+    // Parse Content-Length from header
+    const header = this.buffer.slice(0, headerEndIndex).toString('utf8');
+    const match = header.match(StdioMessageReader.CONTENT_LENGTH_PATTERN);
+    if (!match?.[1]) {
+      // Invalid header - skip to next potential header
+      this.skipToNextHeader();
+      return null;
+    }
+
+    const contentLength = parseInt(match[1], 10);
+    const contentStart = headerEndIndex + StdioMessageReader.HEADER_END_LENGTH;
+    const contentEnd = contentStart + contentLength;
+
+    // Check if we have the complete message
+    if (this.buffer.length < contentEnd) {
+      return null; // Need more data
+    }
+
+    // Extract and parse JSON
+    const content = this.buffer.slice(contentStart, contentEnd).toString('utf8');
+    this.buffer = this.buffer.slice(contentEnd); // Remove processed data
+
+    try {
+      return JSON.parse(content) as JsonRpcResponse;
+    } catch (error) {
+      // Invalid JSON - log error so developer knows something's wrong
+      console.error('[KADI] Failed to parse message from child process:', error);
+      console.error('[KADI] Raw content (truncated):', content.slice(0, 200));
+      return null;
+    }
+  }
+
+  /**
+   * Skip to next potential header (error recovery).
+   * Called when we encounter a malformed header.
+   */
+  private skipToNextHeader(): void {
+    const nextHeaderIndex = this.buffer.indexOf(StdioMessageReader.CONTENT_LENGTH_MARKER, 1);
+
+    if (nextHeaderIndex === -1) {
+      this.buffer = Buffer.alloc(0); // No more headers, clear buffer
+    } else {
+      this.buffer = this.buffer.slice(nextHeaderIndex);
+    }
+  }
+
+  /**
+   * Dispatch a parsed message to waiting handlers or notification handler.
+   */
+  private dispatchMessage(message: JsonRpcResponse | JsonRpcNotification): void {
+    // Check if this is a notification (no id field)
+    if (!('id' in message) || message.id === undefined) {
+      // It's a notification - route to notification handler
+      if (this.notificationHandler) {
+        this.notificationHandler(message as JsonRpcNotification);
+      }
+      return;
+    }
+
+    // It's a response - find and remove waiter for this message id
+    const waiterIndex = this.waiters.findIndex((w) => w.id === message.id);
+    if (waiterIndex === -1) {
+      return; // No one waiting for this response
+    }
+
+    // splice returns removed elements - use destructuring to get the waiter
+    const [waiter] = this.waiters.splice(waiterIndex, 1);
+    if (!waiter) {
+      return;
+    }
+
+    clearTimeout(waiter.timeout);
+    waiter.resolve(message);
+  }
+
+  /**
+   * Wait for a response with a specific id.
+   */
+  waitForResponse(id: string | number, timeoutOverride?: number): Promise<JsonRpcResponse> {
+    const effectiveTimeout = timeoutOverride ?? this.timeoutMs;
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        // Remove from waiters
+        const index = this.waiters.findIndex((w) => w.id === id);
+        if (index !== -1) {
+          this.waiters.splice(index, 1);
+        }
+        reject(new KadiError(
+          `Timeout waiting for response to request ${id}`,
+          'TIMEOUT',
+          { requestId: id, timeoutMs: effectiveTimeout }
+        ));
+      }, effectiveTimeout);
+
+      this.waiters.push({ id, resolve, reject, timeout });
+    });
+  }
+
+  /**
+   * Cancel all pending waiters (for cleanup).
+   * @param error - Optional error to reject with (defaults to generic close error)
+   */
+  cancelAll(error?: Error): void {
+    const rejectError = error ?? new KadiError('Connection closed', 'STDIO_ERROR');
+    for (const waiter of this.waiters) {
+      clearTimeout(waiter.timeout);
+      waiter.reject(rejectError);
+    }
+    this.waiters = [];
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// MESSAGE WRITER (Content-Length framing)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Writes JSON-RPC messages to a stream using Content-Length framing.
+ */
+export class StdioMessageWriter {
+  constructor(private stream: Writable) {}
+
+  /**
+   * Write a message to the stream.
+   */
+  write(message: JsonRpcRequest): void {
+    const json = JSON.stringify(message);
+    const contentLength = Buffer.byteLength(json, 'utf-8');
+    const header = `Content-Length: ${contentLength}\r\n\r\n`;
+
+    this.stream.write(header + json);
+  }
+}

package/src/transports/stdio.ts

@@ -19,11 +19,11 @@
  */
 
 import { spawn, type ChildProcess } from 'child_process';
-import type { Readable, Writable } from 'stream';
 import { z } from 'zod';
-import type { LoadedAbility, InvokeOptions, ToolDefinition, JsonRpcRequest, JsonRpcResponse, EventHandler } from '../types.js';
+import type { LoadedAbility, InvokeOptions, ToolDefinition, EventHandler } from '../types.js';
 import { KadiError } from '../errors.js';
 import * as protocol from '../protocol.js';
+import { StdioMessageReader, StdioMessageWriter } from '../stdio-framing.js';
 
 /** Schema for event notification params */
 const EventNotificationParams = z.object({
@@ -31,223 +31,6 @@ const EventNotificationParams = z.object({
   data: z.unknown(),
 });
 
-/**
- * JSON-RPC notification (no id field).
- */
-interface JsonRpcNotification {
-  jsonrpc: '2.0';
-  method: string;
-  params?: unknown;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// MESSAGE READER (Content-Length framing)
-// ═══════════════════════════════════════════════════════════════════════════════
-
-/**
- * Reads JSON-RPC messages from a stream using Content-Length framing.
- *
- * Uses Buffer (not string) for binary safety. Handles partial messages
- * across chunks and recovers from malformed headers.
- *
- * Message format:
- * ```
- * Content-Length: 42\r\n
- * \r\n
- * {"jsonrpc":"2.0","id":1,"result":{...}}
- * ```
- */
-class StdioReader {
-  private buffer = Buffer.alloc(0);
-  private static readonly HEADER_END = '\r\n\r\n';
-  private static readonly HEADER_END_LENGTH = 4; // \r\n\r\n
-  private static readonly CONTENT_LENGTH_MARKER = Buffer.from('Content-Length:');
-  private static readonly CONTENT_LENGTH_PATTERN = /Content-Length:\s*(\d+)/;
-
-  private waiters: Array<{
-    id: string | number;
-    resolve: (response: JsonRpcResponse) => void;
-    reject: (error: Error) => void;
-    timeout: ReturnType<typeof setTimeout>;
-  }> = [];
-
-  /** Handler for event notifications */
-  private notificationHandler: ((notification: JsonRpcNotification) => void) | null = null;
-
-  constructor(stream: Readable, private timeoutMs: number = 600000) {
-    stream.on('data', (chunk: Buffer) => this.onData(chunk));
-  }
-
-  /**
-   * Set handler for notifications (messages without id).
-   */
-  setNotificationHandler(handler: (notification: JsonRpcNotification) => void): void {
-    this.notificationHandler = handler;
-  }
-
-  /**
-   * Handle incoming data from the stream.
-   */
-  private onData(chunk: Buffer): void {
-    this.buffer = Buffer.concat([this.buffer, chunk]);
-    this.processBuffer();
-  }
-
-  /**
-   * Process the buffer, extracting complete messages.
-   */
-  private processBuffer(): void {
-    let message: JsonRpcResponse | null;
-    while ((message = this.tryReadSingleMessage()) !== null) {
-      this.dispatchMessage(message);
-    }
-  }
-
-  /**
-   * Try to read a single complete message from the buffer.
-   * @returns Parsed message, or null if no complete message available
-   */
-  private tryReadSingleMessage(): JsonRpcResponse | null {
-    // Look for header end marker
-    const headerEndIndex = this.buffer.indexOf(StdioReader.HEADER_END);
-    if (headerEndIndex === -1) {
-      return null; // No complete header yet
-    }
-
-    // Parse Content-Length from header
-    const header = this.buffer.slice(0, headerEndIndex).toString('utf8');
-    const match = header.match(StdioReader.CONTENT_LENGTH_PATTERN);
-    if (!match?.[1]) {
-      // Invalid header - skip to next potential header
-      this.skipToNextHeader();
-      return null;
-    }
-
-    const contentLength = parseInt(match[1], 10);
-    const contentStart = headerEndIndex + StdioReader.HEADER_END_LENGTH;
-    const contentEnd = contentStart + contentLength;
-
-    // Check if we have the complete message
-    if (this.buffer.length < contentEnd) {
-      return null; // Need more data
-    }
-
-    // Extract and parse JSON
-    const content = this.buffer.slice(contentStart, contentEnd).toString('utf8');
-    this.buffer = this.buffer.slice(contentEnd); // Remove processed data
-
-    try {
-      return JSON.parse(content) as JsonRpcResponse;
-    } catch (error) {
-      // Invalid JSON - log error so developer knows something's wrong
-      console.error('[KADI] Failed to parse message from child process:', error);
-      console.error('[KADI] Raw content (truncated):', content.slice(0, 200));
-      return null;
-    }
-  }
-
-  /**
-   * Skip to next potential header (error recovery).
-   * Called when we encounter a malformed header.
-   */
-  private skipToNextHeader(): void {
-    const nextHeaderIndex = this.buffer.indexOf(StdioReader.CONTENT_LENGTH_MARKER, 1);
-
-    if (nextHeaderIndex === -1) {
-      this.buffer = Buffer.alloc(0); // No more headers, clear buffer
-    } else {
-      this.buffer = this.buffer.slice(nextHeaderIndex);
-    }
-  }
-
-  /**
-   * Dispatch a parsed message to waiting handlers or notification handler.
-   */
-  private dispatchMessage(message: JsonRpcResponse | JsonRpcNotification): void {
-    // Check if this is a notification (no id field)
-    if (!('id' in message) || message.id === undefined) {
-      // It's a notification - route to notification handler
-      if (this.notificationHandler) {
-        this.notificationHandler(message as JsonRpcNotification);
-      }
-      return;
-    }
-
-    // It's a response - find and remove waiter for this message id
-    const waiterIndex = this.waiters.findIndex((w) => w.id === message.id);
-    if (waiterIndex === -1) {
-      return; // No one waiting for this response
-    }
-
-    // splice returns removed elements - use destructuring to get the waiter
-    const [waiter] = this.waiters.splice(waiterIndex, 1);
-    if (!waiter) {
-      return;
-    }
-
-    clearTimeout(waiter.timeout);
-    waiter.resolve(message);
-  }
-
-  /**
-   * Wait for a response with a specific id.
-   */
-  waitForResponse(id: string | number, timeoutOverride?: number): Promise<JsonRpcResponse> {
-    const effectiveTimeout = timeoutOverride ?? this.timeoutMs;
-    return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        // Remove from waiters
-        const index = this.waiters.findIndex((w) => w.id === id);
-        if (index !== -1) {
-          this.waiters.splice(index, 1);
-        }
-        reject(new KadiError(
-          `Timeout waiting for response to request ${id}`,
-          'TIMEOUT',
-          { requestId: id, timeoutMs: effectiveTimeout }
-        ));
-      }, effectiveTimeout);
-
-      this.waiters.push({ id, resolve, reject, timeout });
-    });
-  }
-
-  /**
-   * Cancel all pending waiters (for cleanup).
-   * @param error - Optional error to reject with (defaults to generic close error)
-   */
-  cancelAll(error?: Error): void {
-    const rejectError = error ?? new KadiError('Connection closed', 'STDIO_ERROR');
-    for (const waiter of this.waiters) {
-      clearTimeout(waiter.timeout);
-      waiter.reject(rejectError);
-    }
-    this.waiters = [];
-  }
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// MESSAGE WRITER (Content-Length framing)
-// ═══════════════════════════════════════════════════════════════════════════════
-
-/**
- * Writes JSON-RPC messages to a stream using Content-Length framing.
- */
-class StdioWriter {
-  constructor(private stream: Writable) {}
-
-  /**
-   * Write a message to the stream.
-   */
-  write(message: JsonRpcRequest): void {
-    const json = JSON.stringify(message);
-    const contentLength = Buffer.byteLength(json, 'utf-8');
-    const header = `Content-Length: ${contentLength}\r\n\r\n`;
-
-    this.stream.write(header + json);
-  }
-}
-
 // ═══════════════════════════════════════════════════════════════════════════════
 // STDIO TRANSPORT
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -319,8 +102,8 @@ export async function loadStdioTransport(
     );
   }
 
-  const reader = new StdioReader(proc.stdout, timeoutMs);
-  const writer = new StdioWriter(proc.stdin);
+  const reader = new StdioMessageReader(proc.stdout, timeoutMs);
+  const writer = new StdioMessageWriter(proc.stdin);
   let idCounter = 1;
   let isShutdown = false;