@usejarvis/brain 0.1.0

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 };

package/src/observers/file-watcher.ts

@@ -0,0 +1,124 @@
+/**
+ * FileWatcher - Monitors file system changes
+ *
+ * Watches specified directories recursively and emits events when files change.
+ * Includes debouncing to avoid duplicate rapid-fire events.
+ */
+
+import { watch, type FSWatcher } from 'node:fs';
+import type { Observer, ObserverEvent, ObserverEventHandler } from './index';
+
+type DebounceEntry = {
+  path: string;
+  timestamp: number;
+};
+
+export class FileWatcher implements Observer {
+  name = 'file-watcher';
+  private watchers: FSWatcher[] = [];
+  private paths: string[];
+  private handler: ObserverEventHandler | null = null;
+  private running = false;
+  private recentChanges: Map<string, number> = new Map();
+  private debounceMs = 100; // Ignore duplicate events within 100ms
+
+  constructor(paths: string[]) {
+    this.paths = paths;
+  }
+
+  async start(): Promise<void> {
+    if (this.running) {
+      console.log('[file-watcher] Already running');
+      return;
+    }
+
+    console.log('[file-watcher] Starting file system monitoring...');
+
+    for (const path of this.paths) {
+      try {
+        const watcher = watch(path, { recursive: true }, (eventType, filename) => {
+          this.handleFileEvent(path, eventType, filename);
+        });
+
+        watcher.on('error', (error) => {
+          console.error(`[file-watcher] Error watching ${path}:`, error);
+        });
+
+        this.watchers.push(watcher);
+        console.log(`[file-watcher] Watching: ${path}`);
+      } catch (error) {
+        console.error(`[file-watcher] Failed to watch ${path}:`, error);
+      }
+    }
+
+    this.running = true;
+  }
+
+  async stop(): Promise<void> {
+    if (!this.running) {
+      return;
+    }
+
+    console.log('[file-watcher] Stopping file system monitoring...');
+
+    for (const watcher of this.watchers) {
+      watcher.close();
+    }
+
+    this.watchers = [];
+    this.recentChanges.clear();
+    this.running = false;
+  }
+
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  onEvent(handler: ObserverEventHandler): void {
+    this.handler = handler;
+  }
+
+  private handleFileEvent(
+    basePath: string,
+    eventType: 'rename' | 'change',
+    filename: string | null
+  ): void {
+    if (!filename || !this.handler) {
+      return;
+    }
+
+    const fullPath = `${basePath}/${filename}`;
+    const now = Date.now();
+
+    // Debounce: skip if same file changed within debounceMs
+    const lastChange = this.recentChanges.get(fullPath);
+    if (lastChange && now - lastChange < this.debounceMs) {
+      return;
+    }
+
+    this.recentChanges.set(fullPath, now);
+
+    // Clean up old entries to prevent memory leak
+    if (this.recentChanges.size > 1000) {
+      const cutoff = now - this.debounceMs * 2;
+      for (const [path, timestamp] of this.recentChanges.entries()) {
+        if (timestamp < cutoff) {
+          this.recentChanges.delete(path);
+        }
+      }
+    }
+
+    const event: ObserverEvent = {
+      type: 'file_change',
+      data: {
+        path: fullPath,
+        eventType,
+        filename,
+        basePath,
+      },
+      timestamp: now,
+    };
+
+    this.handler(event);
+  }
+}

package/src/observers/index.ts

@@ -0,0 +1,159 @@
+/**
+ * Observer Layer - Monitors system events and emits observations to the Vault
+ *
+ * All observers implement a common interface and emit standardized events.
+ */
+
+// Common Observer Interface
+export type ObserverEvent = {
+  type: string;
+  data: Record<string, unknown>;
+  timestamp: number;
+};
+
+export type ObserverEventHandler = (event: ObserverEvent) => void;
+
+export interface Observer {
+  name: string;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  isRunning(): boolean;
+  onEvent(handler: ObserverEventHandler): void;
+}
+
+// Export all observers
+export { FileWatcher } from './file-watcher';
+export { ClipboardMonitor } from './clipboard';
+export { NotificationListener } from './notifications';
+export { ProcessMonitor } from './processes';
+export { CalendarSync } from './calendar';
+export { EmailSync } from './email';
+
+/**
+ * ObserverManager - Centralized coordinator for all observers
+ */
+export class ObserverManager {
+  private observers: Map<string, Observer> = new Map();
+  private eventHandler: ObserverEventHandler | null = null;
+
+  /**
+   * Register a new observer
+   */
+  register(observer: Observer): void {
+    this.observers.set(observer.name, observer);
+
+    // If we already have a handler, apply it to the new observer
+    if (this.eventHandler) {
+      observer.onEvent(this.eventHandler);
+    }
+
+    console.log(`[ObserverManager] Registered observer: ${observer.name}`);
+  }
+
+  /**
+   * Set the global event handler for all observers
+   * This is typically the Vault's observation ingestion function
+   */
+  setEventHandler(handler: ObserverEventHandler): void {
+    this.eventHandler = handler;
+
+    // Apply handler to all registered observers
+    for (const observer of this.observers.values()) {
+      observer.onEvent(handler);
+    }
+
+    console.log(`[ObserverManager] Event handler configured for ${this.observers.size} observers`);
+  }
+
+  /**
+   * Start all registered observers
+   */
+  async startAll(): Promise<void> {
+    console.log('[ObserverManager] Starting all observers...');
+
+    const promises = Array.from(this.observers.values()).map(async (observer) => {
+      try {
+        await observer.start();
+        console.log(`[ObserverManager] ✓ Started ${observer.name}`);
+      } catch (error) {
+        console.error(`[ObserverManager] ✗ Failed to start ${observer.name}:`, error);
+      }
+    });
+
+    await Promise.all(promises);
+    console.log('[ObserverManager] All observers started');
+  }
+
+  /**
+   * Stop all registered observers
+   */
+  async stopAll(): Promise<void> {
+    console.log('[ObserverManager] Stopping all observers...');
+
+    const promises = Array.from(this.observers.values()).map(async (observer) => {
+      try {
+        await observer.stop();
+        console.log(`[ObserverManager] ✓ Stopped ${observer.name}`);
+      } catch (error) {
+        console.error(`[ObserverManager] ✗ Failed to stop ${observer.name}:`, error);
+      }
+    });
+
+    await Promise.all(promises);
+    console.log('[ObserverManager] All observers stopped');
+  }
+
+  /**
+   * Start a specific observer by name
+   */
+  async startObserver(name: string): Promise<void> {
+    const observer = this.observers.get(name);
+    if (!observer) {
+      throw new Error(`Observer not found: ${name}`);
+    }
+
+    if (observer.isRunning()) {
+      console.log(`[ObserverManager] Observer ${name} is already running`);
+      return;
+    }
+
+    await observer.start();
+    console.log(`[ObserverManager] Started ${name}`);
+  }
+
+  /**
+   * Stop a specific observer by name
+   */
+  async stopObserver(name: string): Promise<void> {
+    const observer = this.observers.get(name);
+    if (!observer) {
+      throw new Error(`Observer not found: ${name}`);
+    }
+
+    if (!observer.isRunning()) {
+      console.log(`[ObserverManager] Observer ${name} is not running`);
+      return;
+    }
+
+    await observer.stop();
+    console.log(`[ObserverManager] Stopped ${name}`);
+  }
+
+  /**
+   * Get running status of all observers
+   */
+  getStatus(): Record<string, boolean> {
+    const status: Record<string, boolean> = {};
+    for (const [name, observer] of this.observers) {
+      status[name] = observer.isRunning();
+    }
+    return status;
+  }
+
+  /**
+   * List all registered observer names
+   */
+  listObservers(): string[] {
+    return Array.from(this.observers.keys());
+  }
+}