@kb-labs/adapters 0.5.0

package/packages/adapters-transport/src/ipc-transport.ts

@@ -0,0 +1,228 @@
+/**
+ * @module @kb-labs/core-runtime/transport
+ * IPC transport implementation using process.send/process.on('message').
+ *
+ * This transport is used for communication between parent (CLI) and
+ * child (sandbox worker) processes created by child_process.fork().
+ *
+ * Features:
+ * - Thread-safe: Uses request IDs to match responses with requests
+ * - Timeout enforcement: Rejects calls that exceed timeout
+ * - Error propagation: Deserializes errors from parent
+ * - Cleanup: Properly removes listeners on close()
+ *
+ * @example
+ * ```typescript
+ * import { IPCTransport } from '@kb-labs/core-runtime/transport';
+ *
+ * // In child process
+ * const transport = new IPCTransport({ timeout: 10000 });
+ *
+ * const response = await transport.send({
+ *   type: 'adapter:call',
+ *   requestId: 'uuid-123',
+ *   adapter: 'vectorStore',
+ *   method: 'search',
+ *   args: [[0.1, 0.2, 0.3], 10],
+ * });
+ *
+ * await transport.close();
+ * ```
+ */
+
+import type { AdapterCall, AdapterResponse } from "./types.js";
+import { isAdapterResponse } from "./types.js";
+import {
+  type ITransport,
+  type TransportConfig,
+  type PendingRequest,
+  TransportError,
+  TimeoutError,
+} from "./transport.js";
+
+// Re-export TransportConfig for convenience
+export type { TransportConfig };
+
+/**
+ * IPC transport using process.send/process.on('message').
+ *
+ * Requires:
+ * - process.send() must be available (running as forked child)
+ * - Parent process must listen for messages and respond
+ *
+ * Thread-safety:
+ * - Uses Map for pending requests (safe for concurrent access in single thread)
+ * - Uses request IDs to match responses (no race conditions)
+ *
+ * Limitations:
+ * - Only works in forked child processes (not worker threads)
+ * - Parent must implement IPCServer to handle calls
+ * - Message size limited by Node.js IPC buffer (typically 1MB)
+ */
+export class IPCTransport implements ITransport {
+  private pending = new Map<string, PendingRequest>();
+  private messageHandler: (msg: unknown) => void;
+  private closed = false;
+
+  constructor(private config: TransportConfig = {}) {
+    // Bind handler to preserve 'this' context
+    this.messageHandler = this.handleMessage.bind(this);
+
+    // Listen for responses from parent
+    process.on("message", this.messageHandler);
+
+    // Check if IPC channel is available
+    if (!process.send) {
+      throw new TransportError(
+        "No IPC channel available. IPCTransport can only be used in forked child processes.",
+      );
+    }
+  }
+
+  async send(call: AdapterCall): Promise<AdapterResponse> {
+    if (this.closed) {
+      throw new TransportError("Transport is closed");
+    }
+
+    // Determine timeout (call-specific > config default > 30s)
+    const timeout = call.timeout ?? this.config.timeout ?? 30000;
+
+    return new Promise((resolve, reject) => {
+      // Create timeout timer
+      const timer = setTimeout(() => {
+        this.pending.delete(call.requestId);
+        reject(
+          new TimeoutError(
+            `Adapter call timed out after ${timeout}ms`,
+            timeout,
+          ),
+        );
+      }, timeout);
+
+      // Store pending request
+      this.pending.set(call.requestId, { resolve, reject, timer });
+
+      // Try to send message, with backpressure handling
+      this.trySendWithBackpressure(call, 0).catch((error) => {
+        const pending = this.pending.get(call.requestId);
+        if (pending) {
+          clearTimeout(pending.timer);
+          this.pending.delete(call.requestId);
+          reject(error);
+        }
+      });
+    });
+  }
+
+  /**
+   * Try to send IPC message with backpressure handling.
+   * If backpressure detected, waits and retries with exponential backoff.
+   *
+   * Note: Node.js IPC 'drain' event is unreliable, so we use sleep-based backoff instead.
+   *
+   * @param call - Adapter call to send
+   * @param retryCount - Current retry attempt (for exponential backoff)
+   */
+  private async trySendWithBackpressure(
+    call: AdapterCall,
+    retryCount: number,
+  ): Promise<void> {
+    const maxRetries = 20;
+    const baseDelayMs = 50;
+
+    try {
+      // process.send() is guaranteed to exist (checked in constructor)
+      // Returns false if backpressure detected (buffer full)
+      const sent = process.send!(call);
+
+      if (sent) {
+        // Message sent successfully
+        return;
+      }
+
+      // Backpressure detected
+      if (retryCount >= maxRetries) {
+        throw new TransportError(
+          `Failed to send IPC message after ${maxRetries} retries: persistent backpressure`,
+        );
+      }
+
+      // Wait with exponential backoff (sleep instead of drain event)
+      const delay = Math.min(baseDelayMs * Math.pow(1.5, retryCount), 5000); // Cap at 5s
+      await new Promise((resolve) => {
+        setTimeout(resolve, delay);
+      });
+
+      // Retry sending
+      return this.trySendWithBackpressure(call, retryCount + 1);
+    } catch (error) {
+      // Synchronous error (e.g., message too large, serialization error, channel closed)
+      if (error instanceof TransportError) {
+        throw error;
+      }
+      throw new TransportError(
+        `Failed to send IPC message: ${error}`,
+        error as Error,
+      );
+    }
+  }
+
+  private handleMessage(msg: unknown) {
+    // Ignore non-response messages
+    if (!isAdapterResponse(msg)) {
+      return;
+    }
+
+    // Find pending request
+    const pending = this.pending.get(msg.requestId);
+    if (!pending) {
+      // Response for unknown request (may have timed out)
+      return;
+    }
+
+    // Clear timeout and remove from pending
+    clearTimeout(pending.timer);
+    this.pending.delete(msg.requestId);
+
+    // Resolve with response (caller will check for error field)
+    pending.resolve(msg);
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) {
+      return;
+    }
+
+    this.closed = true;
+
+    // Remove message listener
+    process.off("message", this.messageHandler);
+
+    // Reject all pending requests
+    for (const [_requestId, pending] of this.pending) {
+      clearTimeout(pending.timer);
+      pending.reject(new TransportError("Transport closed"));
+    }
+    this.pending.clear();
+  }
+
+  isClosed(): boolean {
+    return this.closed;
+  }
+}
+
+/**
+ * Create IPCTransport with default configuration.
+ *
+ * @example
+ * ```typescript
+ * import { createIPCTransport } from '@kb-labs/core-runtime/transport';
+ *
+ * const transport = createIPCTransport();
+ * // Use transport...
+ * await transport.close();
+ * ```
+ */
+export function createIPCTransport(config?: TransportConfig): IPCTransport {
+  return new IPCTransport(config);
+}

package/packages/adapters-transport/src/transport.ts

@@ -0,0 +1,224 @@
+/**
+ * @module @kb-labs/core-runtime/transport
+ * Abstract transport layer for cross-process adapter communication.
+ *
+ * Provides a transport-agnostic interface for sending adapter calls
+ * between parent and child processes. Implementations can use:
+ * - IPC (process.send/process.on('message'))
+ * - HTTP REST API
+ * - Docker exec
+ * - gRPC
+ * - WebSockets
+ *
+ * @example
+ * ```typescript
+ * import { ITransport, IPCTransport } from '@kb-labs/core-runtime/transport';
+ *
+ * const transport: ITransport = new IPCTransport();
+ * const response = await transport.send({
+ *   type: 'adapter:call',
+ *   requestId: 'uuid-123',
+ *   adapter: 'vectorStore',
+ *   method: 'search',
+ *   args: [[0.1, 0.2, 0.3], 10],
+ * });
+ * ```
+ */
+
+import type { AdapterCall, AdapterResponse } from "./types.js";
+
+/**
+ * Transport configuration options.
+ */
+export interface TransportConfig {
+  /**
+   * Default timeout for adapter calls in milliseconds.
+   * @default 30000 (30 seconds)
+   */
+  timeout?: number;
+
+  /**
+   * Number of retry attempts for transient errors.
+   * @default 0 (no retries)
+   */
+  retries?: number;
+
+  /**
+   * Delay between retry attempts in milliseconds.
+   * @default 1000 (1 second)
+   */
+  retryDelay?: number;
+
+  /**
+   * Exponential backoff multiplier for retries.
+   * @default 2 (doubles delay each retry)
+   */
+  backoffMultiplier?: number;
+}
+
+/**
+ * Abstract transport for sending adapter calls.
+ *
+ * Implementations must handle:
+ * - Reliable message delivery
+ * - Timeout enforcement
+ * - Error propagation
+ * - Resource cleanup
+ *
+ * Thread-safety: Implementations must be safe to call concurrently
+ * from multiple async contexts.
+ */
+export interface ITransport {
+  /**
+   * Send adapter call and await response.
+   *
+   * @param call - Adapter method call to send
+   * @returns Response with result or error
+   * @throws TransportError if communication fails
+   * @throws TimeoutError if timeout exceeded
+   * @throws SerializationError if message cannot be serialized
+   *
+   * @example
+   * ```typescript
+   * const call: AdapterCall = {
+   *   type: 'adapter:call',
+   *   requestId: 'uuid-123',
+   *   adapter: 'vectorStore',
+   *   method: 'search',
+   *   args: [[0.1, 0.2, 0.3], 10],
+   *   timeout: 5000,
+   * };
+   *
+   * const response = await transport.send(call);
+   * if (response.error) {
+   *   throw deserialize(response.error);
+   * }
+   * return deserialize(response.result);
+   * ```
+   */
+  send(call: AdapterCall): Promise<AdapterResponse>;
+
+  /**
+   * Close transport and cleanup resources.
+   *
+   * After close():
+   * - No new calls can be sent
+   * - Pending calls are rejected with TransportError
+   * - Listeners/connections are cleaned up
+   *
+   * @example
+   * ```typescript
+   * await transport.close();
+   * // All pending calls rejected
+   * // transport.send() will throw TransportError
+   * ```
+   */
+  close(): Promise<void>;
+
+  /**
+   * Check if transport is closed.
+   */
+  isClosed(): boolean;
+}
+
+/**
+ * Base error for transport failures.
+ */
+export class TransportError extends Error {
+  public override readonly cause?: Error;
+
+  constructor(message: string, cause?: Error) {
+    super(message);
+    this.name = "TransportError";
+    this.cause = cause;
+    if (cause) {
+      this.stack = `${this.stack}\nCaused by: ${cause.stack}`;
+    }
+  }
+}
+
+/**
+ * Error thrown when adapter call times out.
+ */
+export class TimeoutError extends TransportError {
+  public readonly timeoutMs: number;
+
+  constructor(message: string, timeoutMs: number) {
+    super(message);
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+/**
+ * Error thrown when circuit breaker is open.
+ */
+export class CircuitOpenError extends TransportError {
+  constructor(message: string) {
+    super(message);
+    this.name = "CircuitOpenError";
+  }
+}
+
+/**
+ * Check if error is retryable (transient failure).
+ *
+ * Retryable errors:
+ * - Network timeouts (TimeoutError)
+ * - Connection errors (ECONNRESET, ECONNREFUSED, ETIMEDOUT)
+ * - Temporary server errors (503 Service Unavailable)
+ *
+ * Non-retryable errors:
+ * - Invalid requests (400 Bad Request)
+ * - Authentication failures (401, 403)
+ * - Not found (404)
+ * - Application errors from adapter (e.g., VectorStoreError)
+ *
+ * @param error - Error to check
+ * @returns true if error should be retried
+ */
+export function isRetryableError(error: Error): boolean {
+  // Timeout errors are retryable
+  if (error instanceof TimeoutError) {
+    return true;
+  }
+
+  // Circuit breaker open is NOT retryable (wait for half-open state)
+  if (error instanceof CircuitOpenError) {
+    return false;
+  }
+
+  // Check error code for network errors
+  const code = (error as any).code;
+  if (code) {
+    const retryableCodes = [
+      "ECONNRESET", // Connection reset
+      "ECONNREFUSED", // Connection refused
+      "ETIMEDOUT", // Operation timed out
+      "ENOTFOUND", // DNS lookup failed
+      "EAI_AGAIN", // DNS temporary failure
+    ];
+    return retryableCodes.includes(code);
+  }
+
+  // Check HTTP status for server errors
+  const status = (error as any).status || (error as any).statusCode;
+  if (status) {
+    // 503 Service Unavailable is retryable
+    // 429 Too Many Requests is retryable
+    return status === 503 || status === 429;
+  }
+
+  // Default: not retryable
+  return false;
+}
+
+/**
+ * Internal pending request tracking.
+ * Used by transport implementations to match responses with requests.
+ */
+export interface PendingRequest {
+  resolve: (response: AdapterResponse) => void;
+  reject: (error: Error) => void;
+  timer: NodeJS.Timeout;
+}

package/packages/adapters-transport/src/types.ts

@@ -0,0 +1,92 @@
+/**
+ * Core types for transport layer.
+ * Extracted from @kb-labs/core-platform to avoid circular dependencies.
+ */
+
+export interface SerializableBuffer {
+  __type: "Buffer";
+  data: string;
+}
+
+export interface SerializableDate {
+  __type: "Date";
+  iso: string;
+}
+
+export interface SerializableError {
+  __type: "Error";
+  name: string;
+  message: string;
+  stack?: string;
+  code?: string;
+}
+
+export type SerializableValue =
+  | null
+  | boolean
+  | number
+  | string
+  | SerializableBuffer
+  | SerializableDate
+  | SerializableError
+  | SerializableArray
+  | SerializableObject;
+
+export type SerializableArray = SerializableValue[];
+export type SerializableObject = { [key: string]: SerializableValue };
+
+export type AdapterType =
+  | "vectorStore"
+  | "cache"
+  | "llm"
+  | "embeddings"
+  | "storage"
+  | "logger"
+  | "analytics"
+  | "eventBus"
+  | "invoke"
+  | "artifacts";
+
+export interface AdapterCallContext {
+  traceId?: string;
+  sessionId?: string;
+  pluginId?: string;
+  workspaceId?: string;
+  tenantId?: string;
+  permissions?: {
+    adapters?: string[];
+    storagePaths?: string[];
+    networkHosts?: string[];
+  };
+}
+
+export const IPC_PROTOCOL_VERSION = 2;
+
+export interface AdapterCall {
+  version: number;
+  type: "adapter:call";
+  requestId: string;
+  adapter: AdapterType;
+  method: string;
+  args: SerializableValue[];
+  timeout?: number;
+  context?: AdapterCallContext;
+}
+
+export interface AdapterResponse {
+  type: "adapter:response";
+  requestId: string;
+  result?: SerializableValue;
+  error?: SerializableError;
+}
+
+export function isAdapterResponse(msg: unknown): msg is AdapterResponse {
+  return (
+    typeof msg === "object" &&
+    msg !== null &&
+    "type" in msg &&
+    (msg as any).type === "adapter:response" &&
+    "requestId" in msg &&
+    typeof (msg as any).requestId === "string"
+  );
+}