@usejarvis/brain 0.1.0

package/src/comms/README.md

@@ -0,0 +1,329 @@
+# J.A.R.V.I.S. Communication Layer
+
+The communication layer provides multi-channel messaging, WebSocket-based real-time communication, LLM response streaming, and voice I/O capabilities.
+
+## Architecture
+
+```
+comms/
+├── websocket.ts       # Local WebSocket server using Bun.serve()
+├── streaming.ts       # LLM stream relay to WebSocket clients
+├── voice.ts          # STT/TTS provider interfaces and stubs
+├── channels/         # Multi-platform messaging adapters
+│   ├── telegram.ts   # ✅ Telegram Bot API (fully functional)
+│   ├── whatsapp.ts   # 🚧 WhatsApp Business API (stub)
+│   ├── discord.ts    # 🚧 Discord Bot (stub)
+│   └── signal.ts     # 🚧 Signal CLI (stub)
+└── index.ts          # ChannelManager and exports
+```
+
+## Core Components
+
+### 1. WebSocket Server
+
+Real-time bidirectional communication with web clients.
+
+```typescript
+import { WebSocketServer } from './comms';
+
+const wsServer = new WebSocketServer(3142);
+
+wsServer.setHandler({
+  async onMessage(msg) {
+    console.log('Received:', msg.type, msg.payload);
+    return { type: 'status', payload: 'Acknowledged', timestamp: Date.now() };
+  },
+  onConnect() {
+    console.log('Client connected');
+  },
+  onDisconnect() {
+    console.log('Client disconnected');
+  },
+});
+
+wsServer.start();
+```
+
+**Endpoints:**
+- `ws://localhost:3142/ws` - WebSocket connection
+- `http://localhost:3142/health` - Health check
+- `http://localhost:3142/` - Server info
+
+**Message Types:**
+```typescript
+type WSMessage = {
+  type: 'chat' | 'command' | 'status' | 'stream' | 'error';
+  payload: unknown;
+  id?: string;
+  timestamp: number;
+};
+```
+
+### 2. Stream Relay
+
+Relays LLM streaming responses to connected WebSocket clients in real-time.
+
+```typescript
+import { StreamRelay, WebSocketServer } from './comms';
+
+const wsServer = new WebSocketServer();
+wsServer.start();
+
+const relay = new StreamRelay(wsServer);
+
+// Relay LLM stream to all connected clients
+const stream = llmProvider.generateStream(prompt);
+const fullResponse = await relay.relayStream(stream, 'request-123');
+```
+
+Clients receive incremental updates:
+```json
+{
+  "type": "stream",
+  "payload": {
+    "text": "chunk of text",
+    "requestId": "request-123",
+    "accumulated": "full text so far"
+  },
+  "timestamp": 1708645200000
+}
+```
+
+### 3. Channel Manager
+
+Unified interface for managing multiple messaging platforms.
+
+```typescript
+import { ChannelManager, TelegramAdapter } from './comms';
+
+const manager = new ChannelManager();
+
+// Register Telegram
+const telegram = new TelegramAdapter(process.env.TELEGRAM_BOT_TOKEN!);
+manager.register(telegram);
+
+// Set unified message handler
+manager.setHandler(async (message) => {
+  console.log(`[${message.channel}] ${message.from}: ${message.text}`);
+  return `Received: ${message.text}`;
+});
+
+// Connect all channels
+await manager.connectAll();
+
+// Check status
+console.log(manager.getStatus()); // { telegram: true }
+```
+
+### 4. Telegram Adapter (Functional)
+
+Full implementation using Telegram Bot API with long polling.
+
+```typescript
+import { TelegramAdapter } from './comms/channels/telegram';
+
+const telegram = new TelegramAdapter(process.env.TELEGRAM_BOT_TOKEN!);
+
+telegram.onMessage(async (message) => {
+  console.log(`Message from ${message.from}: ${message.text}`);
+  return `Echo: ${message.text}`;
+});
+
+await telegram.connect();
+
+// Send message
+await telegram.sendMessage('CHAT_ID', 'Hello from J.A.R.V.I.S.!');
+```
+
+**Setup:**
+1. Create bot via [@BotFather](https://t.me/botfather)
+2. Get bot token
+3. Set `TELEGRAM_BOT_TOKEN` environment variable
+
+### 5. Voice I/O (Stubs)
+
+Speech-to-Text and Text-to-Speech provider interfaces.
+
+```typescript
+import { WhisperSTT, LocalTTS } from './comms';
+
+// STT - requires whisper.cpp setup
+const stt = new WhisperSTT('http://localhost:8080');
+// const text = await stt.transcribe(audioBuffer);
+
+// TTS - requires ElevenLabs API or local TTS
+const tts = new LocalTTS({ provider: 'elevenlabs', apiKey: '...' });
+// const audio = await tts.synthesize('Hello world');
+```
+
+## Message Flow
+
+### Incoming Message Flow
+```
+Telegram/Discord/etc
+    ↓
+ChannelAdapter.onMessage()
+    ↓
+ChannelHandler (unified)
+    ↓
+Business logic (in daemon)
+    ↓
+WebSocketServer.broadcast()
+    ↓
+All connected web clients
+```
+
+### LLM Streaming Flow
+```
+LLM Provider stream
+    ↓
+StreamRelay.relayStream()
+    ↓
+WebSocketServer.broadcast()
+    ↓
+Real-time updates to clients
+```
+
+## Running Examples
+
+### Start WebSocket Server Only
+```bash
+bun run src/comms/example.ts
+```
+
+### With Telegram Integration
+```bash
+export TELEGRAM_BOT_TOKEN="your_bot_token"
+bun run src/comms/example.ts
+```
+
+### Run Tests
+```bash
+bun test src/comms/websocket.test.ts
+bun test src/comms/channels.test.ts
+```
+
+## Environment Variables
+
+```bash
+# Required for Telegram
+TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
+
+# Future integrations
+WHATSAPP_PHONE_ID=...
+WHATSAPP_ACCESS_TOKEN=...
+DISCORD_BOT_TOKEN=...
+SIGNAL_PHONE=+1234567890
+ELEVENLABS_API_KEY=...
+```
+
+## Channel Adapter Interface
+
+All channel adapters implement this interface:
+
+```typescript
+interface ChannelAdapter {
+  name: string;
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  sendMessage(to: string, text: string): Promise<void>;
+  onMessage(handler: ChannelHandler): void;
+  isConnected(): boolean;
+}
+
+type ChannelMessage = {
+  id: string;
+  channel: string;
+  from: string;
+  text: string;
+  timestamp: number;
+  metadata: Record<string, unknown>;
+};
+
+type ChannelHandler = (message: ChannelMessage) => Promise<string>;
+```
+
+## Future Channel Implementations
+
+### WhatsApp
+- Requires WhatsApp Business API setup
+- Webhook-based architecture
+- See: https://developers.facebook.com/docs/whatsapp/cloud-api
+
+### Discord
+- Use Discord Gateway WebSocket or discord.js
+- Support slash commands
+- See: https://discord.com/developers/docs
+
+### Signal
+- Requires signal-cli in daemon mode
+- Local installation needed
+- See: https://github.com/AsamK/signal-cli
+
+## Integration with J.A.R.V.I.S. Daemon
+
+```typescript
+// In daemon/index.ts
+import { WebSocketServer, ChannelManager, TelegramAdapter, StreamRelay } from './comms';
+import { LLMRouter } from './llm';
+
+const wsServer = new WebSocketServer();
+const channels = new ChannelManager();
+const streamRelay = new StreamRelay(wsServer);
+const llmRouter = new LLMRouter();
+
+// Unified message handler
+channels.setHandler(async (message) => {
+  // Route to appropriate LLM provider
+  const stream = await llmRouter.route(message.text, { stream: true });
+
+  // Relay stream to WebSocket clients
+  const response = await streamRelay.relayStream(stream, message.id);
+
+  // Return response to original channel
+  return response;
+});
+
+// Start everything
+wsServer.start();
+if (process.env.TELEGRAM_BOT_TOKEN) {
+  channels.register(new TelegramAdapter(process.env.TELEGRAM_BOT_TOKEN));
+}
+await channels.connectAll();
+```
+
+## Performance Considerations
+
+- **WebSocket**: Bun's native WebSocket support is extremely fast
+- **Telegram Polling**: Uses long polling (30s timeout) to minimize requests
+- **Stream Relay**: Zero-copy broadcast to multiple clients
+- **Memory**: Each WebSocket connection uses ~1KB of memory
+
+## Security Notes
+
+- **WebSocket**: Currently no authentication - add JWT or session tokens for production
+- **Channel Tokens**: Store in environment variables, never commit
+- **Rate Limiting**: Implement on message handlers to prevent abuse
+- **Input Validation**: Always sanitize user input before processing
+
+## Troubleshooting
+
+### WebSocket Connection Failed
+- Check port 3142 is not in use: `lsof -i :3142`
+- Verify firewall allows connections
+- Check CORS if connecting from browser
+
+### Telegram Not Receiving Messages
+- Verify bot token is correct
+- Check bot is not blocked
+- Ensure polling is active: check logs for "Starting polling"
+- Test with `/health` endpoint
+
+### Stream Not Broadcasting
+- Verify WebSocket clients are connected: check `/health`
+- Ensure LLM stream implements AsyncIterable<LLMStreamEvent>
+- Check client WebSocket listeners are set up
+
+## API Reference
+
+See inline TypeScript documentation in each module for detailed API reference.

package/src/comms/auth-error.html

@@ -0,0 +1,48 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <!--
+    Auth error page — if ?token= is inside the hash (e.g. /#/settings?token=xxx),
+    move it into the query string so the server can set the cookie via Set-Cookie + 302.
+  -->
+  <script>
+    (function () {
+      var h = location.hash;
+      var qi = h.indexOf('?');
+      if (qi !== -1) {
+        var hp = new URLSearchParams(h.slice(qi));
+        var t = hp.get('token');
+        if (t) {
+          hp.delete('token');
+          var cleanHash = h.slice(0, qi);
+          var remaining = hp.toString();
+          if (remaining) cleanHash += '?' + remaining;
+          location.replace(location.pathname + '?token=' + encodeURIComponent(t) + cleanHash);
+        }
+      }
+    })();
+  </script>
+  <title>Unauthorized</title>
+  <style>
+    body {
+      font-family: system-ui;
+      display: flex;
+      justify-content: center;
+      align-items: center;
+      height: 100vh;
+      margin: 0;
+      background: #111;
+      color: #ccc;
+    }
+    .box { text-align: center }
+    h1 { font-size: 4rem; margin: 0; color: #666 }
+    p { margin-top: 1rem }
+  </style>
+</head>
+<body>
+  <div class="box">
+    <h1>401</h1>
+    <p>Access requires a valid token.</p>
+  </div>
+</body>
+</html>

package/src/comms/channels/discord.ts

@@ -0,0 +1,228 @@
+import { Client, GatewayIntentBits, Partials, type Message } from 'discord.js';
+import type { ChannelAdapter, ChannelHandler, ChannelMessage } from './telegram.ts';
+import type { STTProvider } from '../voice.ts';
+
+export class DiscordAdapter implements ChannelAdapter {
+  name = 'discord';
+  private token: string;
+  private handler: ChannelHandler | null = null;
+  private connected: boolean = false;
+  private client: Client | null = null;
+  private allowedUsers: string[];
+  private guildId: string | null;
+  private sttProvider: STTProvider | null;
+
+  constructor(token: string, opts?: {
+    allowedUsers?: string[];
+    guildId?: string;
+    sttProvider?: STTProvider;
+  }) {
+    this.token = token;
+    this.allowedUsers = opts?.allowedUsers ?? [];
+    this.guildId = opts?.guildId ?? null;
+    this.sttProvider = opts?.sttProvider ?? null;
+  }
+
+  setSTTProvider(provider: STTProvider): void {
+    this.sttProvider = provider;
+  }
+
+  async connect(): Promise<void> {
+    if (this.connected) {
+      console.warn('[DiscordAdapter] Already connected');
+      return;
+    }
+
+    this.client = new Client({
+      intents: [
+        GatewayIntentBits.Guilds,
+        GatewayIntentBits.GuildMessages,
+        GatewayIntentBits.DirectMessages,
+        GatewayIntentBits.MessageContent,
+      ],
+      partials: [Partials.Channel],
+    });
+
+    // Wait for ready event
+    let loginTimeout: ReturnType<typeof setTimeout> | null = null;
+    const readyPromise = new Promise<void>((resolve, reject) => {
+      loginTimeout = setTimeout(() => reject(new Error('Discord login timed out')), 30000);
+
+      this.client!.once('ready', () => {
+        clearTimeout(loginTimeout!);
+        this.connected = true;
+        console.log(`[DiscordAdapter] Connected as: ${this.client!.user?.tag}`);
+        resolve();
+      });
+
+      this.client!.once('error', (err) => {
+        clearTimeout(loginTimeout!);
+        reject(err);
+      });
+    });
+
+    // Set up message handler
+    this.client.on('messageCreate', async (message: Message) => {
+      try {
+        await this.processMessage(message);
+      } catch (err) {
+        console.error('[DiscordAdapter] Unhandled error in processMessage:', err);
+      }
+    });
+
+    try {
+      await this.client.login(this.token);
+    } catch (err) {
+      // Clear the ready timeout to prevent unhandled rejection
+      if (loginTimeout) clearTimeout(loginTimeout);
+      this.client.destroy();
+      this.client = null;
+      throw err;
+    }
+    await readyPromise;
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.client) {
+      this.client.destroy();
+      this.client = null;
+    }
+    this.connected = false;
+    console.log('[DiscordAdapter] Disconnected');
+  }
+
+  async sendMessage(channelId: string, text: string): Promise<void> {
+    if (!this.client) throw new Error('Discord not connected');
+
+    const channel = await this.client.channels.fetch(channelId);
+    if (!channel || !channel.isTextBased()) {
+      throw new Error(`Invalid or non-text channel: ${channelId}`);
+    }
+
+    const chunks = splitMessage(text, 2000);
+    for (const chunk of chunks) {
+      await (channel as any).send(chunk);
+    }
+  }
+
+  onMessage(handler: ChannelHandler): void {
+    this.handler = handler;
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  private async processMessage(message: Message): Promise<void> {
+    // Ignore bot messages (including our own)
+    if (message.author.bot) return;
+    if (!this.handler) return;
+
+    // Security: check allowed users (empty = allow all)
+    if (this.allowedUsers.length > 0 && !this.allowedUsers.includes(message.author.id)) {
+      return;
+    }
+
+    // Security: check guild restriction
+    if (this.guildId && message.guildId && message.guildId !== this.guildId) {
+      return;
+    }
+
+    let text = message.content;
+
+    // Handle audio attachments via STT
+    const audioAttachment = message.attachments.find(a =>
+      a.contentType?.startsWith('audio/') ||
+      a.name?.endsWith('.ogg') ||
+      a.name?.endsWith('.mp3') ||
+      a.name?.endsWith('.wav') ||
+      a.name?.endsWith('.m4a')
+    );
+
+    if (audioAttachment && !text && this.sttProvider) {
+      try {
+        const resp = await fetch(audioAttachment.url);
+        if (!resp.ok) throw new Error(`Failed to download: ${resp.status}`);
+        const buffer = Buffer.from(await resp.arrayBuffer());
+        text = await this.sttProvider.transcribe(buffer);
+        console.log('[DiscordAdapter] Transcribed audio:', text.slice(0, 80));
+      } catch (err) {
+        console.error('[DiscordAdapter] STT error:', err);
+        await message.reply('Failed to transcribe audio. Please send text.');
+        return;
+      }
+    }
+
+    if (!text) return;
+
+    const channelMessage: ChannelMessage = {
+      id: message.id,
+      channel: 'discord',
+      from: message.author.username,
+      text,
+      timestamp: message.createdTimestamp,
+      metadata: {
+        userId: message.author.id,
+        channelId: message.channelId,
+        guildId: message.guildId,
+        isDM: !message.guildId,
+        isVoice: !!audioAttachment,
+      },
+    };
+
+    console.log('[DiscordAdapter] Message from', channelMessage.from, ':', text.slice(0, 80));
+
+    try {
+      // Show typing indicator
+      if (message.channel.isSendable()) {
+        await message.channel.sendTyping();
+      }
+
+      const response = await this.handler(channelMessage);
+
+      if (response) {
+        const chunks = splitMessage(response, 2000);
+        for (const chunk of chunks) {
+          await message.reply(chunk);
+        }
+      }
+    } catch (err) {
+      console.error('[DiscordAdapter] Error handling message:', err);
+      try {
+        await message.reply('Sorry, I encountered an error processing your message.');
+      } catch {
+        // Ignore send failure
+      }
+    }
+  }
+}
+
+export function splitMessage(text: string, maxLength: number): string[] {
+  if (text.length <= maxLength) return [text];
+
+  const chunks: string[] = [];
+  let remaining = text;
+
+  while (remaining.length > 0) {
+    if (remaining.length <= maxLength) {
+      chunks.push(remaining);
+      break;
+    }
+
+    // Try to split at newline
+    let splitIdx = remaining.lastIndexOf('\n', maxLength);
+    if (splitIdx < maxLength / 2) {
+      // Try space
+      splitIdx = remaining.lastIndexOf(' ', maxLength);
+    }
+    if (splitIdx < maxLength / 2) {
+      // Hard split
+      splitIdx = maxLength;
+    }
+
+    chunks.push(remaining.slice(0, splitIdx));
+    remaining = remaining.slice(splitIdx).trimStart();
+  }
+
+  return chunks;
+}

package/src/comms/channels/signal.ts

@@ -0,0 +1,56 @@
+import type { ChannelAdapter, ChannelHandler, ChannelMessage } from './telegram.ts';
+
+export class SignalAdapter implements ChannelAdapter {
+  name = 'signal';
+  private phone: string;
+  private handler: ChannelHandler | null = null;
+  private connected: boolean = false;
+
+  constructor(config: { phone: string }) {
+    this.phone = config.phone;
+  }
+
+  async connect(): Promise<void> {
+    throw new Error(
+      'Signal adapter not yet implemented. Requires signal-cli setup. ' +
+      'Install signal-cli: https://github.com/AsamK/signal-cli'
+    );
+
+    // Future implementation would use signal-cli in daemon mode:
+    // 1. Ensure signal-cli is installed and registered with phone number
+    // 2. Start signal-cli in daemon mode with D-Bus interface
+    // 3. Subscribe to message events via D-Bus
+    // 4. Set this.connected = true
+    //
+    // Example using signal-cli REST API mode:
+    // Start signal-cli with: signal-cli -a <PHONE> daemon --http localhost:8080
+    // Then connect via HTTP API
+  }
+
+  async disconnect(): Promise<void> {
+    this.connected = false;
+  }
+
+  async sendMessage(recipient: string, text: string): Promise<void> {
+    throw new Error('Signal adapter not yet implemented.');
+
+    // Future implementation using signal-cli REST API:
+    // await fetch('http://localhost:8080/v2/send', {
+    //   method: 'POST',
+    //   headers: { 'Content-Type': 'application/json' },
+    //   body: JSON.stringify({
+    //     number: this.phone,
+    //     recipients: [recipient],
+    //     message: text,
+    //   }),
+    // });
+  }
+
+  onMessage(handler: ChannelHandler): void {
+    this.handler = handler;
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+}