@auxiora/ambient 1.0.0

package/src/scheduler.ts

@@ -0,0 +1,238 @@
+import type { Scheduler } from '@auxiora/behaviors';
+import type { ConnectorRegistry, TriggerManager } from '@auxiora/connectors';
+import type { BriefingGenerator } from './briefing.js';
+import type { NotificationOrchestrator } from './orchestrator.js';
+import type { QuietNotification } from './types.js';
+import { formatBriefingAsText } from './briefing.js';
+
+/** Configuration for the ambient scheduler. */
+export interface AmbientSchedulerConfig {
+  /** Cron expression for morning briefing. */
+  morningCron: string;
+  /** Cron expression for evening summary. */
+  eveningCron: string;
+  /** Cron expression for email polling. */
+  emailPollCron: string;
+  /** Cron expression for calendar polling. */
+  calendarPollCron: string;
+  /** Cron expression for notification polling. */
+  notificationPollCron: string;
+  /** Calendar alert window in minutes. */
+  calendarAlertMinutes: number;
+  /** Whether the scheduler is enabled. */
+  enabled: boolean;
+  /** Categories to include in briefings. */
+  categories: string[];
+}
+
+export const DEFAULT_AMBIENT_SCHEDULER_CONFIG: AmbientSchedulerConfig = {
+  morningCron: '0 7 * * *',
+  eveningCron: '0 18 * * *',
+  emailPollCron: '*/2 * * * *',
+  calendarPollCron: '*/5 * * * *',
+  notificationPollCron: '*/1 * * * *',
+  calendarAlertMinutes: 15,
+  enabled: true,
+  categories: ['calendar', 'email', 'tasks'],
+};
+
+/** Dependencies for the ambient scheduler. */
+export interface AmbientSchedulerDeps {
+  scheduler: Scheduler;
+  connectorRegistry: ConnectorRegistry;
+  triggerManager: TriggerManager;
+  briefingGenerator: BriefingGenerator;
+  emailIntelligence?: { triage?: { getTriageSummary(opts: { maxResults: number }): Promise<{ items: Array<{ subject: string; priority: string }> }> } };
+  calendarIntelligence?: { analyzeDay(date: string): Promise<{ events: Array<{ title: string; time: string }> }> };
+  notificationOrchestrator?: NotificationOrchestrator;
+  deliveryChannel: (message: string) => Promise<void>;
+  userId: string;
+  config?: Partial<AmbientSchedulerConfig>;
+}
+
+const JOB_IDS = {
+  emailPoll: 'ambient:email-poll',
+  calendarPoll: 'ambient:calendar-poll',
+  morningBriefing: 'ambient:morning-briefing',
+  eveningSummary: 'ambient:evening-summary',
+  notificationPoll: 'ambient:notification-poll',
+} as const;
+
+/**
+ * Schedules ambient polling and briefing generation using cron jobs.
+ */
+export class AmbientScheduler {
+  private readonly scheduler: Scheduler;
+  private readonly connectorRegistry: ConnectorRegistry;
+  private readonly triggerManager: TriggerManager;
+  private readonly briefingGenerator: BriefingGenerator;
+  private readonly emailIntelligence: AmbientSchedulerDeps['emailIntelligence'];
+  private readonly calendarIntelligence: AmbientSchedulerDeps['calendarIntelligence'];
+  private readonly notificationOrchestrator: NotificationOrchestrator | undefined;
+  private readonly deliveryChannel: (message: string) => Promise<void>;
+  private readonly userId: string;
+  private readonly config: AmbientSchedulerConfig;
+  private running = false;
+
+  constructor(deps: AmbientSchedulerDeps) {
+    this.scheduler = deps.scheduler;
+    this.connectorRegistry = deps.connectorRegistry;
+    this.triggerManager = deps.triggerManager;
+    this.briefingGenerator = deps.briefingGenerator;
+    this.emailIntelligence = deps.emailIntelligence;
+    this.calendarIntelligence = deps.calendarIntelligence;
+    this.notificationOrchestrator = deps.notificationOrchestrator;
+    this.deliveryChannel = deps.deliveryChannel;
+    this.userId = deps.userId;
+    this.config = { ...DEFAULT_AMBIENT_SCHEDULER_CONFIG, ...deps.config };
+  }
+
+  /** Start all scheduled cron jobs. */
+  start(): void {
+    if (!this.config.enabled || this.running) return;
+
+    this.scheduler.schedule(JOB_IDS.emailPoll, this.config.emailPollCron, () => {
+      void this.triggerManager.pollAll();
+    });
+
+    this.scheduler.schedule(JOB_IDS.calendarPoll, this.config.calendarPollCron, () => {
+      void this.pollCalendar();
+    });
+
+    this.scheduler.schedule(JOB_IDS.morningBriefing, this.config.morningCron, () => {
+      void this.generateAndDeliverBriefing('morning');
+    });
+
+    this.scheduler.schedule(JOB_IDS.eveningSummary, this.config.eveningCron, () => {
+      void this.generateAndDeliverBriefing('evening');
+    });
+
+    this.scheduler.schedule(JOB_IDS.notificationPoll, this.config.notificationPollCron, () => {
+      void this.pollAndNotify();
+    });
+
+    this.running = true;
+  }
+
+  /** Stop all scheduled cron jobs. */
+  stop(): void {
+    this.scheduler.stop(JOB_IDS.emailPoll);
+    this.scheduler.stop(JOB_IDS.calendarPoll);
+    this.scheduler.stop(JOB_IDS.morningBriefing);
+    this.scheduler.stop(JOB_IDS.eveningSummary);
+    this.scheduler.stop(JOB_IDS.notificationPoll);
+    this.running = false;
+  }
+
+  /** Whether the scheduler is currently running. */
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  /** Get the current configuration. */
+  getConfig(): AmbientSchedulerConfig {
+    return { ...this.config };
+  }
+
+  /** Generate and deliver a briefing for the specified time of day. */
+  async generateAndDeliverBriefing(time: 'morning' | 'evening'): Promise<void> {
+    const calendarEvents = await this.fetchCalendarEvents(time);
+    const emailNotifications = await this.fetchEmailSummary();
+
+    const briefing = this.briefingGenerator.generateBriefing(
+      this.userId,
+      time,
+      {
+        calendarEvents,
+        notifications: emailNotifications,
+      },
+    );
+
+    const formatted = formatBriefingAsText(briefing);
+    await this.deliveryChannel(formatted);
+  }
+
+  private async pollAndNotify(): Promise<void> {
+    if (!this.notificationOrchestrator) return;
+
+    const events = await this.triggerManager.pollAll();
+    if (events.length > 0) {
+      this.notificationOrchestrator.processTriggerEvents(events);
+    }
+
+    // Check for upcoming calendar events
+    if (this.calendarIntelligence) {
+      try {
+        const today = new Date().toISOString().split('T')[0]!;
+        const result = await this.calendarIntelligence.analyzeDay(today);
+        const now = Date.now();
+        const alertWindowMs = this.config.calendarAlertMinutes * 60_000;
+
+        const upcomingEvents = (result.events ?? [])
+          .map((e) => ({
+            title: e.title,
+            startTime: this.parseTimeToTimestamp(e.time),
+          }))
+          .filter((e) => {
+            const timeUntil = e.startTime - now;
+            return timeUntil > 0 && timeUntil <= alertWindowMs;
+          });
+
+        if (upcomingEvents.length > 0) {
+          this.notificationOrchestrator.processCalendarCheck(upcomingEvents, now);
+        }
+      } catch {
+        // Calendar fetch errors are silently ignored
+      }
+    }
+  }
+
+  private parseTimeToTimestamp(time: string): number {
+    const [hours, minutes] = time.split(':').map(Number);
+    const d = new Date();
+    d.setHours(hours ?? 0, minutes ?? 0, 0, 0);
+    return d.getTime();
+  }
+
+  private async pollCalendar(): Promise<void> {
+    if (!this.calendarIntelligence) return;
+
+    const today = new Date().toISOString().split('T')[0]!;
+    await this.calendarIntelligence.analyzeDay(today);
+  }
+
+  private async fetchCalendarEvents(
+    time: 'morning' | 'evening',
+  ): Promise<Array<{ title: string; time: string }>> {
+    if (!this.calendarIntelligence) return [];
+
+    const targetDate = time === 'evening'
+      ? new Date(Date.now() + 86_400_000).toISOString().split('T')[0]!
+      : new Date().toISOString().split('T')[0]!;
+
+    try {
+      const result = await this.calendarIntelligence.analyzeDay(targetDate);
+      return result.events ?? [];
+    } catch {
+      return [];
+    }
+  }
+
+  private async fetchEmailSummary(): Promise<QuietNotification[]> {
+    if (!this.emailIntelligence?.triage) return [];
+
+    try {
+      const result = await this.emailIntelligence.triage.getTriageSummary({ maxResults: 10 });
+      return (result.items ?? []).map((item, i) => ({
+        id: `email-${i}`,
+        priority: item.priority === 'urgent' ? 'alert' as const : 'nudge' as const,
+        message: item.subject,
+        createdAt: Date.now(),
+        dismissed: false,
+        source: 'email',
+      }));
+    } catch {
+      return [];
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,85 @@
+/** Types of patterns the ambient engine can detect. */
+export type AmbientPatternType = 'schedule' | 'preference' | 'trigger' | 'correlation';
+
+/** Notification priority levels for quiet notifications. */
+export type NotificationPriority = 'whisper' | 'nudge' | 'alert';
+
+/** A detected ambient pattern from user behavior. */
+export interface AmbientPattern {
+  id: string;
+  /** Pattern type. */
+  type: AmbientPatternType;
+  /** Human-readable description. */
+  description: string;
+  /** Confidence score (0-1). */
+  confidence: number;
+  /** Evidence supporting this pattern. */
+  evidence: string[];
+  /** When the pattern was first detected. */
+  detectedAt: number;
+  /** When the pattern was last confirmed. */
+  lastConfirmedAt: number;
+  /** Number of times this pattern has been observed. */
+  occurrences: number;
+}
+
+/** An anticipated user need based on detected patterns. */
+export interface Anticipation {
+  id: string;
+  /** What the user might need. */
+  description: string;
+  /** When this need is expected. */
+  expectedAt: number;
+  /** Confidence that this anticipation is correct (0-1). */
+  confidence: number;
+  /** Patterns that led to this anticipation. */
+  sourcePatterns: string[];
+  /** Suggested action to fulfill the need. */
+  suggestedAction?: string;
+}
+
+/** A quiet notification queued for the user. */
+export interface QuietNotification {
+  id: string;
+  /** Priority level. */
+  priority: NotificationPriority;
+  /** Notification message. */
+  message: string;
+  /** Detailed content (optional). */
+  detail?: string;
+  /** When the notification was created. */
+  createdAt: number;
+  /** Whether the notification has been dismissed. */
+  dismissed: boolean;
+  /** Source of the notification. */
+  source: string;
+}
+
+/** Configuration for personalized briefings. */
+export interface BriefingConfig {
+  /** Whether briefings are enabled. */
+  enabled: boolean;
+  /** Time of day for morning briefing (HH:MM). */
+  morningTime: string;
+  /** Time of day for evening summary (HH:MM). */
+  eveningTime: string;
+  /** Categories to include in briefings. */
+  categories: string[];
+  /** Maximum number of items per section. */
+  maxItemsPerSection: number;
+}
+
+export const DEFAULT_BRIEFING_CONFIG: BriefingConfig = {
+  enabled: true,
+  morningTime: '08:00',
+  eveningTime: '20:00',
+  categories: ['calendar', 'tasks', 'weather', 'news', 'patterns'],
+  maxItemsPerSection: 5,
+};
+
+/** An observed event for the pattern engine. */
+export interface ObservedEvent {
+  type: string;
+  timestamp: number;
+  data?: Record<string, unknown>;
+}

package/tests/ambient.test.ts

@@ -0,0 +1,363 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { AmbientPatternEngine } from '../src/pattern-engine.js';
+import { AnticipationEngine } from '../src/anticipation.js';
+import { BriefingGenerator } from '../src/briefing.js';
+import { QuietNotificationManager } from '../src/notification.js';
+import type { AmbientPattern } from '../src/types.js';
+
+describe('AmbientPatternEngine', () => {
+  let engine: AmbientPatternEngine;
+
+  beforeEach(() => {
+    engine = new AmbientPatternEngine();
+  });
+
+  it('should start with no events', () => {
+    expect(engine.getEventCount()).toBe(0);
+    expect(engine.getPatterns()).toHaveLength(0);
+  });
+
+  it('should observe events', () => {
+    engine.observe({ type: 'coffee', timestamp: Date.now() });
+    engine.observe({ type: 'coffee', timestamp: Date.now() });
+    expect(engine.getEventCount()).toBe(2);
+  });
+
+  it('should detect schedule patterns from repeated events at same hour', () => {
+    const now = Date.now();
+    const hour = new Date(now).getHours();
+
+    // Create events at same hour across multiple days
+    for (let i = 0; i < 5; i++) {
+      const d = new Date(now);
+      d.setDate(d.getDate() - i);
+      d.setHours(hour, 0, 0, 0);
+      engine.observe({ type: 'standup', timestamp: d.getTime() });
+    }
+
+    const patterns = engine.detectPatterns();
+    expect(patterns.length).toBeGreaterThan(0);
+    const schedule = patterns.find(p => p.type === 'schedule');
+    expect(schedule).toBeDefined();
+    expect(schedule!.description).toContain('standup');
+  });
+
+  it('should detect frequency patterns from regularly spaced events', () => {
+    const now = Date.now();
+    const interval = 2 * 60 * 60 * 1000; // 2 hours
+
+    for (let i = 0; i < 5; i++) {
+      engine.observe({ type: 'check-email', timestamp: now - i * interval });
+    }
+
+    const patterns = engine.detectPatterns();
+    const freq = patterns.find(p => p.type === 'preference');
+    expect(freq).toBeDefined();
+    expect(freq!.description).toContain('check-email');
+    expect(freq!.description).toContain('hours');
+  });
+
+  it('should detect correlations between event types', () => {
+    const now = Date.now();
+
+    // A always followed by B within 5 minutes
+    for (let i = 0; i < 3; i++) {
+      const base = now - i * 60 * 60 * 1000;
+      engine.observe({ type: 'open-slack', timestamp: base });
+      engine.observe({ type: 'check-calendar', timestamp: base + 2 * 60 * 1000 });
+    }
+
+    const patterns = engine.detectPatterns();
+    const correlation = patterns.find(p => p.type === 'correlation');
+    expect(correlation).toBeDefined();
+    expect(correlation!.description).toContain('follows');
+  });
+
+  it('should prune events outside window', () => {
+    // Use a tiny window (1 second)
+    const shortEngine = new AmbientPatternEngine(1000);
+    shortEngine.observe({ type: 'old', timestamp: Date.now() - 5000 });
+    shortEngine.observe({ type: 'new', timestamp: Date.now() });
+    // Prune happens on next observe
+    shortEngine.observe({ type: 'new2', timestamp: Date.now() });
+    expect(shortEngine.getEventCount()).toBe(2); // 'old' pruned
+  });
+
+  it('should reset state', () => {
+    engine.observe({ type: 'test', timestamp: Date.now() });
+    engine.reset();
+    expect(engine.getEventCount()).toBe(0);
+    expect(engine.getPatterns()).toHaveLength(0);
+  });
+});
+
+describe('AnticipationEngine', () => {
+  let anticipation: AnticipationEngine;
+
+  beforeEach(() => {
+    anticipation = new AnticipationEngine();
+  });
+
+  it('should generate anticipations from schedule patterns', () => {
+    const pattern: AmbientPattern = {
+      id: 'p1',
+      type: 'schedule',
+      description: '"standup" events frequently occur around 10:00',
+      confidence: 0.8,
+      evidence: [],
+      detectedAt: Date.now(),
+      lastConfirmedAt: Date.now(),
+      occurrences: 5,
+    };
+
+    const results = anticipation.generateAnticipations([pattern]);
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0].sourcePatterns).toContain('p1');
+    expect(results[0].expectedAt).toBeGreaterThan(Date.now());
+  });
+
+  it('should generate anticipations from preference patterns', () => {
+    const pattern: AmbientPattern = {
+      id: 'p2',
+      type: 'preference',
+      description: '"email" occurs roughly every 2.5 hours',
+      confidence: 0.7,
+      evidence: [],
+      detectedAt: Date.now(),
+      lastConfirmedAt: Date.now(),
+      occurrences: 4,
+    };
+
+    const results = anticipation.generateAnticipations([pattern]);
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0].expectedAt).toBeGreaterThan(Date.now());
+  });
+
+  it('should skip low-confidence patterns', () => {
+    const pattern: AmbientPattern = {
+      id: 'p3',
+      type: 'schedule',
+      description: '"rare" around 14:00',
+      confidence: 0.2,
+      evidence: [],
+      detectedAt: Date.now(),
+      lastConfirmedAt: Date.now(),
+      occurrences: 1,
+    };
+
+    const results = anticipation.generateAnticipations([pattern]);
+    expect(results).toHaveLength(0);
+  });
+
+  it('should prune expired anticipations', () => {
+    const pattern: AmbientPattern = {
+      id: 'p4',
+      type: 'correlation',
+      description: '"B" often follows "A" within 5 minutes',
+      confidence: 0.8,
+      evidence: [],
+      detectedAt: Date.now(),
+      lastConfirmedAt: Date.now(),
+      occurrences: 3,
+    };
+
+    // Generate with a past time so anticipations expire immediately
+    anticipation.generateAnticipations([pattern], { currentTime: Date.now() - 10 * 60 * 1000 });
+    const pruned = anticipation.prune();
+    expect(pruned).toBeGreaterThanOrEqual(1);
+  });
+
+  it('should reset', () => {
+    const pattern: AmbientPattern = {
+      id: 'p5',
+      type: 'trigger',
+      description: 'trigger detected',
+      confidence: 0.9,
+      evidence: [],
+      detectedAt: Date.now(),
+      lastConfirmedAt: Date.now(),
+      occurrences: 1,
+    };
+    anticipation.generateAnticipations([pattern]);
+    anticipation.reset();
+    expect(anticipation.getAnticipations()).toHaveLength(0);
+  });
+});
+
+describe('BriefingGenerator', () => {
+  let generator: BriefingGenerator;
+
+  beforeEach(() => {
+    generator = new BriefingGenerator();
+  });
+
+  it('should generate a morning briefing with sections', () => {
+    const briefing = generator.generateBriefing('user1', 'morning', {
+      notifications: [
+        { id: 'n1', priority: 'nudge', message: 'New email', createdAt: Date.now(), dismissed: false, source: 'email' },
+      ],
+      calendarEvents: [
+        { title: 'Team standup', time: '10:00' },
+        { title: 'Lunch', time: '12:00' },
+      ],
+      tasks: [
+        { title: 'Review PR', status: 'in-progress' },
+      ],
+    });
+
+    expect(briefing.userId).toBe('user1');
+    expect(briefing.timeOfDay).toBe('morning');
+    expect(briefing.sections.length).toBeGreaterThan(0);
+
+    const calendarSection = briefing.sections.find(s => s.title.includes('Schedule'));
+    expect(calendarSection).toBeDefined();
+    expect(calendarSection!.items).toHaveLength(2);
+  });
+
+  it('should include patterns section when patterns are available', () => {
+    const briefing = generator.generateBriefing('user1', 'evening', {
+      patterns: [
+        {
+          id: 'p1',
+          type: 'schedule',
+          description: 'Standup at 10:00',
+          confidence: 0.8,
+          evidence: [],
+          detectedAt: Date.now(),
+          lastConfirmedAt: Date.now(),
+          occurrences: 5,
+        },
+      ],
+    });
+
+    const patternsSection = briefing.sections.find(s => s.title === 'Observed Patterns');
+    expect(patternsSection).toBeDefined();
+  });
+
+  it('should filter dismissed notifications', () => {
+    const briefing = generator.generateBriefing('user1', 'morning', {
+      notifications: [
+        { id: 'n1', priority: 'nudge', message: 'Old', createdAt: Date.now(), dismissed: true, source: 'test' },
+      ],
+    });
+
+    const notifSection = briefing.sections.find(s => s.title === 'Notifications');
+    expect(notifSection).toBeUndefined();
+  });
+
+  it('should respect maxItemsPerSection', () => {
+    const generator2 = new BriefingGenerator({ maxItemsPerSection: 2 });
+    const briefing = generator2.generateBriefing('user1', 'morning', {
+      calendarEvents: [
+        { title: 'Event 1', time: '09:00' },
+        { title: 'Event 2', time: '10:00' },
+        { title: 'Event 3', time: '11:00' },
+      ],
+    });
+
+    const calSection = briefing.sections.find(s => s.title.includes('Schedule'));
+    expect(calSection!.items).toHaveLength(2);
+  });
+
+  it('should return config', () => {
+    const config = generator.getConfig();
+    expect(config.enabled).toBe(true);
+    expect(config.morningTime).toBe('08:00');
+  });
+});
+
+describe('QuietNotificationManager', () => {
+  let manager: QuietNotificationManager;
+
+  beforeEach(() => {
+    manager = new QuietNotificationManager();
+  });
+
+  it('should create notifications', () => {
+    const n = manager.notify('nudge', 'Test message');
+    expect(n.id).toBeDefined();
+    expect(n.priority).toBe('nudge');
+    expect(n.message).toBe('Test message');
+    expect(n.dismissed).toBe(false);
+  });
+
+  it('should queue notifications by priority', () => {
+    manager.notify('whisper', 'Low');
+    manager.notify('alert', 'High');
+    manager.notify('nudge', 'Medium');
+
+    const queue = manager.getQueue();
+    expect(queue[0].priority).toBe('alert');
+    expect(queue[1].priority).toBe('nudge');
+    expect(queue[2].priority).toBe('whisper');
+  });
+
+  it('should dismiss a notification', () => {
+    const n = manager.notify('nudge', 'Dismiss me');
+    expect(manager.dismiss(n.id)).toBe(true);
+    expect(manager.getQueue()).toHaveLength(0);
+  });
+
+  it('should return false for unknown dismiss', () => {
+    expect(manager.dismiss('nonexistent')).toBe(false);
+  });
+
+  it('should dismiss all', () => {
+    manager.notify('whisper', 'A');
+    manager.notify('nudge', 'B');
+    const count = manager.dismissAll();
+    expect(count).toBe(2);
+    expect(manager.getQueue()).toHaveLength(0);
+  });
+
+  it('should filter by priority', () => {
+    manager.notify('whisper', 'A');
+    manager.notify('alert', 'B');
+    manager.notify('whisper', 'C');
+
+    const whispers = manager.getByPriority('whisper');
+    expect(whispers).toHaveLength(2);
+  });
+
+  it('should get notification by ID', () => {
+    const n = manager.notify('alert', 'Important');
+    const fetched = manager.get(n.id);
+    expect(fetched).toBeDefined();
+    expect(fetched!.message).toBe('Important');
+  });
+
+  it('should count pending notifications', () => {
+    manager.notify('whisper', 'A');
+    manager.notify('nudge', 'B');
+    expect(manager.getPendingCount()).toBe(2);
+
+    const n = manager.notify('alert', 'C');
+    manager.dismiss(n.id);
+    expect(manager.getPendingCount()).toBe(2);
+  });
+
+  it('should prune old dismissed notifications', () => {
+    const n = manager.notify('whisper', 'Old');
+    manager.dismiss(n.id);
+    // Manually set createdAt to old
+    const notification = manager.get(n.id)!;
+    (notification as any).createdAt = Date.now() - 48 * 60 * 60 * 1000;
+
+    const pruned = manager.prune();
+    expect(pruned).toBe(1);
+    expect(manager.get(n.id)).toBeUndefined();
+  });
+
+  it('should clear all', () => {
+    manager.notify('alert', 'A');
+    manager.notify('nudge', 'B');
+    manager.clear();
+    expect(manager.getPendingCount()).toBe(0);
+  });
+
+  it('should include source and detail', () => {
+    const n = manager.notify('nudge', 'Msg', { source: 'calendar', detail: 'Extra info' });
+    expect(n.source).toBe('calendar');
+    expect(n.detail).toBe('Extra info');
+  });
+});