@usejarvis/brain 0.1.0

package/src/llm/provider.test.ts

@@ -0,0 +1,231 @@
+import { test, expect, describe } from 'bun:test';
+import { AnthropicProvider } from './anthropic.ts';
+import { OpenAIProvider } from './openai.ts';
+import { OllamaProvider } from './ollama.ts';
+import { LLMManager } from './manager.ts';
+import { guardImageSize, type LLMMessage, type ContentBlock } from './provider.ts';
+import { isToolResult, type ToolResult } from '../actions/tools/registry.ts';
+
+describe('LLM Provider Types', () => {
+  test('AnthropicProvider can be instantiated', () => {
+    const provider = new AnthropicProvider('test-key', 'test-model');
+    expect(provider.name).toBe('anthropic');
+  });
+
+  test('OpenAIProvider can be instantiated', () => {
+    const provider = new OpenAIProvider('test-key', 'test-model');
+    expect(provider.name).toBe('openai');
+  });
+
+  test('OllamaProvider can be instantiated', () => {
+    const provider = new OllamaProvider('http://localhost:11434', 'llama3');
+    expect(provider.name).toBe('ollama');
+  });
+});
+
+describe('LLMManager', () => {
+  test('can register providers', () => {
+    const manager = new LLMManager();
+    const anthropic = new AnthropicProvider('test-key');
+
+    manager.registerProvider(anthropic);
+    expect(manager.getProvider('anthropic')).toBe(anthropic);
+  });
+
+  test('sets first registered provider as primary', () => {
+    const manager = new LLMManager();
+    const anthropic = new AnthropicProvider('test-key');
+
+    manager.registerProvider(anthropic);
+    // Primary is set automatically
+    expect(manager.getProvider('anthropic')).toBeDefined();
+  });
+
+  test('can change primary provider', () => {
+    const manager = new LLMManager();
+    const anthropic = new AnthropicProvider('test-key-1');
+    const openai = new OpenAIProvider('test-key-2');
+
+    manager.registerProvider(anthropic);
+    manager.registerProvider(openai);
+    manager.setPrimary('openai');
+
+    // Should not throw
+    expect(manager.getProvider('openai')).toBeDefined();
+  });
+
+  test('throws when setting non-existent provider as primary', () => {
+    const manager = new LLMManager();
+    expect(() => manager.setPrimary('nonexistent')).toThrow();
+  });
+
+  test('can set fallback chain', () => {
+    const manager = new LLMManager();
+    const anthropic = new AnthropicProvider('test-key-1');
+    const openai = new OpenAIProvider('test-key-2');
+
+    manager.registerProvider(anthropic);
+    manager.registerProvider(openai);
+    manager.setPrimary('anthropic');
+    manager.setFallbackChain(['openai']);
+
+    // Should not throw
+    expect(manager.getProvider('anthropic')).toBeDefined();
+    expect(manager.getProvider('openai')).toBeDefined();
+  });
+
+  test('throws when setting non-existent fallback provider', () => {
+    const manager = new LLMManager();
+    const anthropic = new AnthropicProvider('test-key');
+
+    manager.registerProvider(anthropic);
+    expect(() => manager.setFallbackChain(['nonexistent'])).toThrow();
+  });
+});
+
+describe('Message Types', () => {
+  test('LLMMessage has correct structure', () => {
+    const message: LLMMessage = {
+      role: 'user',
+      content: 'Hello',
+    };
+
+    expect(message.role).toBe('user');
+    expect(message.content).toBe('Hello');
+  });
+
+  test('supports all message roles', () => {
+    const messages: LLMMessage[] = [
+      { role: 'system', content: 'You are helpful' },
+      { role: 'user', content: 'Hello' },
+      { role: 'assistant', content: 'Hi there' },
+    ];
+
+    expect(messages).toHaveLength(3);
+    expect(messages[0]!.role).toBe('system');
+    expect(messages[1]!.role).toBe('user');
+    expect(messages[2]!.role).toBe('assistant');
+  });
+});
+
+describe('Provider URLs', () => {
+  test('AnthropicProvider uses correct API URL', () => {
+    const provider = new AnthropicProvider('test-key') as any;
+    expect(provider.apiUrl).toBe('https://api.anthropic.com/v1/messages');
+  });
+
+  test('OpenAIProvider uses correct API URL', () => {
+    const provider = new OpenAIProvider('test-key') as any;
+    expect(provider.apiUrl).toBe('https://api.openai.com/v1/chat/completions');
+  });
+
+  test('OllamaProvider uses correct base URL', () => {
+    const provider = new OllamaProvider() as any;
+    expect(provider.baseUrl).toBe('http://localhost:11434');
+  });
+
+  test('OllamaProvider removes trailing slash from base URL', () => {
+    const provider = new OllamaProvider('http://localhost:11434/') as any;
+    expect(provider.baseUrl).toBe('http://localhost:11434');
+  });
+});
+
+describe('Default Models', () => {
+  test('AnthropicProvider has correct default model', () => {
+    const provider = new AnthropicProvider('test-key') as any;
+    expect(provider.defaultModel).toBe('claude-sonnet-4-5-20250929');
+  });
+
+  test('OpenAIProvider has correct default model', () => {
+    const provider = new OpenAIProvider('test-key') as any;
+    expect(provider.defaultModel).toBe('gpt-4o');
+  });
+
+  test('OllamaProvider has correct default model', () => {
+    const provider = new OllamaProvider() as any;
+    expect(provider.defaultModel).toBe('llama3');
+  });
+
+  test('can override default models', () => {
+    const anthropic = new AnthropicProvider('key', 'custom-model') as any;
+    const openai = new OpenAIProvider('key', 'custom-model') as any;
+    const ollama = new OllamaProvider('http://localhost:11434', 'custom-model') as any;
+
+    expect(anthropic.defaultModel).toBe('custom-model');
+    expect(openai.defaultModel).toBe('custom-model');
+    expect(ollama.defaultModel).toBe('custom-model');
+  });
+});
+
+describe('Vision Support', () => {
+  describe('guardImageSize', () => {
+    test('passes text blocks through unchanged', () => {
+      const block: ContentBlock = { type: 'text', text: 'hello' };
+      expect(guardImageSize(block)).toBe(block);
+    });
+
+    test('passes small images through unchanged', () => {
+      const block: ContentBlock = {
+        type: 'image',
+        source: { type: 'base64', media_type: 'image/png', data: 'abc123' },
+      };
+      expect(guardImageSize(block)).toBe(block);
+    });
+
+    test('replaces oversized images with text warning', () => {
+      const bigData = 'x'.repeat(6 * 1024 * 1024); // 6 MB
+      const block: ContentBlock = {
+        type: 'image',
+        source: { type: 'base64', media_type: 'image/png', data: bigData },
+      };
+      const result = guardImageSize(block);
+      expect(result.type).toBe('text');
+      expect((result as { type: 'text'; text: string }).text).toContain('too large');
+    });
+  });
+
+  describe('isToolResult', () => {
+    test('returns true for valid ToolResult', () => {
+      const tr: ToolResult = {
+        content: [{ type: 'text', text: 'hello' }],
+      };
+      expect(isToolResult(tr)).toBe(true);
+    });
+
+    test('returns false for plain string', () => {
+      expect(isToolResult('hello')).toBe(false);
+    });
+
+    test('returns false for null', () => {
+      expect(isToolResult(null)).toBe(false);
+    });
+
+    test('returns false for object without content array', () => {
+      expect(isToolResult({ content: 'not an array' })).toBe(false);
+    });
+
+    test('returns false for object with no content field', () => {
+      expect(isToolResult({ data: 'something' })).toBe(false);
+    });
+  });
+
+  describe('ContentBlock in LLMMessage', () => {
+    test('LLMMessage accepts string content', () => {
+      const msg: LLMMessage = { role: 'user', content: 'Hello' };
+      expect(typeof msg.content).toBe('string');
+    });
+
+    test('LLMMessage accepts ContentBlock[] content', () => {
+      const msg: LLMMessage = {
+        role: 'tool',
+        content: [
+          { type: 'text', text: 'Screenshot captured' },
+          { type: 'image', source: { type: 'base64', media_type: 'image/png', data: 'abc' } },
+        ],
+        tool_call_id: 'test-id',
+      };
+      expect(Array.isArray(msg.content)).toBe(true);
+      expect((msg.content as ContentBlock[]).length).toBe(2);
+    });
+  });
+});

package/src/llm/provider.ts

@@ -0,0 +1,60 @@
+export type ContentBlock =
+  | { type: 'text'; text: string }
+  | { type: 'image'; source: { type: 'base64'; media_type: string; data: string } };
+
+export type LLMMessage = {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string | ContentBlock[];
+  tool_calls?: LLMToolCall[];   // present on assistant messages with tool use
+  tool_call_id?: string;        // present on tool result messages
+};
+
+export type LLMTool = {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;  // JSON Schema
+};
+
+export type LLMToolCall = {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+};
+
+export type LLMResponse = {
+  content: string;
+  tool_calls: LLMToolCall[];
+  usage: { input_tokens: number; output_tokens: number };
+  model: string;
+  finish_reason: 'stop' | 'tool_use' | 'length' | 'error';
+};
+
+export type LLMStreamEvent =
+  | { type: 'text'; text: string }
+  | { type: 'tool_call'; tool_call: LLMToolCall }
+  | { type: 'done'; response: LLMResponse }
+  | { type: 'error'; error: string };
+
+export type LLMOptions = {
+  model?: string;
+  temperature?: number;
+  max_tokens?: number;
+  tools?: LLMTool[];
+  stream?: boolean;
+};
+
+export interface LLMProvider {
+  name: string;
+  chat(messages: LLMMessage[], options?: LLMOptions): Promise<LLMResponse>;
+  stream(messages: LLMMessage[], options?: LLMOptions): AsyncIterable<LLMStreamEvent>;
+  listModels(): Promise<string[]>;
+}
+
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024; // 5 MB base64 limit
+
+export function guardImageSize(block: ContentBlock): ContentBlock {
+  if (block.type === 'image' && block.source.data.length > MAX_IMAGE_BYTES) {
+    return { type: 'text', text: '[Image too large to send — saved to disk instead]' };
+  }
+  return block;
+}

package/src/llm/test.ts

@@ -0,0 +1,87 @@
+/**
+ * Manual test file for LLM providers
+ *
+ * Run with: bun run src/llm/test.ts
+ */
+
+import { LLMManager, AnthropicProvider, OpenAIProvider, OllamaProvider } from './index.ts';
+import { loadConfig } from '../config/index.ts';
+
+async function testProviders() {
+  console.log('Loading config...');
+  const config = await loadConfig();
+
+  const manager = new LLMManager();
+
+  // Register providers based on config
+  if (config.llm.anthropic?.api_key) {
+    const anthropic = new AnthropicProvider(
+      config.llm.anthropic.api_key,
+      config.llm.anthropic.model
+    );
+    manager.registerProvider(anthropic);
+    console.log('Registered Anthropic provider');
+  }
+
+  if (config.llm.openai?.api_key) {
+    const openai = new OpenAIProvider(
+      config.llm.openai.api_key,
+      config.llm.openai.model
+    );
+    manager.registerProvider(openai);
+    console.log('Registered OpenAI provider');
+  }
+
+  if (config.llm.ollama) {
+    const ollama = new OllamaProvider(
+      config.llm.ollama.base_url,
+      config.llm.ollama.model
+    );
+    manager.registerProvider(ollama);
+    console.log('Registered Ollama provider');
+  }
+
+  // Set primary and fallbacks
+  manager.setPrimary(config.llm.primary);
+  manager.setFallbackChain(config.llm.fallback);
+
+  console.log(`\nPrimary provider: ${config.llm.primary}`);
+  console.log(`Fallback chain: ${config.llm.fallback.join(', ')}\n`);
+
+  // Test basic chat
+  console.log('Testing chat...');
+  const messages = [
+    { role: 'system' as const, content: 'You are a helpful assistant.' },
+    { role: 'user' as const, content: 'Say hello in exactly 5 words.' },
+  ];
+
+  try {
+    const response = await manager.chat(messages);
+    console.log('Response:', response.content);
+    console.log('Model:', response.model);
+    console.log('Usage:', response.usage);
+    console.log('Finish reason:', response.finish_reason);
+  } catch (err) {
+    console.error('Chat failed:', err);
+  }
+
+  // Test streaming
+  console.log('\n\nTesting streaming...');
+  try {
+    for await (const event of manager.stream(messages)) {
+      if (event.type === 'text') {
+        process.stdout.write(event.text);
+      } else if (event.type === 'done') {
+        console.log('\n\nStream completed!');
+        console.log('Model:', event.response.model);
+        console.log('Usage:', event.response.usage);
+      } else if (event.type === 'error') {
+        console.error('Stream error:', event.error);
+      }
+    }
+  } catch (err) {
+    console.error('Stream failed:', err);
+  }
+}
+
+testProviders().catch(console.error);

package/src/observers/README.md

@@ -0,0 +1,278 @@
+# Observer Layer
+
+The Observer Layer monitors system events and emits standardized observations to the Vault. All observers implement a common interface and can be managed centrally through the `ObserverManager`.
+
+## Architecture
+
+### Common Interface
+
+All observers implement the `Observer` interface:
+
+```typescript
+interface Observer {
+  name: string;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  isRunning(): boolean;
+  onEvent(handler: ObserverEventHandler): void;
+}
+```
+
+Events are emitted in a standardized format:
+
+```typescript
+type ObserverEvent = {
+  type: string;
+  data: Record<string, unknown>;
+  timestamp: number;
+};
+```
+
+## Observers
+
+### FileWatcher (Fully Implemented)
+
+Monitors file system changes in specified directories.
+
+```typescript
+import { FileWatcher } from './file-watcher';
+
+const watcher = new FileWatcher([
+  '/home/user/projects',
+  '/home/user/documents'
+]);
+
+watcher.onEvent((event) => {
+  // event.type: 'file_change'
+  // event.data: { path, eventType: 'rename'|'change', filename, basePath }
+});
+
+await watcher.start();
+```
+
+Features:
+- Recursive directory watching using `node:fs` watch API
+- Debouncing (100ms) to avoid duplicate rapid-fire events
+- Automatic cleanup of old debounce entries to prevent memory leaks
+
+### ClipboardMonitor (Fully Implemented)
+
+Polls the system clipboard and detects content changes.
+
+```typescript
+import { ClipboardMonitor } from './clipboard';
+
+const clipboard = new ClipboardMonitor(1000); // Poll every 1 second
+
+clipboard.onEvent((event) => {
+  // event.type: 'clipboard'
+  // event.data: { content, length }
+});
+
+await clipboard.start();
+```
+
+Features:
+- Cross-platform clipboard reading (Linux/macOS/Windows/WSL)
+- Automatic platform detection and command selection
+- Silent failure on read errors to avoid spam
+
+Platform commands used:
+- Linux: `xclip` or `xsel`
+- macOS: `pbpaste`
+- Windows/WSL: `powershell.exe Get-Clipboard`
+
+### ProcessMonitor (Fully Implemented)
+
+Monitors running processes and detects lifecycle changes.
+
+```typescript
+import { ProcessMonitor } from './processes';
+
+const processes = new ProcessMonitor(5000); // Poll every 5 seconds
+
+processes.onEvent((event) => {
+  // event.type: 'process_started' or 'process_stopped'
+  // event.data: { pid, name, cpu?, memory? }
+});
+
+await processes.start();
+```
+
+Features:
+- Cross-platform process listing (Linux/macOS/Windows)
+- Detects new and terminated processes
+- Provides CPU and memory usage data
+- Automatic cleanup of terminated process records
+
+### NotificationListener (Stub)
+
+Placeholder for system notification monitoring.
+
+**TODO:**
+- Linux: Monitor D-Bus `org.freedesktop.Notifications`
+- Windows: Use PowerShell to read notification center
+- macOS: Use notification center API
+
+### CalendarSync (Stub)
+
+Placeholder for calendar integration.
+
+**TODO:**
+- Google Calendar API integration (OAuth2)
+- Microsoft Graph API (Outlook/Office 365)
+- CalDAV support for generic providers
+
+### EmailSync (Stub)
+
+Placeholder for email integration.
+
+**TODO:**
+- Gmail API integration (OAuth2)
+- Microsoft Graph API (Outlook/Office 365)
+- IMAP support for generic providers
+
+## ObserverManager
+
+The `ObserverManager` provides centralized control over all observers.
+
+```typescript
+import { ObserverManager, FileWatcher, ClipboardMonitor } from './observers';
+
+const manager = new ObserverManager();
+
+// Register observers
+manager.register(new FileWatcher(['/path/to/watch']));
+manager.register(new ClipboardMonitor(1000));
+
+// Set event handler (typically the Vault's ingestion function)
+manager.setEventHandler((event) => {
+  console.log(`[${event.type}]`, event.data);
+  // Forward to Vault for storage/analysis
+});
+
+// Start all observers
+await manager.startAll();
+
+// Get status
+console.log(manager.getStatus());
+// => { 'file-watcher': true, 'clipboard': true }
+
+// Stop specific observer
+await manager.stopObserver('clipboard');
+
+// Stop all observers
+await manager.stopAll();
+```
+
+### Manager API
+
+- `register(observer: Observer)` - Register a new observer
+- `setEventHandler(handler: ObserverEventHandler)` - Set global event handler
+- `startAll()` - Start all registered observers
+- `stopAll()` - Stop all registered observers
+- `startObserver(name: string)` - Start specific observer
+- `stopObserver(name: string)` - Stop specific observer
+- `getStatus()` - Get running status of all observers
+- `listObservers()` - Get list of registered observer names
+
+## Usage Example
+
+See `example.ts` for a complete working example:
+
+```bash
+bun run src/observers/example.ts
+```
+
+This will run all observers for 30 seconds and log events to the console.
+
+## Integration with Vault
+
+The Observer Layer is designed to integrate with the Vault for persistent storage:
+
+```typescript
+import { ObserverManager } from './observers';
+import { Vault } from '../vault';
+
+const vault = new Vault();
+const manager = new ObserverManager();
+
+// Register all observers...
+manager.register(new FileWatcher(['/home/user/projects']));
+// ... etc
+
+// Connect to Vault
+manager.setEventHandler((event) => {
+  vault.storeObservation(event);
+});
+
+await manager.startAll();
+```
+
+## Event Types
+
+Current event types emitted by observers:
+
+- `file_change` - File system change detected
+- `clipboard` - Clipboard content changed
+- `process_started` - New process started
+- `process_stopped` - Process terminated
+
+Future event types (when stubs are implemented):
+
+- `notification` - System notification received
+- `calendar_event` - Calendar event upcoming/created/updated
+- `new_email` - New email received
+- `email_read` - Email marked as read
+- `email_sent` - Email sent
+
+## Performance Considerations
+
+- **FileWatcher**: Uses native `node:fs` watch API with minimal overhead
+- **ClipboardMonitor**: Polling-based, configurable interval (default 1s)
+- **ProcessMonitor**: Polling-based, configurable interval (default 5s)
+- **Debouncing**: FileWatcher implements 100ms debouncing for rapid changes
+- **Memory**: Old debounce entries are automatically cleaned up
+
+## Error Handling
+
+All observers implement graceful error handling:
+
+- Silent failures for transient errors (e.g., clipboard read failures)
+- Console logging for persistent errors
+- Proper cleanup in `stop()` methods
+- Error isolation (one observer's failure doesn't affect others)
+
+## Platform Support
+
+- **Linux**: Full support for all implemented observers
+- **macOS**: Full support for all implemented observers
+- **Windows**: Full support for all implemented observers
+- **WSL**: Full support (uses Windows clipboard via PowerShell)
+
+## Testing
+
+Run the example to test all observers:
+
+```bash
+bun run src/observers/example.ts
+```
+
+Or create custom tests:
+
+```typescript
+import { test, expect } from 'bun:test';
+import { FileWatcher } from './file-watcher';
+
+test('FileWatcher starts and stops', async () => {
+  const watcher = new FileWatcher(['/tmp']);
+
+  expect(watcher.isRunning()).toBe(false);
+
+  await watcher.start();
+  expect(watcher.isRunning()).toBe(true);
+
+  await watcher.stop();
+  expect(watcher.isRunning()).toBe(false);
+});
+```