@usejarvis/brain 0.1.0

package/src/daemon/commitment-executor.ts

@@ -0,0 +1,297 @@
+/**
+ * CommitmentExecutor — Notify-Then-Execute Engine
+ *
+ * Detects due commitments, announces pending execution to the UI
+ * with a cancel window, then forces the agent to execute if not cancelled.
+ *
+ * Aggressiveness modes:
+ *   passive:    announce only, never auto-execute
+ *   moderate:   30s cancel window (default)
+ *   aggressive: 5s cancel window
+ */
+
+import { getDueCommitments, getUpcoming, updateCommitmentStatus } from '../vault/commitments.ts';
+import type { Commitment } from '../vault/commitments.ts';
+import type { IAgentService } from './agent-service-interface.ts';
+import type { WSMessage } from '../comms/websocket.ts';
+
+export type Aggressiveness = 'passive' | 'moderate' | 'aggressive';
+
+export type ExecutionState = {
+  commitmentId: string;
+  what: string;
+  announcedAt: number;
+  cancelDeadline: number;
+  cancelled: boolean;
+  executed: boolean;
+};
+
+export type BroadcastFn = (msg: WSMessage) => void;
+
+const CANCEL_WINDOW: Record<Aggressiveness, number> = {
+  passive: Infinity,
+  moderate: 30_000,
+  aggressive: 5_000,
+};
+
+export class CommitmentExecutor {
+  private agentService: IAgentService | null = null;
+  private broadcast: BroadcastFn | null = null;
+  private pending: Map<string, ExecutionState> = new Map();
+  private executedIds: Set<string> = new Set();
+  private checkTimer: Timer | null = null;
+  private tickTimer: Timer | null = null;
+  private aggressiveness: Aggressiveness;
+  private running = false;
+
+  constructor(aggressiveness: Aggressiveness = 'moderate') {
+    this.aggressiveness = aggressiveness;
+  }
+
+  setAgentService(agent: IAgentService): void {
+    this.agentService = agent;
+  }
+
+  setBroadcast(fn: BroadcastFn): void {
+    this.broadcast = fn;
+  }
+
+  start(): void {
+    if (this.running) return;
+    this.running = true;
+
+    // Check for due commitments every 60 seconds
+    this.checkTimer = setInterval(() => {
+      this.checkAndAnnounce();
+    }, 60_000);
+
+    // Tick pending executions every 5 seconds
+    this.tickTimer = setInterval(() => {
+      this.tickExecutions().catch((err) =>
+        console.error('[Executor] Tick error:', err)
+      );
+    }, 5_000);
+
+    // Run an immediate check
+    this.checkAndAnnounce();
+
+    console.log(`[Executor] Started (mode: ${this.aggressiveness})`);
+  }
+
+  stop(): void {
+    this.running = false;
+    if (this.checkTimer) {
+      clearInterval(this.checkTimer);
+      this.checkTimer = null;
+    }
+    if (this.tickTimer) {
+      clearInterval(this.tickTimer);
+      this.tickTimer = null;
+    }
+    console.log('[Executor] Stopped');
+  }
+
+  /**
+   * Check for commitments that are due or due within 2 minutes.
+   * Announce each one as a pending execution.
+   */
+  checkAndAnnounce(): void {
+    try {
+      const now = Date.now();
+      const dueNow = getDueCommitments(); // when_due <= now
+      const upcoming = getUpcoming(20); // all upcoming with when_due
+
+      // Filter upcoming to those due within 2 minutes
+      const dueSoon = upcoming.filter(
+        (c) => c.when_due && c.when_due > now && c.when_due <= now + 2 * 60_000
+      );
+
+      const candidates = [...dueNow, ...dueSoon];
+
+      for (const commitment of candidates) {
+        // Skip if already announced, executed, or terminal status
+        if (this.pending.has(commitment.id)) continue;
+        if (this.executedIds.has(commitment.id)) continue;
+        if (commitment.status === 'completed' || commitment.status === 'failed') continue;
+
+        this.announceExecution(commitment);
+      }
+    } catch (err) {
+      console.error('[Executor] Check error:', err);
+    }
+  }
+
+  /**
+   * Cancel a pending execution. Returns true if successfully cancelled.
+   */
+  cancelExecution(commitmentId: string): boolean {
+    const state = this.pending.get(commitmentId);
+    if (!state || state.executed || state.cancelled) return false;
+
+    state.cancelled = true;
+    console.log(`[Executor] Cancelled execution: ${state.what}`);
+
+    // Broadcast cancellation confirmation
+    this.broadcast?.({
+      type: 'notification',
+      payload: {
+        source: 'commitment_executor',
+        action: 'execution_cancelled',
+        commitmentId,
+        what: state.what,
+      },
+      timestamp: Date.now(),
+    });
+
+    // Clean up
+    this.pending.delete(commitmentId);
+    return true;
+  }
+
+  /**
+   * Get all pending executions (for UI display).
+   */
+  getPending(): ExecutionState[] {
+    return Array.from(this.pending.values()).filter((s) => !s.cancelled && !s.executed);
+  }
+
+  // --- Private ---
+
+  private announceExecution(commitment: Commitment): void {
+    const now = Date.now();
+    const cancelWindow = CANCEL_WINDOW[this.aggressiveness];
+
+    const state: ExecutionState = {
+      commitmentId: commitment.id,
+      what: commitment.what,
+      announcedAt: now,
+      cancelDeadline: cancelWindow === Infinity ? Infinity : now + cancelWindow,
+      cancelled: false,
+      executed: false,
+    };
+
+    this.pending.set(commitment.id, state);
+
+    if (this.aggressiveness === 'passive') {
+      console.log(`[Executor] Announced (passive, no auto-execute): ${commitment.what}`);
+    } else {
+      const windowSec = Math.round(cancelWindow / 1000);
+      console.log(`[Executor] Announced: "${commitment.what}" — executing in ${windowSec}s unless cancelled`);
+    }
+
+    // Broadcast announcement to all WebSocket clients
+    this.broadcast?.({
+      type: 'notification',
+      payload: {
+        source: 'commitment_executor',
+        action: 'pending_execution',
+        commitmentId: commitment.id,
+        what: commitment.what,
+        executeAt: state.cancelDeadline === Infinity ? null : state.cancelDeadline,
+        cancelWindowMs: cancelWindow === Infinity ? null : cancelWindow,
+      },
+      timestamp: now,
+    });
+
+    // Also broadcast as a chat message so the user sees it
+    this.broadcast?.({
+      type: 'chat',
+      payload: {
+        text: this.aggressiveness === 'passive'
+          ? `Task due: "${commitment.what}". Waiting for your instruction to proceed.`
+          : `Executing "${commitment.what}" in ${Math.round(cancelWindow / 1000)}s. Send cancel to abort.`,
+        source: 'proactive',
+      },
+      priority: 'urgent',
+      timestamp: now,
+    });
+  }
+
+  private async tickExecutions(): Promise<void> {
+    if (!this.agentService) return;
+
+    const now = Date.now();
+
+    for (const [id, state] of this.pending) {
+      if (state.cancelled || state.executed) {
+        this.pending.delete(id);
+        continue;
+      }
+
+      // Check if cancel window has expired
+      if (now < state.cancelDeadline) continue;
+
+      // Execute!
+      state.executed = true;
+      this.pending.delete(id);
+      this.executedIds.add(id);
+
+      // Cap executedIds memory
+      if (this.executedIds.size > 500) {
+        const arr = Array.from(this.executedIds);
+        this.executedIds = new Set(arr.slice(arr.length - 250));
+      }
+
+      try {
+        await this.executeCommitment(state);
+      } catch (err) {
+        console.error(`[Executor] Failed to execute "${state.what}":`, err);
+        try {
+          const reason = err instanceof Error ? err.message : 'Execution failed';
+          updateCommitmentStatus(state.commitmentId, 'failed', reason);
+        } catch { /* ignore */ }
+      }
+    }
+  }
+
+  private async executeCommitment(state: ExecutionState): Promise<void> {
+    console.log(`[Executor] Executing: "${state.what}"`);
+
+    // Mark as active
+    try {
+      updateCommitmentStatus(state.commitmentId, 'active');
+    } catch { /* ignore */ }
+
+    // Build a mandatory execution prompt
+    const prompt = [
+      '[COMMITMENT EXECUTION — MANDATORY]',
+      '',
+      `You previously committed to: "${state.what}"`,
+      'This commitment is now due. Execute it NOW using your tools.',
+      '',
+      'Instructions:',
+      '1. Use your available tools (browser, terminal, file operations) to complete this task.',
+      '2. Be thorough — actually perform the work, don\'t just describe it.',
+      '3. After completion, summarize what you did.',
+      '4. If the task is impossible or unclear, explain why and suggest alternatives.',
+      '',
+      'BEGIN EXECUTION.',
+    ].join('\n');
+
+    const response = await this.agentService!.handleMessage(prompt, 'system');
+
+    // Broadcast the execution result
+    this.broadcast?.({
+      type: 'chat',
+      payload: {
+        text: response ?? 'Task executed (no response).',
+        source: 'proactive',
+      },
+      priority: 'normal',
+      timestamp: Date.now(),
+    });
+
+    // Mark commitment as completed
+    const resultSummary = response
+      ? response.length > 500 ? response.slice(0, 497) + '...' : response
+      : 'Executed successfully';
+
+    try {
+      updateCommitmentStatus(state.commitmentId, 'completed', resultSummary);
+    } catch (err) {
+      console.error('[Executor] Failed to update commitment status:', err);
+    }
+
+    console.log(`[Executor] Completed: "${state.what}"`);
+  }
+}

package/src/daemon/event-classifier.ts

@@ -0,0 +1,239 @@
+/**
+ * Event Classifier — Priority Router
+ *
+ * Classifies ObserverEvents into priority levels using rule-based logic.
+ * No LLM calls — must be instant. Critical/high events trigger immediate
+ * reactions; normal/low events get batched for the next heartbeat.
+ */
+
+import type { ObserverEvent } from '../observers/index.ts';
+import { getDueCommitments, getUpcoming } from '../vault/commitments.ts';
+
+export type EventPriority = 'critical' | 'high' | 'normal' | 'low';
+
+export type ClassifiedEvent = {
+  event: ObserverEvent;
+  priority: EventPriority;
+  reason: string;
+};
+
+// Patterns that suggest high-intent clipboard content
+const URL_PATTERN = /https?:\/\/\S+/i;
+const EMAIL_PATTERN = /[\w.-]+@[\w.-]+\.\w{2,}/;
+const PHONE_PATTERN = /(\+?\d{1,3}[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}/;
+
+// Directories where file changes are low-priority noise
+const LOW_PRIORITY_DIRS = ['/tmp', '/var/tmp', '/dev/shm', 'node_modules', '.git', '__pycache__', '.cache'];
+
+/**
+ * Classify an observer event into a priority level.
+ * Rules are evaluated top-down; first match wins.
+ */
+export function classifyEvent(event: ObserverEvent): ClassifiedEvent {
+  const { type, data } = event;
+
+  // --- Commitment-related events (injected by heartbeat checks) ---
+  if (type === 'commitment_overdue') {
+    return { event, priority: 'critical', reason: `Commitment overdue: ${data.what}` };
+  }
+
+  if (type === 'commitment_due_soon') {
+    return { event, priority: 'high', reason: `Commitment due within 15 min: ${data.what}` };
+  }
+
+  // --- Clipboard events ---
+  if (type === 'clipboard') {
+    const text = String(data.content ?? '');
+
+    if (text.length < 3) {
+      return { event, priority: 'low', reason: 'Clipboard: trivial content' };
+    }
+
+    if (URL_PATTERN.test(text)) {
+      return { event, priority: 'high', reason: 'Clipboard contains URL — possible intent to browse/research' };
+    }
+
+    if (EMAIL_PATTERN.test(text)) {
+      return { event, priority: 'high', reason: 'Clipboard contains email address — possible intent to contact' };
+    }
+
+    if (PHONE_PATTERN.test(text)) {
+      return { event, priority: 'high', reason: 'Clipboard contains phone number' };
+    }
+
+    if (text.length > 200) {
+      return { event, priority: 'normal', reason: 'Clipboard: substantial text copied' };
+    }
+
+    return { event, priority: 'low', reason: 'Clipboard: short text' };
+  }
+
+  // --- File change events ---
+  if (type === 'file_change') {
+    const filePath = String(data.path ?? '');
+    const changeType = String(data.changeType ?? data.type ?? '');
+
+    // Check if file is in a low-priority directory
+    if (LOW_PRIORITY_DIRS.some(dir => filePath.includes(dir))) {
+      return { event, priority: 'low', reason: `File change in noisy directory: ${filePath}` };
+    }
+
+    // Large file deletions are noteworthy
+    if (changeType === 'delete' || changeType === 'rename') {
+      return { event, priority: 'high', reason: `File ${changeType}: ${filePath}` };
+    }
+
+    return { event, priority: 'normal', reason: `File modified: ${filePath}` };
+  }
+
+  // --- Process events ---
+  if (type === 'process_started') {
+    const name = String(data.name ?? data.command ?? '');
+
+    // Interesting process launches
+    if (/chrome|firefox|code|slack|discord|telegram|zoom/i.test(name)) {
+      return { event, priority: 'normal', reason: `Notable app launched: ${name}` };
+    }
+
+    return { event, priority: 'low', reason: `Process started: ${name}` };
+  }
+
+  if (type === 'process_stopped') {
+    return { event, priority: 'low', reason: `Process stopped: ${data.name ?? data.pid}` };
+  }
+
+  // --- Notification events ---
+  if (type === 'notification') {
+    const urgency = String(data.urgency ?? '');
+
+    if (urgency === 'critical') {
+      return { event, priority: 'critical', reason: `System notification (critical): ${data.summary}` };
+    }
+
+    return { event, priority: 'normal', reason: `System notification: ${data.summary}` };
+  }
+
+  // --- Calendar / Email events ---
+  if (type === 'calendar') {
+    return { event, priority: 'high', reason: `Calendar event: ${data.summary ?? data.title}` };
+  }
+
+  if (type === 'email') {
+    const subject = String(data.subject ?? '');
+    const labels = Array.isArray(data.labels) ? data.labels as string[] : [];
+
+    // IMPORTANT/STARRED labels → high priority
+    if (labels.includes('IMPORTANT') || labels.includes('STARRED')) {
+      return { event, priority: 'high', reason: `Important email: ${subject}` };
+    }
+
+    // Urgent keywords in subject
+    const urgentKeywords = /\b(urgent|asap|critical|emergency|action required|immediate|deadline)\b/i;
+    if (urgentKeywords.test(subject)) {
+      return { event, priority: 'high', reason: `Urgent email: ${subject}` };
+    }
+
+    return { event, priority: 'normal', reason: `New email: ${subject || 'no subject'}` };
+  }
+
+  // --- Awareness events (M13) ---
+  if (type === 'error_detected') {
+    return { event, priority: 'high', reason: `Screen error detected: ${data.errorText} in ${data.appName}` };
+  }
+
+  if (type === 'struggle_detected') {
+    const score = data.compositeScore as number;
+    const priority = score >= 0.7 ? 'high' : 'normal';
+    return { event, priority, reason: `User struggling in ${data.appName} (score: ${score?.toFixed(2)}, ${data.appCategory})` };
+  }
+
+  if (type === 'stuck_detected') {
+    return { event, priority: 'normal', reason: `User appears stuck in ${data.appName} (${Math.round((data.durationMs as number) / 1000)}s)` };
+  }
+
+  if (type === 'context_changed') {
+    return { event, priority: 'low', reason: `Switched from ${data.fromApp} to ${data.toApp}` };
+  }
+
+  if (type === 'session_started' || type === 'session_ended') {
+    return { event, priority: 'low', reason: `Activity session ${type === 'session_started' ? 'started' : 'ended'}` };
+  }
+
+  if (type === 'suggestion_ready') {
+    return { event, priority: 'normal', reason: `Awareness suggestion: ${data.title}` };
+  }
+
+  if (type === 'screen_capture') {
+    return { event, priority: 'low', reason: `Screen captured (${Math.round((data.pixelChangePct as number) * 100)}% change)` };
+  }
+
+  // --- Sidecar events ---
+  if (type === 'sidecar_register') {
+    return { event, priority: 'normal', reason: `Sidecar registered: ${data.name ?? data.sidecar_id}` };
+  }
+
+  if (type === 'sidecar_disconnect') {
+    return { event, priority: 'normal', reason: `Sidecar disconnected: ${data.name ?? data.sidecar_id}` };
+  }
+
+  if (type === 'sidecar_rpc_error') {
+    return { event, priority: 'high', reason: `Sidecar RPC error: ${data.error ?? data.method} on ${data.name ?? data.sidecar_id}` };
+  }
+
+  if (type === 'sidecar_rpc_complete') {
+    return { event, priority: 'low', reason: `Sidecar RPC complete: ${data.method} on ${data.name ?? data.sidecar_id}` };
+  }
+
+  if (type.startsWith('sidecar_')) {
+    return { event, priority: 'normal', reason: `Sidecar event: ${type}` };
+  }
+
+  // --- Default ---
+  return { event, priority: 'low', reason: `Unclassified event: ${type}` };
+}
+
+/**
+ * Check commitments and generate synthetic events for due/overdue items.
+ * Called periodically (e.g., every heartbeat) to inject commitment-awareness.
+ */
+export function checkCommitments(): ClassifiedEvent[] {
+  const events: ClassifiedEvent[] = [];
+
+  try {
+    // Check overdue commitments
+    const overdue = getDueCommitments();
+    for (const c of overdue) {
+      events.push({
+        event: {
+          type: 'commitment_overdue',
+          data: { id: c.id, what: c.what, when_due: c.when_due, priority: c.priority },
+          timestamp: Date.now(),
+        },
+        priority: 'critical',
+        reason: `Commitment overdue: ${c.what}`,
+      });
+    }
+
+    // Check commitments due within 15 minutes
+    const upcoming = getUpcoming(10);
+    const fifteenMinFromNow = Date.now() + 15 * 60 * 1000;
+
+    for (const c of upcoming) {
+      if (c.when_due && c.when_due <= fifteenMinFromNow && c.when_due > Date.now()) {
+        events.push({
+          event: {
+            type: 'commitment_due_soon',
+            data: { id: c.id, what: c.what, when_due: c.when_due, priority: c.priority },
+            timestamp: Date.now(),
+          },
+          priority: 'high',
+          reason: `Commitment due within 15 min: ${c.what}`,
+        });
+      }
+    }
+  } catch (err) {
+    console.error('[EventClassifier] Error checking commitments:', err);
+  }
+
+  return events;
+}

package/src/daemon/event-coalescer.ts

@@ -0,0 +1,123 @@
+/**
+ * Event Coalescer — Batch Buffer
+ *
+ * Collects normal/low priority events in memory and flushes them
+ * as a formatted summary string at heartbeat time. Groups events
+ * by type for clean LLM consumption.
+ */
+
+import type { ClassifiedEvent, EventPriority } from './event-classifier.ts';
+
+const MAX_BUFFER_SIZE = 100;
+
+export class EventCoalescer {
+  private buffer: ClassifiedEvent[] = [];
+
+  /**
+   * Add a classified event to the buffer.
+   * Oldest events are dropped if buffer exceeds max size.
+   */
+  addEvent(event: ClassifiedEvent): void {
+    this.buffer.push(event);
+
+    if (this.buffer.length > MAX_BUFFER_SIZE) {
+      // Drop oldest events
+      const overflow = this.buffer.length - MAX_BUFFER_SIZE;
+      this.buffer.splice(0, overflow);
+    }
+  }
+
+  /**
+   * Get the current buffer size.
+   */
+  get size(): number {
+    return this.buffer.length;
+  }
+
+  /**
+   * Flush the buffer and return a formatted summary string.
+   * Returns empty string if no events buffered.
+   */
+  flush(): string {
+    if (this.buffer.length === 0) {
+      return '';
+    }
+
+    const events = [...this.buffer];
+    this.buffer = [];
+
+    // Group by event type
+    const groups = new Map<string, ClassifiedEvent[]>();
+    for (const evt of events) {
+      const type = evt.event.type;
+      if (!groups.has(type)) {
+        groups.set(type, []);
+      }
+      groups.get(type)!.push(evt);
+    }
+
+    // Format each group
+    const lines: string[] = [];
+    lines.push(`## Recent Activity (${events.length} events since last check)`);
+    lines.push('');
+
+    for (const [type, groupEvents] of groups) {
+      const label = formatEventType(type);
+      lines.push(`**${label}** (${groupEvents.length}):`);
+
+      // Show up to 5 details per group, summarize the rest
+      const shown = groupEvents.slice(0, 5);
+      for (const evt of shown) {
+        lines.push(`  - ${evt.reason}`);
+      }
+
+      if (groupEvents.length > 5) {
+        lines.push(`  - ... and ${groupEvents.length - 5} more`);
+      }
+
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Peek at the buffer without clearing it.
+   */
+  peek(): ClassifiedEvent[] {
+    return [...this.buffer];
+  }
+
+  /**
+   * Clear the buffer without returning anything.
+   */
+  clear(): void {
+    this.buffer = [];
+  }
+}
+
+/**
+ * Human-readable label for event types.
+ */
+function formatEventType(type: string): string {
+  switch (type) {
+    case 'file_change': return 'File Changes';
+    case 'clipboard': return 'Clipboard Activity';
+    case 'process_started': return 'Apps Launched';
+    case 'process_stopped': return 'Apps Closed';
+    case 'notification': return 'System Notifications';
+    case 'calendar': return 'Calendar Events';
+    case 'email': return 'Emails';
+    case 'browser': return 'Browser Activity';
+    case 'commitment_overdue': return 'Overdue Commitments';
+    case 'commitment_due_soon': return 'Upcoming Commitments';
+    case 'screen_capture': return 'Screen Captures';
+    case 'context_changed': return 'Context Switches';
+    case 'error_detected': return 'Screen Errors';
+    case 'stuck_detected': return 'Stuck Detection';
+    case 'session_started': return 'Sessions Started';
+    case 'session_ended': return 'Sessions Ended';
+    case 'suggestion_ready': return 'Awareness Suggestions';
+    default: return type.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+  }
+}