@usejarvis/brain 0.1.0

package/src/comms/example.ts

@@ -0,0 +1,129 @@
+/**
+ * Example usage of J.A.R.V.I.S. Communication Layer
+ *
+ * This demonstrates how to:
+ * 1. Start the WebSocket server
+ * 2. Set up Telegram bot integration
+ * 3. Handle messages from multiple channels
+ * 4. Relay LLM streaming responses
+ */
+
+import {
+  WebSocketServer,
+  ChannelManager,
+  TelegramAdapter,
+  StreamRelay,
+  type WSMessage,
+  type ChannelMessage,
+} from './index.ts';
+
+async function main() {
+  console.log('🤖 Starting J.A.R.V.I.S. Communication Layer...\n');
+
+  // 1. Initialize WebSocket server
+  const wsServer = new WebSocketServer(3142);
+
+  wsServer.setHandler({
+    async onMessage(msg: WSMessage) {
+      console.log('[WS] Received message:', msg.type);
+
+      if (msg.type === 'chat') {
+        // Echo back for demo
+        return {
+          type: 'chat' as const,
+          payload: {
+            reply: `You said: ${msg.payload}`,
+          },
+          id: msg.id,
+          timestamp: Date.now(),
+        };
+      }
+    },
+    onConnect() {
+      console.log('[WS] Client connected');
+    },
+    onDisconnect() {
+      console.log('[WS] Client disconnected');
+    },
+  });
+
+  wsServer.start();
+
+  // 2. Initialize Channel Manager
+  const channelManager = new ChannelManager();
+
+  // Set up unified message handler
+  channelManager.setHandler(async (message: ChannelMessage) => {
+    console.log(`\n[${message.channel.toUpperCase()}] Message from ${message.from}:`);
+    console.log(`  "${message.text}"`);
+
+    // Broadcast to WebSocket clients
+    wsServer.broadcast({
+      type: 'chat',
+      payload: {
+        channel: message.channel,
+        from: message.from,
+        text: message.text,
+      },
+      id: message.id,
+      timestamp: message.timestamp,
+    });
+
+    // Simple echo response for demo
+    return `Received your message: "${message.text}"`;
+  });
+
+  // 3. Register channels (Telegram only for demo)
+  const telegramToken = process.env.TELEGRAM_BOT_TOKEN;
+
+  if (telegramToken) {
+    const telegram = new TelegramAdapter(telegramToken);
+    channelManager.register(telegram);
+    console.log('✓ Telegram adapter registered');
+  } else {
+    console.log('⚠️  TELEGRAM_BOT_TOKEN not set, skipping Telegram');
+  }
+
+  // Connect all channels
+  try {
+    await channelManager.connectAll();
+    console.log('\n✓ All channels connected');
+    console.log('Status:', channelManager.getStatus());
+  } catch (error) {
+    console.error('Error connecting channels:', error);
+  }
+
+  // 4. Demo: Stream relay (requires LLM provider setup)
+  const streamRelay = new StreamRelay(wsServer);
+
+  // Example stream simulation
+  console.log('\n📡 Streaming demo (simulated)...');
+  const simulatedStream = (async function* () {
+    yield { type: 'text' as const, text: 'Hello ' };
+    await new Promise(r => setTimeout(r, 100));
+    yield { type: 'text' as const, text: 'from ' };
+    await new Promise(r => setTimeout(r, 100));
+    yield { type: 'text' as const, text: 'J.A.R.V.I.S.!' };
+    await new Promise(r => setTimeout(r, 100));
+    yield { type: 'done' as const, response: { content: 'Hello from J.A.R.V.I.S.!', tool_calls: [], usage: { input_tokens: 0, output_tokens: 10 }, model: 'demo', finish_reason: 'stop' as const } };
+  })();
+
+  const fullResponse = await streamRelay.relayStream(simulatedStream, 'demo-123');
+  console.log('Full response:', fullResponse);
+
+  console.log('\n✓ Communication layer is running');
+  console.log(`  WebSocket: ws://localhost:${wsServer.getPort()}/ws`);
+  console.log(`  Health: http://localhost:${wsServer.getPort()}/health`);
+  console.log(`  Channels: ${channelManager.listChannels().join(', ')}`);
+  console.log('\nPress Ctrl+C to stop...');
+
+  // Graceful shutdown
+  process.on('SIGINT', async () => {
+    console.log('\n\n🛑 Shutting down...');
+    await channelManager.disconnectAll();
+    wsServer.stop();
+    process.exit(0);
+  });
+}
+
+main().catch(console.error);

package/src/comms/index.ts

@@ -0,0 +1,129 @@
+// Core WebSocket and Streaming
+export { WebSocketServer, type WSMessage, type WSClientHandler } from './websocket.ts';
+export { StreamRelay } from './streaming.ts';
+
+// Voice I/O
+export {
+  OpenAIWhisperSTT,
+  GroqWhisperSTT,
+  LocalWhisperSTT,
+  EdgeTTSProvider,
+  ElevenLabsTTSProvider,
+  createSTTProvider,
+  createTTSProvider,
+  listElevenLabsVoices,
+  splitIntoSentences,
+  type STTProvider,
+  type TTSProvider,
+} from './voice.ts';
+
+// Channel adapters
+export {
+  TelegramAdapter,
+  type ChannelMessage,
+  type ChannelHandler,
+  type ChannelAdapter,
+} from './channels/telegram.ts';
+export { WhatsAppAdapter } from './channels/whatsapp.ts';
+export { DiscordAdapter } from './channels/discord.ts';
+export { SignalAdapter } from './channels/signal.ts';
+
+// Channel Manager
+export class ChannelManager {
+  private channels: Map<string, import('./channels/telegram.ts').ChannelAdapter> = new Map();
+  private handler: import('./channels/telegram.ts').ChannelHandler | null = null;
+
+  /**
+   * Register a channel adapter
+   */
+  register(adapter: import('./channels/telegram.ts').ChannelAdapter): void {
+    if (this.channels.has(adapter.name)) {
+      console.warn(`[ChannelManager] Channel "${adapter.name}" already registered, overwriting`);
+    }
+
+    this.channels.set(adapter.name, adapter);
+    console.log(`[ChannelManager] Registered channel: ${adapter.name}`);
+  }
+
+  /**
+   * Set the message handler for all channels
+   */
+  setHandler(handler: import('./channels/telegram.ts').ChannelHandler): void {
+    this.handler = handler;
+
+    // Apply handler to all registered channels
+    for (const adapter of this.channels.values()) {
+      adapter.onMessage(handler);
+    }
+
+    console.log('[ChannelManager] Handler set for all channels');
+  }
+
+  /**
+   * Connect all registered channels
+   */
+  async connectAll(): Promise<void> {
+    const results = await Promise.allSettled(
+      Array.from(this.channels.values()).map(async (adapter) => {
+        try {
+          await adapter.connect();
+          console.log(`[ChannelManager] Connected: ${adapter.name}`);
+        } catch (error) {
+          console.error(`[ChannelManager] Failed to connect ${adapter.name}:`, error);
+          throw error;
+        }
+      })
+    );
+
+    const failures = results.filter((r) => r.status === 'rejected');
+    if (failures.length > 0) {
+      console.warn(`[ChannelManager] ${failures.length} channel(s) failed to connect`);
+    }
+
+    const successes = results.filter((r) => r.status === 'fulfilled').length;
+    console.log(`[ChannelManager] ${successes}/${this.channels.size} channels connected`);
+  }
+
+  /**
+   * Disconnect all registered channels
+   */
+  async disconnectAll(): Promise<void> {
+    await Promise.allSettled(
+      Array.from(this.channels.values()).map(async (adapter) => {
+        try {
+          await adapter.disconnect();
+          console.log(`[ChannelManager] Disconnected: ${adapter.name}`);
+        } catch (error) {
+          console.error(`[ChannelManager] Error disconnecting ${adapter.name}:`, error);
+        }
+      })
+    );
+
+    console.log('[ChannelManager] All channels disconnected');
+  }
+
+  /**
+   * Get a specific channel adapter by name
+   */
+  getChannel(name: string): import('./channels/telegram.ts').ChannelAdapter | undefined {
+    return this.channels.get(name);
+  }
+
+  /**
+   * List all registered channel names
+   */
+  listChannels(): string[] {
+    return Array.from(this.channels.keys());
+  }
+
+  /**
+   * Get status of all channels
+   */
+  getStatus(): Record<string, boolean> {
+    const status: Record<string, boolean> = {};
+    for (const [name, adapter] of this.channels) {
+      status[name] = adapter.isConnected();
+    }
+    return status;
+  }
+}

package/src/comms/streaming.ts

@@ -0,0 +1,142 @@
+import type { LLMStreamEvent } from '../llm/provider.ts';
+import type { WebSocketServer, WSMessage } from './websocket.ts';
+
+export type RelayOptions = {
+  /** Called each time a complete sentence is available during streaming. */
+  onSentence?: (sentence: string) => void;
+  /** Called when all text is done streaming. */
+  onTextDone?: () => void;
+};
+
+// Sentence boundary: period, exclamation, question mark, colon followed by whitespace or end
+const SENTENCE_END_RE = /[.!?:]\s/;
+
+export class StreamRelay {
+  private wsServer: WebSocketServer;
+
+  constructor(wsServer: WebSocketServer) {
+    this.wsServer = wsServer;
+  }
+
+  /**
+   * Relay LLM stream events to all connected WebSocket clients.
+   * Accumulates and returns the complete response text.
+   * Optionally fires onSentence callback as complete sentences arrive.
+   */
+  async relayStream(
+    stream: AsyncIterable<LLMStreamEvent>,
+    requestId: string,
+    options?: RelayOptions,
+  ): Promise<string> {
+    let fullText = '';
+    let sentenceBuffer = '';
+
+    try {
+      for await (const event of stream) {
+        if (event.type === 'text') {
+          fullText += event.text;
+
+          // Sentence-level TTS callback
+          if (options?.onSentence) {
+            sentenceBuffer += event.text;
+            // Flush complete sentences from the buffer
+            let match: RegExpExecArray | null;
+            while ((match = SENTENCE_END_RE.exec(sentenceBuffer)) !== null) {
+              const end = match.index + match[0].length;
+              const sentence = sentenceBuffer.slice(0, end).trim();
+              if (sentence) {
+                options.onSentence(sentence);
+              }
+              sentenceBuffer = sentenceBuffer.slice(end);
+            }
+          }
+
+          // Broadcast chunk to all connected clients
+          const message: WSMessage = {
+            type: 'stream',
+            payload: {
+              text: event.text,
+              requestId,
+              accumulated: fullText,
+            },
+            id: requestId,
+            timestamp: Date.now(),
+          };
+
+          this.wsServer.broadcast(message);
+        } else if (event.type === 'tool_call') {
+          // Broadcast tool call notification to clients
+          const toolMessage: WSMessage = {
+            type: 'stream',
+            payload: {
+              tool_call: {
+                name: event.tool_call.name,
+                arguments: event.tool_call.arguments,
+              },
+              requestId,
+            },
+            id: requestId,
+            timestamp: Date.now(),
+          };
+
+          this.wsServer.broadcast(toolMessage);
+        } else if (event.type === 'error') {
+          console.error('[StreamRelay] Stream error:', event.error);
+
+          const errorMessage: WSMessage = {
+            type: 'error',
+            payload: {
+              message: event.error,
+              requestId,
+            },
+            id: requestId,
+            timestamp: Date.now(),
+          };
+
+          this.wsServer.broadcast(errorMessage);
+        } else if (event.type === 'done') {
+          // Flush remaining sentence buffer
+          if (options?.onSentence && sentenceBuffer.trim()) {
+            options.onSentence(sentenceBuffer.trim());
+            sentenceBuffer = '';
+          }
+          options?.onTextDone?.();
+
+          console.log('[StreamRelay] Stream complete for request:', requestId);
+
+          const doneMessage: WSMessage = {
+            type: 'status',
+            payload: {
+              status: 'done',
+              requestId,
+              fullText,
+              usage: event.response.usage,
+            },
+            id: requestId,
+            timestamp: Date.now(),
+          };
+
+          this.wsServer.broadcast(doneMessage);
+        }
+      }
+    } catch (error) {
+      console.error('[StreamRelay] Error relaying stream:', error);
+
+      const errorMessage: WSMessage = {
+        type: 'error',
+        payload: {
+          message: error instanceof Error ? error.message : 'Stream relay error',
+          requestId,
+        },
+        id: requestId,
+        timestamp: Date.now(),
+      };
+
+      this.wsServer.broadcast(errorMessage);
+
+      throw error;
+    }
+
+    return fullText;
+  }
+}

package/src/comms/voice.test.ts

@@ -0,0 +1,152 @@
+import { test, expect, describe } from 'bun:test';
+import {
+  createSTTProvider,
+  createTTSProvider,
+  OpenAIWhisperSTT,
+  GroqWhisperSTT,
+  LocalWhisperSTT,
+  EdgeTTSProvider,
+  splitIntoSentences,
+} from './voice.ts';
+import type { STTConfig, TTSConfig } from '../config/types.ts';
+
+describe('createSTTProvider factory', () => {
+  test('returns OpenAIWhisperSTT when provider=openai and key present', () => {
+    const config: STTConfig = {
+      provider: 'openai',
+      openai: { api_key: 'test-openai-key-not-real' },
+    };
+    const provider = createSTTProvider(config);
+    expect(provider).toBeInstanceOf(OpenAIWhisperSTT);
+  });
+
+  test('returns null when provider=openai and no key', () => {
+    const config: STTConfig = { provider: 'openai' };
+    const provider = createSTTProvider(config);
+    expect(provider).toBeNull();
+  });
+
+  test('returns GroqWhisperSTT when provider=groq and key present', () => {
+    const config: STTConfig = {
+      provider: 'groq',
+      groq: { api_key: 'gtest-openai-key-not-real' },
+    };
+    const provider = createSTTProvider(config);
+    expect(provider).toBeInstanceOf(GroqWhisperSTT);
+  });
+
+  test('returns null when provider=groq and no key', () => {
+    const config: STTConfig = { provider: 'groq' };
+    const provider = createSTTProvider(config);
+    expect(provider).toBeNull();
+  });
+
+  test('returns LocalWhisperSTT when provider=local (no key needed)', () => {
+    const config: STTConfig = { provider: 'local' };
+    const provider = createSTTProvider(config);
+    expect(provider).toBeInstanceOf(LocalWhisperSTT);
+  });
+
+  test('returns LocalWhisperSTT with custom endpoint', () => {
+    const config: STTConfig = {
+      provider: 'local',
+      local: { endpoint: 'http://my-server:9000' },
+    };
+    const provider = createSTTProvider(config);
+    expect(provider).toBeInstanceOf(LocalWhisperSTT);
+  });
+
+  test('returns null for unknown provider', () => {
+    const config = { provider: 'unknown' } as any;
+    const provider = createSTTProvider(config);
+    expect(provider).toBeNull();
+  });
+
+  test('returns OpenAI with custom model', () => {
+    const config: STTConfig = {
+      provider: 'openai',
+      openai: { api_key: 'test-key-not-real', model: 'whisper-large-v3' },
+    };
+    const provider = createSTTProvider(config);
+    expect(provider).toBeInstanceOf(OpenAIWhisperSTT);
+  });
+});
+
+describe('createTTSProvider factory', () => {
+  test('returns null when tts disabled', () => {
+    const config: TTSConfig = { enabled: false };
+    expect(createTTSProvider(config)).toBeNull();
+  });
+
+  test('returns EdgeTTSProvider when enabled', () => {
+    const config: TTSConfig = { enabled: true };
+    const provider = createTTSProvider(config);
+    expect(provider).toBeInstanceOf(EdgeTTSProvider);
+  });
+
+  test('passes voice config to provider', () => {
+    const config: TTSConfig = { enabled: true, voice: 'en-GB-SoniaNeural' };
+    const provider = createTTSProvider(config);
+    expect(provider).toBeInstanceOf(EdgeTTSProvider);
+  });
+
+  test('passes rate and volume config', () => {
+    const config: TTSConfig = { enabled: true, rate: '+20%', volume: '-10%' };
+    const provider = createTTSProvider(config);
+    expect(provider).not.toBeNull();
+  });
+});
+
+describe('EdgeTTSProvider', () => {
+  test('implements TTSProvider interface', () => {
+    const provider = new EdgeTTSProvider();
+    expect(typeof provider.synthesize).toBe('function');
+    expect(typeof provider.synthesizeStream).toBe('function');
+  });
+
+  test('constructor accepts custom voice/rate/volume', () => {
+    const provider = new EdgeTTSProvider('en-GB-SoniaNeural', '+10%', '-5%');
+    expect(provider).toBeInstanceOf(EdgeTTSProvider);
+  });
+});
+
+describe('splitIntoSentences', () => {
+  test('splits on period + capital letter', () => {
+    const result = splitIntoSentences('Hello there. World is great. This works.');
+    expect(result.length).toBe(3);
+    expect(result[0]).toBe('Hello there.');
+    expect(result[1]).toBe('World is great.');
+    expect(result[2]).toBe('This works.');
+  });
+
+  test('splits on exclamation and question marks', () => {
+    const result = splitIntoSentences('Wait! Are you sure? Yes I am.');
+    expect(result.length).toBe(3);
+  });
+
+  test('handles single sentence', () => {
+    const result = splitIntoSentences('Just one sentence.');
+    expect(result).toEqual(['Just one sentence.']);
+  });
+
+  test('handles empty string', () => {
+    const result = splitIntoSentences('');
+    expect(result).toEqual(['']);
+  });
+
+  test('collapses code blocks', () => {
+    const result = splitIntoSentences('Here is code:\n```\nconst x = 1;\n```\nDone.');
+    // Should not split inside code block
+    expect(result.length).toBeLessThanOrEqual(3);
+  });
+
+  test('splits on double newlines (paragraph breaks)', () => {
+    const result = splitIntoSentences('First paragraph\n\nSecond paragraph');
+    expect(result.length).toBe(2);
+  });
+
+  test('handles text with no sentence-ending punctuation', () => {
+    const result = splitIntoSentences('just some words without punctuation');
+    expect(result).toEqual(['just some words without punctuation']);
+  });
+});