@kb-labs/adapters 0.5.0

package/packages/adapters-transport/src/unix-socket-server.ts

@@ -0,0 +1,193 @@
+/**
+ * @module @kb-labs/adapters-transport
+ * Unix Socket server for handling adapter calls from child processes.
+ *
+ * This server runs in the parent process and handles incoming adapter
+ * method calls from child processes connected via Unix sockets.
+ *
+ * @example
+ * ```typescript
+ * import { UnixSocketServer } from '@kb-labs/adapters-transport';
+ * import { usePlatform } from '@kb-labs/core-runtime';
+ *
+ * const server = new UnixSocketServer({ socketPath: '/tmp/kb-ipc.sock' });
+ *
+ * server.onCall(async (call) => {
+ *   const platform = usePlatform();
+ *   const adapter = platform.getAdapter(call.adapter);
+ *   const result = await adapter[call.method](...call.args);
+ *   return { requestId: call.requestId, result };
+ * });
+ *
+ * await server.start();
+ * ```
+ */
+
+import * as net from "net";
+import * as fs from "fs";
+import type { AdapterCall, AdapterResponse } from "./types.js";
+
+export interface UnixSocketServerConfig {
+  /** Path to Unix socket file (default: /tmp/kb-ipc.sock) */
+  socketPath?: string;
+}
+
+/**
+ * Unix Socket server for parent process.
+ *
+ * Listens for adapter calls from child processes and executes them
+ * on the real adapters in the parent process.
+ */
+export class UnixSocketServer {
+  private server: net.Server | null = null;
+  private clients = new Set<net.Socket>();
+  private callHandler?: (call: AdapterCall) => Promise<AdapterResponse>;
+  private socketPath: string;
+
+  constructor(private config: UnixSocketServerConfig = {}) {
+    this.socketPath = config.socketPath ?? "/tmp/kb-ipc.sock";
+  }
+
+  /**
+   * Register handler for incoming adapter calls.
+   *
+   * @param handler - Async function that executes adapter call and returns response
+   */
+  onCall(handler: (call: AdapterCall) => Promise<AdapterResponse>): void {
+    this.callHandler = handler;
+  }
+
+  /**
+   * Start listening for connections.
+   */
+  async start(): Promise<void> {
+    // Remove existing socket file if exists
+    if (fs.existsSync(this.socketPath)) {
+      fs.unlinkSync(this.socketPath);
+    }
+
+    return new Promise((resolve, reject) => {
+      this.server = net.createServer((socket) => {
+        this.handleClient(socket);
+      });
+
+      this.server.on("error", (error) => {
+        reject(error);
+      });
+
+      this.server.listen(this.socketPath, () => {
+        // Set socket permissions (readable/writable by all)
+        fs.chmodSync(this.socketPath, 0o666);
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Handle new client connection.
+   */
+  private handleClient(socket: net.Socket): void {
+    this.clients.add(socket);
+
+    let buffer = "";
+
+    socket.on("data", (data) => {
+      buffer += data.toString("utf8");
+
+      // Process all complete messages (newline-delimited)
+      let newlineIndex: number;
+      while ((newlineIndex = buffer.indexOf("\n")) !== -1) {
+        const line = buffer.slice(0, newlineIndex);
+        buffer = buffer.slice(newlineIndex + 1);
+
+        if (line.trim().length === 0) {
+          continue;
+        }
+
+        try {
+          const call = JSON.parse(line) as AdapterCall;
+          this.handleCall(socket, call);
+        } catch (error) {
+          console.error("[UnixSocketServer] Failed to parse message:", error);
+        }
+      }
+    });
+
+    socket.on("close", () => {
+      this.clients.delete(socket);
+    });
+
+    socket.on("error", (error) => {
+      console.error("[UnixSocketServer] Client socket error:", error);
+      this.clients.delete(socket);
+    });
+  }
+
+  /**
+   * Handle adapter call from client.
+   */
+  private async handleCall(
+    socket: net.Socket,
+    call: AdapterCall,
+  ): Promise<void> {
+    if (!this.callHandler) {
+      console.error("[UnixSocketServer] No call handler registered");
+      return;
+    }
+
+    try {
+      const response = await this.callHandler(call);
+      const message = JSON.stringify(response) + "\n";
+      socket.write(message, "utf8");
+    } catch (error) {
+      // Send error response
+      const errorResponse: AdapterResponse = {
+        type: "adapter:response",
+        requestId: call.requestId,
+        error: {
+          __type: "Error",
+          name: error instanceof Error ? error.name : "Error",
+          message: error instanceof Error ? error.message : String(error),
+          stack: error instanceof Error ? error.stack : undefined,
+        },
+      };
+      const message = JSON.stringify(errorResponse) + "\n";
+      socket.write(message, "utf8");
+    }
+  }
+
+  /**
+   * Stop server and close all connections.
+   */
+  async close(): Promise<void> {
+    // Close all client connections
+    for (const client of this.clients) {
+      client.destroy();
+    }
+    this.clients.clear();
+
+    // Close server
+    if (this.server) {
+      await new Promise<void>((resolve) => {
+        this.server!.close(() => {
+          resolve();
+        });
+      });
+      this.server = null;
+    }
+
+    // Remove socket file
+    if (fs.existsSync(this.socketPath)) {
+      fs.unlinkSync(this.socketPath);
+    }
+  }
+}
+
+/**
+ * Create UnixSocketServer.
+ */
+export function createUnixSocketServer(
+  config?: UnixSocketServerConfig,
+): UnixSocketServer {
+  return new UnixSocketServer(config);
+}

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

@@ -0,0 +1,280 @@
+/**
+ * @module @kb-labs/adapters-transport
+ * Unix Domain Socket transport for high-throughput IPC.
+ *
+ * Unix sockets provide 100-1000x better performance than process.send()
+ * for large messages (>16KB), making them ideal for bulk operations like
+ * VectorStore upsert with thousands of vectors.
+ *
+ * @example
+ * ```typescript
+ * import { UnixSocketTransport } from '@kb-labs/adapters-transport';
+ *
+ * // In child process
+ * const transport = new UnixSocketTransport({ socketPath: '/tmp/kb-ipc.sock' });
+ * const response = await transport.send(call);
+ * await transport.close();
+ * ```
+ */
+
+import * as net from "net";
+import type { AdapterCall, AdapterResponse } from "./types.js";
+import { isAdapterResponse } from "./types.js";
+import {
+  type ITransport,
+  type TransportConfig,
+  type PendingRequest,
+  TransportError,
+  TimeoutError,
+} from "./transport.js";
+
+/**
+ * Configuration for Unix Socket transport.
+ */
+export interface UnixSocketConfig extends TransportConfig {
+  /** Path to Unix socket file (default: /tmp/kb-ipc.sock) */
+  socketPath?: string;
+  /** Reconnect on disconnect (default: true) */
+  autoReconnect?: boolean;
+  /** Max reconnect attempts (default: 3) */
+  maxReconnectAttempts?: number;
+}
+
+/**
+ * Unix Domain Socket transport for high-performance IPC.
+ *
+ * Features:
+ * - 100-1000x faster than process.send() for large messages
+ * - No backpressure issues (TCP flow control handles it)
+ * - Auto-reconnect on connection loss
+ * - Message framing with newline delimiter
+ *
+ * Performance:
+ * - process.send(): ~16KB buffer, 250-300s for 40MB
+ * - Unix socket: ~1-2 GB/s throughput, <1s for 40MB
+ */
+export class UnixSocketTransport implements ITransport {
+  private socket: net.Socket | null = null;
+  private pending = new Map<string, PendingRequest>();
+  private closed = false;
+  private connecting = false;
+  private buffer = "";
+  private reconnectAttempts = 0;
+
+  constructor(private config: UnixSocketConfig = {}) {}
+
+  /**
+   * Connect to Unix socket server.
+   * Called lazily on first send() or explicitly.
+   */
+  async connect(): Promise<void> {
+    if (this.socket && !this.socket.destroyed) {
+      return; // Already connected
+    }
+
+    if (this.connecting) {
+      // Wait for existing connection attempt
+      await new Promise((resolve) => {
+        setTimeout(resolve, 100);
+      });
+      return this.connect();
+    }
+
+    this.connecting = true;
+
+    return new Promise((resolve, reject) => {
+      const socketPath = this.config.socketPath ?? "/tmp/kb-ipc.sock";
+
+      this.socket = net.connect(socketPath);
+
+      this.socket.on("connect", () => {
+        this.connecting = false;
+        this.reconnectAttempts = 0;
+        resolve();
+      });
+
+      this.socket.on("error", (error) => {
+        this.connecting = false;
+
+        // Try reconnect if enabled
+        const maxAttempts = this.config.maxReconnectAttempts ?? 3;
+        if (
+          this.config.autoReconnect !== false &&
+          this.reconnectAttempts < maxAttempts
+        ) {
+          this.reconnectAttempts++;
+          setTimeout(() => this.connect(), 1000 * this.reconnectAttempts);
+          return;
+        }
+
+        reject(
+          new TransportError(
+            `Unix socket connection failed: ${error.message}`,
+            error,
+          ),
+        );
+      });
+
+      this.socket.on("data", (data) => {
+        this.handleData(data);
+      });
+
+      this.socket.on("close", () => {
+        if (!this.closed && this.config.autoReconnect !== false) {
+          // Unexpected close, try reconnect
+          setTimeout(() => this.connect(), 1000);
+        }
+      });
+    });
+  }
+
+  async send(call: AdapterCall): Promise<AdapterResponse> {
+    if (this.closed) {
+      throw new TransportError("Transport is closed");
+    }
+
+    // Ensure connected
+    await this.connect();
+
+    if (!this.socket || this.socket.destroyed) {
+      throw new TransportError("Socket not available");
+    }
+
+    // Determine timeout
+    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 });
+
+      // Send via Unix socket (newline-delimited JSON)
+      const message = JSON.stringify(call) + "\n";
+
+      const written = this.socket!.write(message, "utf8", (error) => {
+        if (error) {
+          const pending = this.pending.get(call.requestId);
+          if (pending) {
+            clearTimeout(pending.timer);
+            this.pending.delete(call.requestId);
+            reject(
+              new TransportError(
+                `Failed to write to socket: ${error.message}`,
+                error,
+              ),
+            );
+          }
+        }
+      });
+
+      // Unix sockets handle backpressure via TCP flow control
+      // If write() returns false, 'drain' event will fire when ready
+      if (!written) {
+        this.socket!.once("drain", () => {
+          // Socket ready for more data (TCP handled backpressure)
+        });
+      }
+    });
+  }
+
+  /**
+   * Handle incoming data from Unix socket.
+   * Messages are newline-delimited JSON.
+   */
+  private handleData(data: Buffer): void {
+    this.buffer += data.toString("utf8");
+
+    // Process all complete messages (newline-delimited)
+    let newlineIndex: number;
+    while ((newlineIndex = this.buffer.indexOf("\n")) !== -1) {
+      const line = this.buffer.slice(0, newlineIndex);
+      this.buffer = this.buffer.slice(newlineIndex + 1);
+
+      if (line.trim().length === 0) {
+        continue;
+      }
+
+      try {
+        const msg = JSON.parse(line);
+        this.handleMessage(msg);
+      } catch (error) {
+        console.error("[UnixSocketTransport] Failed to parse message:", error);
+      }
+    }
+  }
+
+  private handleMessage(msg: unknown): void {
+    // 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
+    pending.resolve(msg);
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) {
+      return;
+    }
+
+    this.closed = true;
+
+    // Close socket
+    if (this.socket) {
+      this.socket.destroy();
+      this.socket = null;
+    }
+
+    // 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 UnixSocketTransport with configuration.
+ *
+ * @example
+ * ```typescript
+ * import { createUnixSocketTransport } from '@kb-labs/adapters-transport';
+ *
+ * const transport = createUnixSocketTransport({
+ *   socketPath: '/tmp/kb-ipc.sock',
+ *   timeout: 60000,
+ * });
+ * ```
+ */
+export function createUnixSocketTransport(
+  config?: UnixSocketConfig,
+): UnixSocketTransport {
+  return new UnixSocketTransport(config);
+}

package/packages/adapters-transport/tsconfig.build.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "baseUrl": ".",
+    "paths": {}
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules"
+  ]
+}

package/packages/adapters-transport/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@kb-labs/devkit/tsconfig/node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}

package/packages/adapters-transport/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsup';
+import nodePreset from '@kb-labs/devkit/tsup/node';
+
+export default defineConfig({
+  ...nodePreset,
+  tsconfig: 'tsconfig.build.json',
+  entry: ['src/index.ts', 'src/manifest.ts'],
+  dts: true,
+});

package/packages/adapters-vibeproxy/README.md

@@ -0,0 +1,159 @@
+# @kb-labs/adapters-vibeproxy
+
+> Part of [KB Labs](https://github.com/KirillBaranov/kb-labs) ecosystem. Works exclusively within KB Labs platform.
+
+VibeProxy local adapter supporting multiple LLM providers (Claude, GPT, etc.) through a unified interface.
+
+## Overview
+
+| Property | Value |
+|----------|-------|
+| **Implements** | `ILLM` |
+| **Type** | `core` |
+| **Requires** | None |
+| **Category** | AI |
+
+## Features
+
+- **Multi-Provider** - Claude, GPT, Gemini, and more via single interface
+- **Local Proxy** - Route through local VibeProxy server
+- **Function Calling** - Native tool support for all providers
+- **Model Switching** - Change provider by just changing model name
+
+## Installation
+
+```bash
+pnpm add @kb-labs/adapters-vibeproxy
+```
+
+## Configuration
+
+Add to your `kb.config.json`:
+
+```json
+{
+  "platform": {
+    "adapters": {
+      "llm": "@kb-labs/adapters-vibeproxy"
+    },
+    "adapterOptions": {
+      "llm": {
+        "baseURL": "http://localhost:8317",
+        "apiKey": "any-string",
+        "model": "claude-sonnet-4-20250514",
+        "timeout": 120000
+      }
+    }
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `baseURL` | `string` | `"http://localhost:8317"` | VibeProxy server URL |
+| `apiKey` | `string` | `"any-string"` | API key (any string works for local) |
+| `model` | `string` | `"claude-sonnet-4-20250514"` | Model to use |
+| `timeout` | `number` | `120000` | Request timeout in ms |
+
+## Usage
+
+### Via Platform (Recommended)
+
+```typescript
+import { usePlatform } from '@kb-labs/sdk';
+
+const platform = usePlatform();
+
+// Chat with Claude
+const response = await platform.llm.chat([
+  { role: 'user', content: 'Hello!' }
+]);
+
+// Switch to GPT by changing model
+const gptResponse = await platform.llm.chat(
+  [{ role: 'user', content: 'Hello!' }],
+  { model: 'gpt-4-turbo' }
+);
+
+// Function calling
+const result = await platform.llm.chatWithTools(
+  [{ role: 'user', content: 'What time is it?' }],
+  [{ name: 'getTime', parameters: { ... } }]
+);
+```
+
+### Standalone (Testing/Development)
+
+```typescript
+import { createAdapter } from '@kb-labs/adapters-vibeproxy';
+
+const llm = createAdapter({
+  baseURL: 'http://localhost:8317',
+  model: 'claude-sonnet-4-20250514'
+});
+
+const response = await llm.chat([
+  { role: 'user', content: 'Hello!' }
+]);
+```
+
+## Adapter Manifest
+
+```typescript
+{
+  id: 'vibeproxy-llm',
+  name: 'VibeProxy LLM',
+  version: '0.1.0',
+  implements: 'ILLM',
+  capabilities: {
+    streaming: false, // TODO: implement SSE streaming
+    custom: {
+      functionCalling: true,
+      multiProvider: true,
+    },
+  },
+}
+```
+
+## Supported Models
+
+| Provider | Model Examples |
+|----------|---------------|
+| **Anthropic** | `claude-sonnet-4-20250514`, `claude-3-opus-*` |
+| **OpenAI** | `gpt-4-turbo`, `gpt-3.5-turbo` |
+| **Google** | `gemini-pro`, `gemini-ultra` |
+
+## FAQ
+
+<details>
+<summary><strong>Q: How do I start VibeProxy locally?</strong></summary>
+
+See VibeProxy documentation for setup instructions. Default port is 8317.
+</details>
+
+<details>
+<summary><strong>Q: Why use VibeProxy instead of direct API?</strong></summary>
+
+- Single interface for multiple providers
+- Local caching and rate limiting
+- Request logging and analytics
+- Cost tracking across providers
+</details>
+
+<details>
+<summary><strong>Q: Is streaming supported?</strong></summary>
+
+Not yet. Streaming (SSE) is planned for a future release.
+</details>
+
+## Related Adapters
+
+| Adapter | Use Case |
+|---------|----------|
+| `@kb-labs/adapters-openai` | Direct OpenAI API access |
+
+## License
+
+[KB Public License v1.1](../../LICENSE) - KB Labs Team

package/packages/adapters-vibeproxy/eslint.config.js

@@ -0,0 +1,27 @@
+/**
+ * Standard ESLint configuration template
+ *
+ * This is the canonical template for all @kb-labs packages.
+ * DO NOT modify this file locally - it is synced from @kb-labs/devkit
+ *
+ * Customization guidelines:
+ * - DevKit preset already includes all standard ignores
+ * - Only add project-specific ignores if absolutely necessary
+ * - Document why custom ignores are needed
+ *
+ * @see https://github.com/kb-labs/devkit#eslint-configuration
+ */
+import nodePreset from '@kb-labs/devkit/eslint/node.js';
+
+export default [
+  ...nodePreset,
+
+  // OPTIONAL: Add project-specific ignores only if needed
+  // DevKit preset already ignores: dist/, coverage/, node_modules/, *.d.ts, scripts/, etc.
+  // {
+  //   ignores: [
+  //     // Add ONLY project-specific patterns here
+  //     // Example: '**/*.generated.ts',
+  //   ]
+  // }
+];