@usejarvis/brain 0.1.0

package/src/workflows/triggers/observer-bridge.ts

@@ -0,0 +1,172 @@
+/**
+ * ObserverBridge — thin adapter between the Observer layer and workflow triggers
+ *
+ * Subscribes to ObserverManager events and routes them to the trigger system,
+ * mapping observer event types to canonical workflow trigger event types.
+ */
+
+import type { ObserverManager, ObserverEvent } from '../../observers/index.ts';
+
+// ── Types ──
+
+/**
+ * Canonical workflow trigger event types sourced from the Observer layer.
+ */
+export type ObserverTriggerType =
+  | 'file_change'
+  | 'clipboard'
+  | 'process'
+  | 'email'
+  | 'calendar'
+  | 'notification'
+  | 'screen';
+
+export type TriggerCallback = (eventType: ObserverTriggerType, data: Record<string, unknown>) => void;
+
+// ── Event type mapping ──
+
+/**
+ * Maps raw observer event type strings (observer.name + "." + event sub-type)
+ * to canonical workflow trigger types.
+ *
+ * Observer names and event types observed in the codebase:
+ *   - FileWatcher:          file_changed, file_created, file_deleted
+ *   - ClipboardMonitor:     clipboard_changed
+ *   - ProcessMonitor:       process_started, process_stopped, process_changed
+ *   - EmailSync:            email_received, email_sent
+ *   - CalendarSync:         calendar_event_created, calendar_event_updated, calendar_event_reminder
+ *   - NotificationListener: notification_received
+ *   - Screen/awareness:     screen_changed, screen_text_detected
+ */
+const EVENT_TYPE_MAP: Record<string, ObserverTriggerType> = {
+  // File watcher
+  file_changed: 'file_change',
+  file_created: 'file_change',
+  file_deleted: 'file_change',
+  file_modified: 'file_change',
+
+  // Clipboard
+  clipboard_changed: 'clipboard',
+  clipboard_copied: 'clipboard',
+
+  // Process monitor
+  process_started: 'process',
+  process_stopped: 'process',
+  process_changed: 'process',
+  process_exited: 'process',
+
+  // Email
+  email_received: 'email',
+  email_sent: 'email',
+  email_new: 'email',
+
+  // Calendar
+  calendar_event_created: 'calendar',
+  calendar_event_updated: 'calendar',
+  calendar_event_reminder: 'calendar',
+  calendar_event_deleted: 'calendar',
+
+  // Notifications
+  notification_received: 'notification',
+
+  // Screen / awareness
+  screen_changed: 'screen',
+  screen_text_detected: 'screen',
+  screen_app_switched: 'screen',
+  ocr_text_changed: 'screen',
+};
+
+// ── ObserverBridge ──
+
+export class ObserverBridge {
+  private observerManager: ObserverManager;
+  private triggerCallback: TriggerCallback | null = null;
+  private running = false;
+
+  constructor(observerManager: ObserverManager) {
+    this.observerManager = observerManager;
+  }
+
+  /**
+   * Set the callback invoked when an observer event arrives.
+   */
+  setTriggerCallback(cb: TriggerCallback): void {
+    this.triggerCallback = cb;
+  }
+
+  /**
+   * Start the bridge — subscribe to all observer events.
+   */
+  start(): void {
+    if (this.running) return;
+
+    this.observerManager.setEventHandler((event: ObserverEvent) => {
+      this.routeEvent(event);
+    });
+
+    this.running = true;
+    console.log('[ObserverBridge] Started — listening to observer events');
+  }
+
+  /**
+   * Stop the bridge — clear the event handler.
+   * Observers continue running; we just stop routing their events.
+   */
+  stop(): void {
+    if (!this.running) return;
+
+    // Replace the handler with a no-op so we stop routing events
+    this.observerManager.setEventHandler(() => {});
+
+    this.running = false;
+    console.log('[ObserverBridge] Stopped');
+  }
+
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  // ── Internal ──
+
+  private routeEvent(event: ObserverEvent): void {
+    if (!this.triggerCallback) return;
+
+    const triggerType = this.mapEventType(event.type);
+    if (!triggerType) {
+      // Unknown event type — skip silently
+      return;
+    }
+
+    const data: Record<string, unknown> = {
+      ...event.data,
+      _observer: {
+        originalType: event.type,
+        timestamp: event.timestamp,
+      },
+    };
+
+    try {
+      this.triggerCallback(triggerType, data);
+    } catch (err) {
+      console.error(`[ObserverBridge] Trigger callback threw for event type "${triggerType}":`, err);
+    }
+  }
+
+  private mapEventType(rawType: string): ObserverTriggerType | null {
+    // Direct match
+    if (rawType in EVENT_TYPE_MAP) {
+      return EVENT_TYPE_MAP[rawType]!;
+    }
+
+    // Prefix match (e.g. "file_" -> file_change)
+    if (rawType.startsWith('file_')) return 'file_change';
+    if (rawType.startsWith('clipboard_')) return 'clipboard';
+    if (rawType.startsWith('process_')) return 'process';
+    if (rawType.startsWith('email_')) return 'email';
+    if (rawType.startsWith('calendar_')) return 'calendar';
+    if (rawType.startsWith('notification_')) return 'notification';
+    if (rawType.startsWith('screen_') || rawType.startsWith('ocr_')) return 'screen';
+
+    return null;
+  }
+}

package/src/workflows/triggers/poller.ts

@@ -0,0 +1,201 @@
+/**
+ * PollingEngine — outbound HTTP polling with deduplication
+ *
+ * Registers named polling jobs that periodically fetch a URL and invoke
+ * a callback when new data is detected (deduplicated by a configured field).
+ */
+
+// ── Types ──
+
+export type PollConfig = {
+  /** Target URL to poll */
+  url: string;
+  /** How often to poll in milliseconds */
+  intervalMs: number;
+  /** HTTP method (default: GET) */
+  method?: string;
+  /** Additional request headers */
+  headers?: Record<string, string>;
+  /** Request body (for POST/PUT) */
+  body?: string;
+  /**
+   * JSON path (dot-notation) into the response used for deduplication.
+   * If set, the callback is only fired when this value changes.
+   * Example: "data.updatedAt" or "id"
+   */
+  deduplicateField?: string;
+};
+
+export type PollCallback = (data: unknown, meta: PollMeta) => void;
+
+export type PollMeta = {
+  id: string;
+  url: string;
+  status: number;
+  timestamp: number;
+};
+
+type PollJob = {
+  id: string;
+  config: PollConfig;
+  callback: PollCallback;
+  handle: ReturnType<typeof setInterval>;
+  lastDeduplicateValue: unknown;
+  lastPolledAt: number | null;
+};
+
+// ── Helpers ──
+
+/**
+ * Traverse a dot-separated path on an object.
+ */
+function getNestedValue(obj: unknown, path: string): unknown {
+  if (!obj || typeof obj !== 'object') return undefined;
+  const parts = path.split('.');
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current === null || current === undefined) return undefined;
+    if (typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+// ── PollingEngine ──
+
+export class PollingEngine {
+  private jobs: Map<string, PollJob> = new Map();
+
+  /**
+   * Register and start a polling job.
+   */
+  register(id: string, config: PollConfig, callback: PollCallback): void {
+    if (this.jobs.has(id)) {
+      this.unregister(id);
+    }
+
+    if (config.intervalMs < 1000) {
+      throw new Error(`Poll interval for "${id}" must be at least 1000ms`);
+    }
+
+    const job: PollJob = {
+      id,
+      config,
+      callback,
+      handle: null as unknown as ReturnType<typeof setInterval>,
+      lastDeduplicateValue: Symbol('unset'),  // Sentinel: never equal to real data
+      lastPolledAt: null,
+    };
+
+    const handle = setInterval(() => this.poll(id), config.intervalMs);
+    job.handle = handle;
+    this.jobs.set(id, job);
+
+    console.log(`[PollingEngine] Registered poll job "${id}" -> ${config.url} (every ${config.intervalMs}ms)`);
+
+    // Run immediately on first registration
+    this.poll(id).catch(err => {
+      console.error(`[PollingEngine] Initial poll for "${id}" failed:`, err);
+    });
+  }
+
+  /**
+   * Stop and remove a polling job.
+   */
+  unregister(id: string): void {
+    const job = this.jobs.get(id);
+    if (job) {
+      clearInterval(job.handle);
+      this.jobs.delete(id);
+      console.log(`[PollingEngine] Unregistered poll job "${id}"`);
+    }
+  }
+
+  /**
+   * Stop and remove all polling jobs.
+   */
+  unregisterAll(): void {
+    for (const job of this.jobs.values()) {
+      clearInterval(job.handle);
+    }
+    this.jobs.clear();
+    console.log('[PollingEngine] All poll jobs unregistered');
+  }
+
+  /**
+   * Returns IDs of all active poll jobs.
+   */
+  getJobIds(): string[] {
+    return Array.from(this.jobs.keys());
+  }
+
+  // ── Internal ──
+
+  private async poll(id: string): Promise<void> {
+    const job = this.jobs.get(id);
+    if (!job) return;
+
+    const { config, callback } = job;
+    const timestamp = Date.now();
+    job.lastPolledAt = timestamp;
+
+    let response: Response;
+    try {
+      response = await fetch(config.url, {
+        method: config.method ?? 'GET',
+        headers: config.headers,
+        body: config.body,
+        signal: AbortSignal.timeout(30_000),
+      });
+    } catch (err) {
+      console.error(`[PollingEngine] Fetch failed for "${id}" (${config.url}):`, err);
+      return;
+    }
+
+    if (!response.ok) {
+      console.warn(`[PollingEngine] Poll "${id}" got HTTP ${response.status}`);
+      return;
+    }
+
+    let data: unknown;
+    const contentType = response.headers.get('content-type') ?? '';
+
+    try {
+      if (contentType.includes('application/json')) {
+        data = await response.json();
+      } else {
+        data = await response.text();
+      }
+    } catch (err) {
+      console.error(`[PollingEngine] Failed to parse response for "${id}":`, err);
+      return;
+    }
+
+    // Deduplication check
+    if (config.deduplicateField) {
+      const currentValue = getNestedValue(data, config.deduplicateField);
+      const serialized = JSON.stringify(currentValue);
+      const lastSerialized = JSON.stringify(job.lastDeduplicateValue);
+
+      if (serialized === lastSerialized) {
+        // No change — skip callback
+        return;
+      }
+
+      job.lastDeduplicateValue = currentValue;
+    }
+
+    const meta: PollMeta = {
+      id,
+      url: config.url,
+      status: response.status,
+      timestamp,
+    };
+
+    try {
+      callback(data, meta);
+    } catch (err) {
+      console.error(`[PollingEngine] Callback for "${id}" threw:`, err);
+    }
+  }
+}

package/src/workflows/triggers/screen-condition.ts

@@ -0,0 +1,218 @@
+/**
+ * ScreenConditionEvaluator — evaluates visual conditions for screen-based triggers
+ *
+ * Supports instant text/app conditions as well as LLM-backed visual checks.
+ */
+
+// ── Types ──
+
+export type ScreenConditionType =
+  | 'text_present'
+  | 'text_absent'
+  | 'app_active'
+  | 'visual_match'
+  | 'llm_check';
+
+export type ScreenCondition = {
+  type: ScreenConditionType;
+  /** For text_present / text_absent: the text substring to look for */
+  text?: string;
+  /** For app_active: the application name to check */
+  appName?: string;
+  /** For visual_match: a description of what should be visible */
+  description?: string;
+  /** For llm_check: a natural-language prompt sent to the LLM */
+  prompt?: string;
+  /** Optional: case-sensitive matching (default: false) */
+  caseSensitive?: boolean;
+};
+
+export type ConditionResult = {
+  matched: boolean;
+  reason: string;
+};
+
+// ── ScreenConditionEvaluator ──
+
+export class ScreenConditionEvaluator {
+  private llmManager: unknown;
+
+  constructor(llmManager: unknown) {
+    this.llmManager = llmManager;
+  }
+
+  /**
+   * Evaluate a screen condition.
+   *
+   * - text_present / text_absent: instant, no LLM needed
+   * - app_active: instant, checks appName against current active app
+   * - visual_match / llm_check: defers to LLM (async, requires llmManager)
+   *
+   * @param condition - The condition to evaluate
+   * @param ocrText - Current screen OCR text (for text-based conditions)
+   * @param appName - Currently active application name (for app_active)
+   * @returns boolean result
+   */
+  async evaluate(
+    condition: ScreenCondition,
+    ocrText?: string,
+    appName?: string,
+  ): Promise<boolean> {
+    switch (condition.type) {
+      case 'text_present':
+        return this.evaluateTextPresent(condition, ocrText ?? '');
+
+      case 'text_absent':
+        return this.evaluateTextAbsent(condition, ocrText ?? '');
+
+      case 'app_active':
+        return this.evaluateAppActive(condition, appName ?? '');
+
+      case 'visual_match':
+        return this.evaluateVisualMatch(condition, ocrText ?? '', appName ?? '');
+
+      case 'llm_check':
+        return this.evaluateLlmCheck(condition, ocrText ?? '', appName ?? '');
+
+      default: {
+        // TypeScript exhaustiveness guard
+        const _exhaustive: never = condition.type;
+        console.warn(`[ScreenConditionEvaluator] Unknown condition type: ${String(_exhaustive)}`);
+        return false;
+      }
+    }
+  }
+
+  // ── Instant evaluators ──
+
+  private evaluateTextPresent(condition: ScreenCondition, ocrText: string): boolean {
+    if (!condition.text) {
+      console.warn('[ScreenConditionEvaluator] text_present condition missing "text" field');
+      return false;
+    }
+
+    if (condition.caseSensitive) {
+      return ocrText.includes(condition.text);
+    }
+
+    return ocrText.toLowerCase().includes(condition.text.toLowerCase());
+  }
+
+  private evaluateTextAbsent(condition: ScreenCondition, ocrText: string): boolean {
+    return !this.evaluateTextPresent({ ...condition, type: 'text_present' }, ocrText);
+  }
+
+  private evaluateAppActive(condition: ScreenCondition, activeApp: string): boolean {
+    if (!condition.appName) {
+      console.warn('[ScreenConditionEvaluator] app_active condition missing "appName" field');
+      return false;
+    }
+
+    // No active app is running — condition cannot match
+    if (!activeApp) return false;
+
+    const target = condition.caseSensitive
+      ? condition.appName
+      : condition.appName.toLowerCase();
+
+    const current = condition.caseSensitive
+      ? activeApp
+      : activeApp.toLowerCase();
+
+    // Support partial match (e.g. "Chrome" matches "Google Chrome")
+    return current.includes(target) || target.includes(current);
+  }
+
+  // ── LLM-backed evaluators ──
+
+  private async evaluateVisualMatch(
+    condition: ScreenCondition,
+    ocrText: string,
+    appName: string,
+  ): Promise<boolean> {
+    if (!condition.description) {
+      console.warn('[ScreenConditionEvaluator] visual_match condition missing "description" field');
+      return false;
+    }
+
+    if (!this.llmManager) {
+      console.warn('[ScreenConditionEvaluator] No LLM manager available for visual_match — returning false');
+      return false;
+    }
+
+    const prompt = [
+      `You are evaluating a screen condition for workflow automation.`,
+      ``,
+      `Current screen state:`,
+      `- Active application: ${appName || '(unknown)'}`,
+      `- OCR text on screen: ${ocrText ? `"${ocrText.slice(0, 2000)}"` : '(none)'}`,
+      ``,
+      `Condition to check: "${condition.description}"`,
+      ``,
+      `Does the current screen state match this description? Answer with ONLY "yes" or "no".`,
+    ].join('\n');
+
+    return this.askLlm(prompt);
+  }
+
+  private async evaluateLlmCheck(
+    condition: ScreenCondition,
+    ocrText: string,
+    appName: string,
+  ): Promise<boolean> {
+    if (!condition.prompt) {
+      console.warn('[ScreenConditionEvaluator] llm_check condition missing "prompt" field');
+      return false;
+    }
+
+    if (!this.llmManager) {
+      console.warn('[ScreenConditionEvaluator] No LLM manager available for llm_check — returning false');
+      return false;
+    }
+
+    const systemContext = [
+      `You are a screen state evaluator for workflow automation.`,
+      `Current screen state:`,
+      `- Active application: ${appName || '(unknown)'}`,
+      `- OCR text visible: ${ocrText ? `"${ocrText.slice(0, 2000)}"` : '(none)'}`,
+      ``,
+      `Answer the following question about the screen state with ONLY "yes" or "no".`,
+    ].join('\n');
+
+    const fullPrompt = `${systemContext}\n\n${condition.prompt}`;
+    return this.askLlm(fullPrompt);
+  }
+
+  /**
+   * Ask the LLM manager a yes/no question and parse the response.
+   */
+  private async askLlm(prompt: string): Promise<boolean> {
+    try {
+      // llmManager is loosely typed (unknown) to avoid circular deps.
+      // We cast it to access the expected interface.
+      const mgr = this.llmManager as {
+        complete?: (prompt: string, opts?: Record<string, unknown>) => Promise<{ text: string }>;
+        chat?: (messages: Array<{ role: string; content: string }>) => Promise<{ content: string }>;
+      };
+
+      let responseText: string | null = null;
+
+      if (typeof mgr.complete === 'function') {
+        const result = await mgr.complete(prompt, { max_tokens: 10, temperature: 0 });
+        responseText = result.text;
+      } else if (typeof mgr.chat === 'function') {
+        const result = await mgr.chat([{ role: 'user', content: prompt }]);
+        responseText = result.content;
+      } else {
+        console.warn('[ScreenConditionEvaluator] llmManager has no usable interface');
+        return false;
+      }
+
+      const normalized = (responseText ?? '').trim().toLowerCase();
+      return normalized.startsWith('yes');
+    } catch (err) {
+      console.error('[ScreenConditionEvaluator] LLM evaluation failed:', err);
+      return false;
+    }
+  }
+}