@shykaruu/jarvis-brain 0.4.0

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);
+});
+```

package/src/observers/calendar.ts

@@ -0,0 +1,113 @@
+/**
+ * CalendarSync — Google Calendar Observer
+ *
+ * Polls Calendar API every 2 minutes with a 30-minute look-ahead.
+ * Tracks announced event IDs to avoid duplicate alerts.
+ * Graceful: if no Google tokens, logs warning and stays no-op.
+ */
+
+import type { Observer, ObserverEventHandler } from './index';
+import type { GoogleAuth } from '../integrations/google-auth.ts';
+import { listUpcomingEvents } from '../integrations/google-api.ts';
+
+const POLL_INTERVAL_MS = 2 * 60_000;  // 2 minutes
+const LOOK_AHEAD_MS = 30 * 60_000;    // 30 minutes
+
+export class CalendarSync implements Observer {
+  name = 'calendar';
+  private running = false;
+  private handler: ObserverEventHandler | null = null;
+  private pollTimer: Timer | null = null;
+  private googleAuth: GoogleAuth | null;
+  private announcedEventIds: Set<string> = new Set();
+  private calendarId: string;
+
+  constructor(googleAuth?: GoogleAuth, calendarId?: string) {
+    this.googleAuth = googleAuth ?? null;
+    this.calendarId = calendarId ?? 'primary';
+  }
+
+  async start(): Promise<void> {
+    this.running = true;
+
+    if (!this.googleAuth || !this.googleAuth.isAuthenticated()) {
+      console.log('[calendar] No Google auth configured — calendar monitoring disabled');
+      console.log('[calendar] Run: bun run src/scripts/google-setup.ts to set up Calendar');
+      return;
+    }
+
+    console.log('[calendar] Observer started — polling Calendar every 2min (30min look-ahead)');
+
+    // Initial poll
+    this.poll();
+
+    // Set up recurring poll
+    this.pollTimer = setInterval(() => this.poll(), POLL_INTERVAL_MS);
+  }
+
+  async stop(): Promise<void> {
+    this.running = false;
+
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+
+    console.log('[calendar] Observer stopped');
+  }
+
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  onEvent(handler: ObserverEventHandler): void {
+    this.handler = handler;
+  }
+
+  private async poll(): Promise<void> {
+    if (!this.googleAuth || !this.handler) return;
+
+    try {
+      const accessToken = await this.googleAuth.getAccessToken();
+      const now = new Date();
+      const later = new Date(now.getTime() + LOOK_AHEAD_MS);
+
+      const events = await listUpcomingEvents(
+        accessToken,
+        this.calendarId,
+        now.toISOString(),
+        later.toISOString(),
+        10
+      );
+
+      for (const event of events) {
+        // Skip already-announced events
+        if (this.announcedEventIds.has(event.id)) continue;
+        this.announcedEventIds.add(event.id);
+
+        this.handler({
+          type: 'calendar',
+          data: {
+            id: event.id,
+            summary: event.summary,
+            description: event.description,
+            start: event.start,
+            end: event.end,
+            location: event.location,
+            attendees: event.attendees,
+            htmlLink: event.htmlLink,
+          },
+          timestamp: Date.now(),
+        });
+      }
+
+      // Cap announcedEventIds to prevent unbounded growth
+      if (this.announcedEventIds.size > 500) {
+        const arr = Array.from(this.announcedEventIds);
+        this.announcedEventIds = new Set(arr.slice(arr.length - 250));
+      }
+    } catch (err) {
+      console.error('[calendar] Poll error:', err);
+    }
+  }
+}

package/src/observers/clipboard.ts

@@ -0,0 +1,136 @@
+/**
+ * ClipboardMonitor - Monitors clipboard changes
+ *
+ * Polls the system clipboard at regular intervals and emits events when content changes.
+ * Uses platform-specific commands to read clipboard content.
+ */
+
+import type { Observer, ObserverEvent, ObserverEventHandler } from './index';
+
+export class ClipboardMonitor implements Observer {
+  name = 'clipboard';
+  private interval: Timer | null = null;
+  private lastContent: string = '';
+  private handler: ObserverEventHandler | null = null;
+  private running = false;
+  private pollMs: number;
+
+  constructor(pollMs: number = 1000) {
+    this.pollMs = pollMs;
+  }
+
+  async start(): Promise<void> {
+    if (this.running) {
+      console.log('[clipboard] Already running');
+      return;
+    }
+
+    console.log(`[clipboard] Starting clipboard monitoring (polling every ${this.pollMs}ms)...`);
+
+    // Initialize with current clipboard content
+    try {
+      this.lastContent = await this.readClipboard();
+    } catch (error) {
+      console.error('[clipboard] Failed to read initial clipboard:', error);
+      this.lastContent = '';
+    }
+
+    // Start polling
+    this.interval = setInterval(async () => {
+      try {
+        const content = await this.readClipboard();
+
+        if (content !== this.lastContent) {
+          this.lastContent = content;
+
+          if (this.handler) {
+            const event: ObserverEvent = {
+              type: 'clipboard',
+              data: {
+                content,
+                length: content.length,
+              },
+              timestamp: Date.now(),
+            };
+
+            this.handler(event);
+          }
+        }
+      } catch (error) {
+        // Silent fail on read errors to avoid spam
+        // console.error('[clipboard] Failed to read clipboard:', error);
+      }
+    }, this.pollMs);
+
+    this.running = true;
+  }
+
+  async stop(): Promise<void> {
+    if (!this.running) {
+      return;
+    }
+
+    console.log('[clipboard] Stopping clipboard monitoring...');
+
+    if (this.interval) {
+      clearInterval(this.interval);
+      this.interval = null;
+    }
+
+    this.running = false;
+  }
+
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  onEvent(handler: ObserverEventHandler): void {
+    this.handler = handler;
+  }
+
+  /**
+   * Read clipboard content using platform-specific commands
+   */
+  private async readClipboard(): Promise<string> {
+    const platform = process.platform;
+
+    try {
+      let result: { stdout: Buffer; stderr: Buffer };
+
+      if (platform === 'linux') {
+        // Try xclip first
+        try {
+          result = await Bun.$`xclip -selection clipboard -o`.quiet();
+          return result.stdout.toString().trim();
+        } catch {
+          // Fall back to xsel
+          try {
+            result = await Bun.$`xsel --clipboard --output`.quiet();
+            return result.stdout.toString().trim();
+          } catch {
+            // Check if we're in WSL and can use PowerShell
+            try {
+              result = await Bun.$`powershell.exe Get-Clipboard`.quiet();
+              return result.stdout.toString().trim();
+            } catch {
+              throw new Error('No clipboard tool available (tried xclip, xsel, powershell.exe)');
+            }
+          }
+        }
+      } else if (platform === 'darwin') {
+        // macOS
+        result = await Bun.$`pbpaste`.quiet();
+        return result.stdout.toString().trim();
+      } else if (platform === 'win32') {
+        // Windows
+        result = await Bun.$`powershell.exe Get-Clipboard`.quiet();
+        return result.stdout.toString().trim();
+      } else {
+        throw new Error(`Unsupported platform: ${platform}`);
+      }
+    } catch (error) {
+      // Return empty string on error
+      return '';
+    }
+  }
+}

package/src/observers/email.ts

@@ -0,0 +1,109 @@
+/**
+ * EmailSync — Gmail Observer
+ *
+ * Polls Gmail API every 60s for unread messages.
+ * Tracks seen message IDs to avoid re-emitting.
+ * Fetches detail (subject, from, snippet) for new messages.
+ * Graceful: if no Google tokens, logs warning and stays no-op.
+ */
+
+import type { Observer, ObserverEventHandler } from './index';
+import type { GoogleAuth } from '../integrations/google-auth.ts';
+import { listUnreadEmails, getEmailDetail } from '../integrations/google-api.ts';
+
+const POLL_INTERVAL_MS = 60_000; // 60 seconds
+
+export class EmailSync implements Observer {
+  name = 'email';
+  private running = false;
+  private handler: ObserverEventHandler | null = null;
+  private pollTimer: Timer | null = null;
+  private googleAuth: GoogleAuth | null;
+  private seenMessageIds: Set<string> = new Set();
+
+  constructor(googleAuth?: GoogleAuth) {
+    this.googleAuth = googleAuth ?? null;
+  }
+
+  async start(): Promise<void> {
+    this.running = true;
+
+    if (!this.googleAuth || !this.googleAuth.isAuthenticated()) {
+      console.log('[email] No Google auth configured — email monitoring disabled');
+      console.log('[email] Run: bun run src/scripts/google-setup.ts to set up Gmail');
+      return;
+    }
+
+    console.log('[email] Observer started — polling Gmail every 60s');
+
+    // Initial poll
+    this.poll();
+
+    // Set up recurring poll
+    this.pollTimer = setInterval(() => this.poll(), POLL_INTERVAL_MS);
+  }
+
+  async stop(): Promise<void> {
+    this.running = false;
+
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+
+    console.log('[email] Observer stopped');
+  }
+
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  onEvent(handler: ObserverEventHandler): void {
+    this.handler = handler;
+  }
+
+  private async poll(): Promise<void> {
+    if (!this.googleAuth || !this.handler) return;
+
+    try {
+      const accessToken = await this.googleAuth.getAccessToken();
+      const messages = await listUnreadEmails(accessToken, 10);
+
+      for (const msg of messages) {
+        // Skip already-seen messages
+        if (this.seenMessageIds.has(msg.id)) continue;
+        this.seenMessageIds.add(msg.id);
+
+        // Fetch detail
+        try {
+          const detail = await getEmailDetail(accessToken, msg.id);
+
+          this.handler({
+            type: 'email',
+            data: {
+              id: detail.id,
+              threadId: detail.threadId,
+              subject: detail.subject,
+              from: detail.from,
+              to: detail.to,
+              date: detail.date,
+              snippet: detail.snippet,
+              labels: detail.labels,
+            },
+            timestamp: Date.now(),
+          });
+        } catch (err) {
+          console.error(`[email] Failed to get detail for ${msg.id}:`, err);
+        }
+      }
+
+      // Cap seenMessageIds to prevent unbounded growth
+      if (this.seenMessageIds.size > 1000) {
+        const arr = Array.from(this.seenMessageIds);
+        this.seenMessageIds = new Set(arr.slice(arr.length - 500));
+      }
+    } catch (err) {
+      console.error('[email] Poll error:', err);
+    }
+  }
+}

package/src/observers/example.ts

@@ -0,0 +1,58 @@
+/**
+ * Example usage of the Observer Layer
+ *
+ * This demonstrates how to set up and use the ObserverManager with various observers.
+ */
+
+import {
+  ObserverManager,
+  FileWatcher,
+  ClipboardMonitor,
+  ProcessMonitor,
+  NotificationListener,
+  CalendarSync,
+  EmailSync,
+  type ObserverEvent,
+} from './index';
+
+async function main() {
+  // Create the manager
+  const manager = new ObserverManager();
+
+  // Register observers
+  manager.register(new FileWatcher([import.meta.dir + '/../'])); // Watch src directory
+  manager.register(new ClipboardMonitor(2000)); // Poll clipboard every 2 seconds
+  manager.register(new ProcessMonitor(10000)); // Poll processes every 10 seconds
+  manager.register(new NotificationListener()); // Stub
+  manager.register(new CalendarSync()); // Stub
+  manager.register(new EmailSync()); // Stub
+
+  // Set up event handler (this would typically be the Vault's ingestion function)
+  manager.setEventHandler((event: ObserverEvent) => {
+    console.log(`[EVENT] ${event.type} at ${new Date(event.timestamp).toISOString()}`);
+    console.log('  Data:', JSON.stringify(event.data, null, 2));
+  });
+
+  // Start all observers
+  await manager.startAll();
+
+  // Get status
+  console.log('\n[STATUS] Observer running status:', manager.getStatus());
+
+  // Run for 30 seconds, then stop
+  console.log('\n[INFO] Running observers for 30 seconds...\n');
+
+  await new Promise(resolve => setTimeout(resolve, 30000));
+
+  // Stop all observers
+  await manager.stopAll();
+
+  console.log('\n[INFO] Example complete');
+}
+
+// Run example if executed directly
+if (import.meta.main) {
+  main().catch(console.error);
+}
+
+export { main };