@operor/copilot 0.1.0

package/src/__tests__/copilot.test.ts

@@ -0,0 +1,1007 @@
+/**
+ * Unit tests for @operor/copilot
+ *
+ * Covers: InMemoryCopilotStore, UnansweredQueryTracker, QueryClusterer,
+ *         CopilotCommandHandler, DigestScheduler
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import crypto from 'node:crypto';
+import { InMemoryCopilotStore } from '../InMemoryCopilotStore.js';
+import { UnansweredQueryTracker } from '../UnansweredQueryTracker.js';
+import { QueryClusterer } from '../QueryClusterer.js';
+import { CopilotCommandHandler } from '../CopilotCommandHandler.js';
+import { DigestScheduler } from '../DigestScheduler.js';
+import type {
+  UnansweredQuery,
+  EmbeddingService,
+  CopilotStore,
+  MessageProcessedEvent,
+} from '../types.js';
+import type { KnowledgeBaseRuntime } from '@operor/core';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createMockEmbedder(dim = 4): EmbeddingService {
+  return {
+    dimensions: dim,
+    embed: async (text: string) => {
+      const hash = text.split('').reduce((acc, c) => acc + c.charCodeAt(0), 0);
+      return Array.from({ length: dim }, (_, i) => Math.sin(hash + i));
+    },
+  };
+}
+
+function createTestQuery(overrides?: Partial<UnansweredQuery>): UnansweredQuery {
+  return {
+    id: crypto.randomUUID(),
+    query: 'test query',
+    normalizedQuery: 'test query',
+    channel: 'whatsapp',
+    customerPhone: '+1234567890',
+    kbTopScore: 0.3,
+    kbIsFaqMatch: false,
+    kbResultCount: 1,
+    status: 'pending',
+    timesAsked: 1,
+    uniqueCustomers: ['+1234567890'],
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    ...overrides,
+  };
+}
+
+function createMockKb(): KnowledgeBaseRuntime {
+  return {
+    ingestFaq: vi.fn().mockResolvedValue({ id: 'test-id' }),
+    retrieve: vi.fn().mockResolvedValue({ results: [], context: '', isFaqMatch: false }),
+    listDocuments: vi.fn().mockResolvedValue([]),
+    deleteDocument: vi.fn().mockResolvedValue(undefined),
+    getStats: vi.fn().mockResolvedValue({
+      documentCount: 0,
+      chunkCount: 0,
+      embeddingDimensions: 4,
+      dbSizeBytes: 0,
+    }),
+  };
+}
+
+function createEvent(overrides?: Partial<MessageProcessedEvent>): MessageProcessedEvent {
+  return {
+    query: 'What is your return policy?',
+    channel: 'whatsapp',
+    customerPhone: '+1234567890',
+    response: {
+      text: 'I am not sure about that.',
+      metadata: {
+        kbTopScore: 0.3,
+        kbIsFaqMatch: false,
+        kbResultCount: 1,
+      },
+    },
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 1. InMemoryCopilotStore
+// ---------------------------------------------------------------------------
+
+describe('InMemoryCopilotStore', () => {
+  let store: InMemoryCopilotStore;
+
+  beforeEach(() => {
+    store = new InMemoryCopilotStore();
+  });
+
+  it('addQuery + getQuery stores and retrieves a query', async () => {
+    const q = createTestQuery({ id: 'q1', query: 'How to return?' });
+    await store.addQuery(q);
+
+    const result = await store.getQuery('q1');
+    expect(result).not.toBeNull();
+    expect(result!.id).toBe('q1');
+    expect(result!.query).toBe('How to return?');
+  });
+
+  it('getQuery returns null for unknown id', async () => {
+    const result = await store.getQuery('nonexistent');
+    expect(result).toBeNull();
+  });
+
+  it('getPendingQueries returns only pending, sorted by timesAsked DESC', async () => {
+    await store.addQuery(createTestQuery({ id: 'q1', status: 'pending', timesAsked: 2, query: 'A' }));
+    await store.addQuery(createTestQuery({ id: 'q2', status: 'taught', timesAsked: 5, query: 'B' }));
+    await store.addQuery(createTestQuery({ id: 'q3', status: 'pending', timesAsked: 10, query: 'C' }));
+    await store.addQuery(createTestQuery({ id: 'q4', status: 'dismissed', timesAsked: 3, query: 'D' }));
+    await store.addQuery(createTestQuery({ id: 'q5', status: 'pending', timesAsked: 1, query: 'E' }));
+
+    const pending = await store.getPendingQueries();
+    expect(pending).toHaveLength(3);
+    expect(pending[0].id).toBe('q3'); // timesAsked=10
+    expect(pending[1].id).toBe('q1'); // timesAsked=2
+    expect(pending[2].id).toBe('q5'); // timesAsked=1
+  });
+
+  it('getPendingQueries respects limit', async () => {
+    await store.addQuery(createTestQuery({ id: 'q1', status: 'pending', timesAsked: 5 }));
+    await store.addQuery(createTestQuery({ id: 'q2', status: 'pending', timesAsked: 3 }));
+    await store.addQuery(createTestQuery({ id: 'q3', status: 'pending', timesAsked: 1 }));
+
+    const pending = await store.getPendingQueries(2);
+    expect(pending).toHaveLength(2);
+    expect(pending[0].id).toBe('q1');
+    expect(pending[1].id).toBe('q2');
+  });
+
+  it('updateQuery updates fields and updatedAt', async () => {
+    const now = Date.now();
+    const q = createTestQuery({ id: 'q1', timesAsked: 1, updatedAt: now - 10_000 });
+    await store.addQuery(q);
+
+    await store.updateQuery('q1', { timesAsked: 5, status: 'taught' });
+
+    const updated = await store.getQuery('q1');
+    expect(updated!.timesAsked).toBe(5);
+    expect(updated!.status).toBe('taught');
+    expect(updated!.updatedAt).toBeGreaterThanOrEqual(now);
+  });
+
+  it('updateQuery does nothing for unknown id', async () => {
+    // Should not throw
+    await store.updateQuery('nonexistent', { timesAsked: 99 });
+  });
+
+  it('findSimilarQuery matches by normalizedQuery', async () => {
+    await store.addQuery(createTestQuery({ id: 'q1', normalizedQuery: 'return policy' }));
+    await store.addQuery(createTestQuery({ id: 'q2', normalizedQuery: 'shipping cost' }));
+
+    const match = await store.findSimilarQuery('return policy');
+    expect(match).not.toBeNull();
+    expect(match!.id).toBe('q1');
+
+    const noMatch = await store.findSimilarQuery('payment methods');
+    expect(noMatch).toBeNull();
+  });
+
+  it('addCluster + getCluster stores and retrieves a cluster', async () => {
+    await store.addCluster({
+      id: 'c1',
+      representativeQuery: 'return policy',
+      queryCount: 1,
+      uniqueCustomers: [],
+      status: 'pending',
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    });
+
+    const cluster = await store.getCluster('c1');
+    expect(cluster).not.toBeNull();
+    expect(cluster!.representativeQuery).toBe('return policy');
+  });
+
+  it('getCluster returns null for unknown id', async () => {
+    expect(await store.getCluster('nonexistent')).toBeNull();
+  });
+
+  it('getOpenClusters returns only pending clusters', async () => {
+    await store.addCluster({
+      id: 'c1', representativeQuery: 'A', queryCount: 1,
+      uniqueCustomers: [], status: 'pending', createdAt: Date.now(), updatedAt: Date.now(),
+    });
+    await store.addCluster({
+      id: 'c2', representativeQuery: 'B', queryCount: 2,
+      uniqueCustomers: [], status: 'taught', createdAt: Date.now(), updatedAt: Date.now(),
+    });
+    await store.addCluster({
+      id: 'c3', representativeQuery: 'C', queryCount: 3,
+      uniqueCustomers: [], status: 'pending', createdAt: Date.now(), updatedAt: Date.now(),
+    });
+
+    const open = await store.getOpenClusters();
+    expect(open).toHaveLength(2);
+    const ids = open.map(c => c.id).sort();
+    expect(ids).toEqual(['c1', 'c3']);
+  });
+
+  it('updateCluster updates fields and updatedAt', async () => {
+    const now = Date.now();
+    await store.addCluster({
+      id: 'c1', representativeQuery: 'A', queryCount: 1,
+      uniqueCustomers: [], status: 'pending', createdAt: now, updatedAt: now - 10_000,
+    });
+
+    await store.updateCluster('c1', { queryCount: 5, label: 'returns' });
+
+    const cluster = await store.getCluster('c1');
+    expect(cluster!.queryCount).toBe(5);
+    expect(cluster!.label).toBe('returns');
+    expect(cluster!.updatedAt).toBeGreaterThanOrEqual(now);
+  });
+
+  it('getQueriesByCluster returns queries with matching clusterId', async () => {
+    await store.addQuery(createTestQuery({ id: 'q1', clusterId: 'c1' }));
+    await store.addQuery(createTestQuery({ id: 'q2', clusterId: 'c2' }));
+    await store.addQuery(createTestQuery({ id: 'q3', clusterId: 'c1' }));
+
+    const result = await store.getQueriesByCluster('c1');
+    expect(result).toHaveLength(2);
+    const ids = result.map(q => q.id).sort();
+    expect(ids).toEqual(['q1', 'q3']);
+  });
+
+  it('getImpactMetrics counts correctly', async () => {
+    await store.addQuery(createTestQuery({
+      id: 'q1', status: 'pending', timesAsked: 3,
+      uniqueCustomers: ['+111', '+222'],
+    }));
+    await store.addQuery(createTestQuery({
+      id: 'q2', status: 'taught', timesAsked: 5,
+      uniqueCustomers: ['+222', '+333'],
+    }));
+    await store.addQuery(createTestQuery({
+      id: 'q3', status: 'dismissed', timesAsked: 2,
+      uniqueCustomers: ['+111'],
+    }));
+    await store.addQuery(createTestQuery({
+      id: 'q4', status: 'pending', timesAsked: 7,
+      uniqueCustomers: ['+444'],
+    }));
+
+    const metrics = await store.getImpactMetrics();
+    expect(metrics.pendingCount).toBe(2);
+    expect(metrics.taughtCount).toBe(1);
+    expect(metrics.dismissedCount).toBe(1);
+    expect(metrics.totalCustomersAffected).toBe(4); // +111, +222, +333, +444
+    expect(metrics.totalTimesAsked).toBe(17); // 3+5+2+7
+    expect(metrics.topPendingQueries).toHaveLength(2);
+    // Sorted by timesAsked DESC
+    expect(metrics.topPendingQueries[0].id).toBe('q4');
+    expect(metrics.topPendingQueries[1].id).toBe('q1');
+  });
+
+  it('getImpactMetrics respects topN limit', async () => {
+    for (let i = 0; i < 5; i++) {
+      await store.addQuery(createTestQuery({
+        id: `q${i}`, status: 'pending', timesAsked: i + 1,
+      }));
+    }
+
+    const metrics = await store.getImpactMetrics(2);
+    expect(metrics.topPendingQueries).toHaveLength(2);
+    expect(metrics.topPendingQueries[0].timesAsked).toBe(5);
+    expect(metrics.topPendingQueries[1].timesAsked).toBe(4);
+  });
+
+  it('getLastDigestTime / setLastDigestTime', async () => {
+    expect(await store.getLastDigestTime()).toBe(0);
+
+    const now = Date.now();
+    await store.setLastDigestTime(now);
+    expect(await store.getLastDigestTime()).toBe(now);
+
+    await store.setLastDigestTime(now + 1000);
+    expect(await store.getLastDigestTime()).toBe(now + 1000);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. UnansweredQueryTracker
+// ---------------------------------------------------------------------------
+
+describe('UnansweredQueryTracker', () => {
+  let store: InMemoryCopilotStore;
+  let embedder: EmbeddingService;
+  let tracker: UnansweredQueryTracker;
+
+  beforeEach(() => {
+    store = new InMemoryCopilotStore();
+    embedder = createMockEmbedder();
+  });
+
+  it('tracks queries below threshold', async () => {
+    tracker = new UnansweredQueryTracker(
+      store,
+      { enabled: true, trackingThreshold: 0.70 },
+      embedder,
+    );
+
+    await tracker.maybeTrack(createEvent({
+      query: 'What is your return policy?',
+      response: {
+        text: 'Not sure.',
+        metadata: { kbTopScore: 0.4, kbIsFaqMatch: false, kbResultCount: 1 },
+      },
+    }));
+
+    const pending = await store.getPendingQueries();
+    expect(pending).toHaveLength(1);
+    expect(pending[0].query).toBe('What is your return policy?');
+    expect(pending[0].status).toBe('pending');
+  });
+
+  it('skips queries above threshold', async () => {
+    tracker = new UnansweredQueryTracker(
+      store,
+      { enabled: true, trackingThreshold: 0.70 },
+      embedder,
+    );
+
+    await tracker.maybeTrack(createEvent({
+      response: {
+        text: 'Here is our return policy...',
+        metadata: { kbTopScore: 0.85, kbIsFaqMatch: false, kbResultCount: 2 },
+      },
+    }));
+
+    const pending = await store.getPendingQueries();
+    expect(pending).toHaveLength(0);
+  });
+
+  it('skips when kbIsFaqMatch is true and score is above threshold', async () => {
+    tracker = new UnansweredQueryTracker(
+      store,
+      { enabled: true, trackingThreshold: 0.70 },
+      embedder,
+    );
+
+    await tracker.maybeTrack(createEvent({
+      response: {
+        text: 'FAQ answer.',
+        metadata: { kbTopScore: 0.90, kbIsFaqMatch: true, kbResultCount: 1 },
+      },
+    }));
+
+    const pending = await store.getPendingQueries();
+    expect(pending).toHaveLength(0);
+  });
+
+  it('tracks when kbResultCount is 0 even if kbTopScore defaults to 0', async () => {
+    tracker = new UnansweredQueryTracker(
+      store,
+      { enabled: true, trackingThreshold: 0.70 },
+      embedder,
+    );
+
+    await tracker.maybeTrack(createEvent({
+      response: {
+        text: 'No results.',
+        metadata: { kbTopScore: 0, kbIsFaqMatch: false, kbResultCount: 0 },
+      },
+    }));
+
+    const pending = await store.getPendingQueries();
+    expect(pending).toHaveLength(1);
+  });
+
+  it('increments timesAsked for duplicate normalized queries', async () => {
+    tracker = new UnansweredQueryTracker(
+      store,
+      { enabled: true, trackingThreshold: 0.70 },
+      embedder,
+    );
+
+    const event = createEvent({ query: 'return policy' });
+
+    await tracker.maybeTrack(event);
+    await tracker.maybeTrack(event);
+    await tracker.maybeTrack(event);
+
+    const pending = await store.getPendingQueries();
+    expect(pending).toHaveLength(1);
+    expect(pending[0].timesAsked).toBe(3);
+  });
+
+  it('adds new customerPhone to uniqueCustomers on duplicate', async () => {
+    tracker = new UnansweredQueryTracker(
+      store,
+      { enabled: true, trackingThreshold: 0.70 },
+      embedder,
+    );
+
+    await tracker.maybeTrack(createEvent({
+      query: 'return policy',
+      customerPhone: '+111',
+    }));
+    await tracker.maybeTrack(createEvent({
+      query: 'return policy',
+      customerPhone: '+222',
+    }));
+    // Same phone again -- should not duplicate
+    await tracker.maybeTrack(createEvent({
+      query: 'return policy',
+      customerPhone: '+111',
+    }));
+
+    const pending = await store.getPendingQueries();
+    expect(pending).toHaveLength(1);
+    expect(pending[0].uniqueCustomers).toHaveLength(2);
+    expect(pending[0].uniqueCustomers).toContain('+111');
+    expect(pending[0].uniqueCustomers).toContain('+222');
+  });
+
+  it('does not track when disabled', async () => {
+    tracker = new UnansweredQueryTracker(
+      store,
+      { enabled: false, trackingThreshold: 0.70 },
+      embedder,
+    );
+
+    await tracker.maybeTrack(createEvent());
+
+    const pending = await store.getPendingQueries();
+    expect(pending).toHaveLength(0);
+  });
+
+  it('catches errors silently (non-blocking)', async () => {
+    const brokenStore: CopilotStore = {
+      ...store,
+      findSimilarQuery: () => { throw new Error('DB crash'); },
+      addQuery: () => { throw new Error('DB crash'); },
+    } as any;
+
+    tracker = new UnansweredQueryTracker(
+      brokenStore,
+      { enabled: true, trackingThreshold: 0.70 },
+      embedder,
+    );
+
+    // Should not throw
+    await expect(tracker.maybeTrack(createEvent())).resolves.toBeUndefined();
+  });
+
+  it('calls clusterer.assignCluster for new queries', async () => {
+    const mockClusterer = {
+      assignCluster: vi.fn().mockResolvedValue('cluster-1'),
+    } as any;
+
+    tracker = new UnansweredQueryTracker(
+      store,
+      { enabled: true, trackingThreshold: 0.70 },
+      embedder,
+      mockClusterer,
+    );
+
+    await tracker.maybeTrack(createEvent({ query: 'new question' }));
+
+    expect(mockClusterer.assignCluster).toHaveBeenCalledTimes(1);
+    const [queryId, normalizedText, embedding] = mockClusterer.assignCluster.mock.calls[0];
+    expect(typeof queryId).toBe('string');
+    expect(normalizedText).toBe('new question');
+    expect(embedding).toHaveLength(4); // mock embedder dim
+  });
+
+  it('does not call clusterer for duplicate queries', async () => {
+    const mockClusterer = {
+      assignCluster: vi.fn().mockResolvedValue('cluster-1'),
+    } as any;
+
+    tracker = new UnansweredQueryTracker(
+      store,
+      { enabled: true, trackingThreshold: 0.70 },
+      embedder,
+      mockClusterer,
+    );
+
+    await tracker.maybeTrack(createEvent({ query: 'same question' }));
+    await tracker.maybeTrack(createEvent({ query: 'same question' }));
+
+    // assignCluster only called once (for the new query, not the duplicate)
+    expect(mockClusterer.assignCluster).toHaveBeenCalledTimes(1);
+  });
+
+  it('normalizeQuery lowercases, trims, and collapses whitespace', () => {
+    tracker = new UnansweredQueryTracker(
+      store,
+      { enabled: true, trackingThreshold: 0.70 },
+      embedder,
+    );
+
+    expect(tracker.normalizeQuery('  HELLO   WORLD  ')).toBe('hello world');
+    expect(tracker.normalizeQuery('Return\t\nPolicy')).toBe('return policy');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. QueryClusterer
+// ---------------------------------------------------------------------------
+
+describe('QueryClusterer', () => {
+  let store: InMemoryCopilotStore;
+  let embedder: EmbeddingService;
+  let clusterer: QueryClusterer;
+
+  beforeEach(() => {
+    store = new InMemoryCopilotStore();
+    embedder = createMockEmbedder();
+  });
+
+  it('creates new cluster for first query', async () => {
+    clusterer = new QueryClusterer(store, embedder, { clusterThreshold: 0.87 });
+
+    const embedding = await embedder.embed('return policy');
+    const q = createTestQuery({ id: 'q1' });
+    await store.addQuery(q);
+
+    const clusterId = await clusterer.assignCluster('q1', 'return policy', embedding);
+
+    expect(typeof clusterId).toBe('string');
+    const cluster = await store.getCluster(clusterId);
+    expect(cluster).not.toBeNull();
+    expect(cluster!.representativeQuery).toBe('return policy');
+    expect(cluster!.queryCount).toBe(1);
+    expect(cluster!.status).toBe('pending');
+
+    // Query should be updated with clusterId
+    const updatedQ = await store.getQuery('q1');
+    expect(updatedQ!.clusterId).toBe(clusterId);
+  });
+
+  it('assigns query to existing cluster when similarity >= threshold', async () => {
+    // Use a very low threshold so identical embeddings always match
+    clusterer = new QueryClusterer(store, embedder, { clusterThreshold: 0.5 });
+
+    const embedding = await embedder.embed('return policy');
+    const q1 = createTestQuery({ id: 'q1' });
+    await store.addQuery(q1);
+    const clusterId1 = await clusterer.assignCluster('q1', 'return policy', embedding);
+
+    // Same text -> same embedding -> cosine similarity = 1.0 -> should match
+    const q2 = createTestQuery({ id: 'q2' });
+    await store.addQuery(q2);
+    const clusterId2 = await clusterer.assignCluster('q2', 'return policy', embedding);
+
+    expect(clusterId2).toBe(clusterId1);
+
+    const cluster = await store.getCluster(clusterId1);
+    expect(cluster!.queryCount).toBe(2);
+  });
+
+  it('creates new cluster when similarity < threshold', async () => {
+    clusterer = new QueryClusterer(store, embedder, { clusterThreshold: 0.99 });
+
+    const embedding1 = await embedder.embed('return policy');
+    const q1 = createTestQuery({ id: 'q1' });
+    await store.addQuery(q1);
+    const clusterId1 = await clusterer.assignCluster('q1', 'return policy', embedding1);
+
+    // Very different text -> different embedding -> low similarity
+    const embedding2 = await embedder.embed('how to bake a cake from scratch');
+    const q2 = createTestQuery({ id: 'q2' });
+    await store.addQuery(q2);
+    const clusterId2 = await clusterer.assignCluster('q2', 'how to bake a cake from scratch', embedding2);
+
+    expect(clusterId2).not.toBe(clusterId1);
+
+    const open = await store.getOpenClusters();
+    expect(open).toHaveLength(2);
+  });
+
+  it('updates centroid with running average', () => {
+    clusterer = new QueryClusterer(store, embedder);
+
+    const current = [1, 0, 0, 0];
+    const newVec = [0, 1, 0, 0];
+    // count=2 means this is the 2nd vector being added
+    const result = clusterer.updateCentroid(current, newVec, 2);
+
+    // (1*(2-1) + 0) / 2 = 0.5, (0*(2-1) + 1) / 2 = 0.5, 0, 0
+    expect(result[0]).toBeCloseTo(0.5);
+    expect(result[1]).toBeCloseTo(0.5);
+    expect(result[2]).toBeCloseTo(0);
+    expect(result[3]).toBeCloseTo(0);
+  });
+
+  it('cosineSimilarity returns correct values', () => {
+    clusterer = new QueryClusterer(store, embedder);
+
+    // Identical vectors -> similarity = 1
+    expect(clusterer.cosineSimilarity([1, 0, 0], [1, 0, 0])).toBeCloseTo(1);
+
+    // Orthogonal vectors -> similarity = 0
+    expect(clusterer.cosineSimilarity([1, 0, 0], [0, 1, 0])).toBeCloseTo(0);
+
+    // Opposite vectors -> similarity = -1
+    expect(clusterer.cosineSimilarity([1, 0, 0], [-1, 0, 0])).toBeCloseTo(-1);
+
+    // Parallel but different magnitude -> similarity = 1
+    expect(clusterer.cosineSimilarity([2, 0, 0], [5, 0, 0])).toBeCloseTo(1);
+
+    // 45-degree angle
+    expect(clusterer.cosineSimilarity([1, 0], [1, 1])).toBeCloseTo(Math.SQRT1_2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. CopilotCommandHandler
+// ---------------------------------------------------------------------------
+
+describe('CopilotCommandHandler', () => {
+  let store: InMemoryCopilotStore;
+  let mockKb: KnowledgeBaseRuntime;
+  let handler: CopilotCommandHandler;
+  let replies: string[];
+  let reply: (text: string) => Promise<void>;
+  const adminPhone = '+admin';
+
+  beforeEach(() => {
+    store = new InMemoryCopilotStore();
+    mockKb = createMockKb();
+    handler = new CopilotCommandHandler(store, undefined, mockKb);
+    replies = [];
+    reply = async (text: string) => { replies.push(text); };
+  });
+
+  describe('/review (no args) and /review next', () => {
+    it('/review (no args) shows next pending query', async () => {
+      await store.addQuery(createTestQuery({
+        id: 'q1', query: 'How to return?', timesAsked: 3,
+        uniqueCustomers: ['+111', '+222', '+333'],
+      }));
+
+      await handler.handleCommand('/review', '', adminPhone, reply);
+
+      expect(replies).toHaveLength(1);
+      expect(replies[0]).toContain('How to return?');
+      expect(replies[0]).toContain('Times asked');
+      expect(replies[0]).toContain('3');
+    });
+
+    it('/review next shows next pending query', async () => {
+      await store.addQuery(createTestQuery({
+        id: 'q1', query: 'Shipping cost?', timesAsked: 2,
+        uniqueCustomers: ['+111', '+222'],
+      }));
+
+      await handler.handleCommand('/review', 'next', adminPhone, reply);
+
+      expect(replies).toHaveLength(1);
+      expect(replies[0]).toContain('Shipping cost?');
+    });
+
+    it('empty queue shows "No pending queries" message', async () => {
+      await handler.handleCommand('/review', '', adminPhone, reply);
+
+      expect(replies).toHaveLength(1);
+      expect(replies[0]).toContain('No pending queries');
+    });
+  });
+
+  describe('/review accept', () => {
+    it('teaches FAQ and marks as taught with suggested answer', async () => {
+      const q = createTestQuery({
+        id: 'q1',
+        query: 'How to return?',
+        suggestedAnswer: 'You can return within 30 days.',
+      });
+      await store.addQuery(q);
+
+      // Load the query first
+      await handler.handleCommand('/review', 'next', adminPhone, reply);
+      replies = [];
+
+      // Accept with the suggested answer (no custom answer)
+      await handler.handleCommand('/review', 'accept', adminPhone, reply);
+
+      expect(replies).toHaveLength(1);
+      expect(replies[0]).toContain('Taught');
+      expect(replies[0]).toContain('How to return?');
+      expect(replies[0]).toContain('You can return within 30 days.');
+
+      expect(mockKb.ingestFaq).toHaveBeenCalledWith('How to return?', 'You can return within 30 days.');
+
+      const updated = await store.getQuery('q1');
+      expect(updated!.status).toBe('taught');
+      expect(updated!.taughtAnswer).toBe('You can return within 30 days.');
+    });
+
+    it('uses custom answer when provided', async () => {
+      const q = createTestQuery({
+        id: 'q1',
+        query: 'How to return?',
+        suggestedAnswer: 'Suggested answer.',
+      });
+      await store.addQuery(q);
+
+      await handler.handleCommand('/review', 'next', adminPhone, reply);
+      replies = [];
+
+      await handler.handleCommand('/review', 'accept My custom answer here', adminPhone, reply);
+
+      expect(replies).toHaveLength(1);
+      expect(replies[0]).toContain('My custom answer here');
+
+      expect(mockKb.ingestFaq).toHaveBeenCalledWith('How to return?', 'My custom answer here');
+    });
+
+    it('shows error when no answer provided and no suggestion', async () => {
+      const q = createTestQuery({ id: 'q1', query: 'How to return?' });
+      // No suggestedAnswer
+      await store.addQuery(q);
+
+      await handler.handleCommand('/review', 'next', adminPhone, reply);
+      replies = [];
+
+      await handler.handleCommand('/review', 'accept', adminPhone, reply);
+
+      expect(replies).toHaveLength(1);
+      expect(replies[0]).toContain('No answer provided');
+    });
+  });
+
+  describe('/review edit', () => {
+    it('teaches with provided answer', async () => {
+      const q = createTestQuery({ id: 'q1', query: 'What are your hours?' });
+      await store.addQuery(q);
+
+      await handler.handleCommand('/review', 'next', adminPhone, reply);
+      replies = [];
+
+      await handler.handleCommand('/review', 'edit We are open 9-5 Mon-Fri', adminPhone, reply);
+
+      expect(replies).toHaveLength(1);
+      expect(replies[0]).toContain('Taught');
+      expect(replies[0]).toContain('We are open 9-5 Mon-Fri');
+
+      expect(mockKb.ingestFaq).toHaveBeenCalledWith('What are your hours?', 'We are open 9-5 Mon-Fri');
+
+      const updated = await store.getQuery('q1');
+      expect(updated!.status).toBe('taught');
+    });
+
+    it('shows error without answer', async () => {
+      const q = createTestQuery({ id: 'q1', query: 'What are your hours?' });
+      await store.addQuery(q);
+
+      await handler.handleCommand('/review', 'next', adminPhone, reply);
+      replies = [];
+
+      await handler.handleCommand('/review', 'edit', adminPhone, reply);
+
+      expect(replies).toHaveLength(1);
+      expect(replies[0]).toContain('provide an answer');
+    });
+  });
+
+  describe('/review skip', () => {
+    it('marks as dismissed', async () => {
+      const q = createTestQuery({ id: 'q1', query: 'Irrelevant question' });
+      await store.addQuery(q);
+
+      await handler.handleCommand('/review', 'next', adminPhone, reply);
+      replies = [];
+
+      await handler.handleCommand('/review', 'skip', adminPhone, reply);
+
+      expect(replies).toHaveLength(1);
+      expect(replies[0]).toContain('Skipped');
+      expect(replies[0]).toContain('Irrelevant question');
+
+      const updated = await store.getQuery('q1');
+      expect(updated!.status).toBe('dismissed');
+    });
+  });
+
+  describe('/review stats', () => {
+    it('shows impact metrics', async () => {
+      await store.addQuery(createTestQuery({
+        id: 'q1', status: 'pending', timesAsked: 5,
+        query: 'return policy', uniqueCustomers: ['+111', '+222'],
+      }));
+      await store.addQuery(createTestQuery({
+        id: 'q2', status: 'taught', timesAsked: 3,
+        query: 'shipping', uniqueCustomers: ['+333'],
+      }));
+
+      await handler.handleCommand('/review', 'stats', adminPhone, reply);
+
+      expect(replies).toHaveLength(1);
+      const text = replies[0];
+      expect(text).toContain('Pending');
+      expect(text).toContain('1');
+      expect(text).toContain('Taught');
+      expect(text).toContain('Customers affected');
+      expect(text).toContain('Total times asked');
+    });
+  });
+
+  describe('/review help', () => {
+    it('shows help text', async () => {
+      await handler.handleCommand('/review', 'help', adminPhone, reply);
+
+      expect(replies).toHaveLength(1);
+      const text = replies[0];
+      expect(text).toContain('Review Commands');
+      expect(text).toContain('/review accept');
+      expect(text).toContain('/review edit');
+      expect(text).toContain('/review skip');
+      expect(text).toContain('/review stats');
+      expect(text).toContain('/review help');
+    });
+  });
+
+  describe('no current query', () => {
+    it('shows "No query selected" for accept', async () => {
+      await handler.handleCommand('/review', 'accept some answer', adminPhone, reply);
+
+      expect(replies).toHaveLength(1);
+      expect(replies[0]).toContain('No query selected');
+    });
+
+    it('shows "No query selected" for edit', async () => {
+      await handler.handleCommand('/review', 'edit some answer', adminPhone, reply);
+
+      expect(replies).toHaveLength(1);
+      expect(replies[0]).toContain('No query selected');
+    });
+
+    it('shows "No query selected" for skip', async () => {
+      await handler.handleCommand('/review', 'skip', adminPhone, reply);
+
+      expect(replies).toHaveLength(1);
+      expect(replies[0]).toContain('No query selected');
+    });
+  });
+
+  it('handles unknown subcommand', async () => {
+    await handler.handleCommand('/review', 'foobar', adminPhone, reply);
+
+    expect(replies).toHaveLength(1);
+    expect(replies[0]).toContain('Unknown subcommand');
+    expect(replies[0]).toContain('foobar');
+  });
+
+  it('maintains separate sessions per admin', async () => {
+    const q1 = createTestQuery({ id: 'q1', query: 'Q1', timesAsked: 10 });
+    const q2 = createTestQuery({ id: 'q2', query: 'Q2', timesAsked: 5 });
+    await store.addQuery(q1);
+    await store.addQuery(q2);
+
+    const replies1: string[] = [];
+    const replies2: string[] = [];
+    const reply1 = async (t: string) => { replies1.push(t); };
+    const reply2 = async (t: string) => { replies2.push(t); };
+
+    // Admin1 loads next query (q1 has highest timesAsked)
+    await handler.handleCommand('/review', 'next', '+admin1', reply1);
+    expect(replies1[0]).toContain('Q1');
+
+    // Admin2 also loads the top query independently
+    await handler.handleCommand('/review', 'next', '+admin2', reply2);
+    expect(replies2[0]).toContain('Q1');
+
+    // Admin1 accepts -- should not affect admin2's session
+    await handler.handleCommand('/review', 'accept The answer is X', '+admin1', reply1);
+    expect(replies1[1]).toContain('Taught');
+
+    // Admin2 can still skip their own loaded query
+    await handler.handleCommand('/review', 'skip', '+admin2', reply2);
+    expect(replies2[1]).toContain('Skipped');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5. DigestScheduler
+// ---------------------------------------------------------------------------
+
+describe('DigestScheduler', () => {
+  let store: InMemoryCopilotStore;
+
+  beforeEach(() => {
+    store = new InMemoryCopilotStore();
+  });
+
+  it('buildDigest returns null when no pending queries', async () => {
+    const scheduler = new DigestScheduler(
+      store,
+      { digestIntervalMs: 86_400_000, digestMaxItems: 10 },
+      vi.fn(),
+    );
+
+    const digest = await scheduler.buildDigest();
+    expect(digest).toBeNull();
+  });
+
+  it('buildDigest returns null when all queries are taught/dismissed', async () => {
+    await store.addQuery(createTestQuery({ id: 'q1', status: 'taught' }));
+    await store.addQuery(createTestQuery({ id: 'q2', status: 'dismissed' }));
+
+    const scheduler = new DigestScheduler(
+      store,
+      { digestIntervalMs: 86_400_000, digestMaxItems: 10 },
+      vi.fn(),
+    );
+
+    const digest = await scheduler.buildDigest();
+    expect(digest).toBeNull();
+  });
+
+  it('buildDigest formats digest text correctly', async () => {
+    await store.addQuery(createTestQuery({
+      id: 'q1', status: 'pending', timesAsked: 5,
+      query: 'Return policy?', uniqueCustomers: ['+111', '+222'],
+    }));
+    await store.addQuery(createTestQuery({
+      id: 'q2', status: 'pending', timesAsked: 3,
+      query: 'Shipping cost?', uniqueCustomers: ['+333'],
+    }));
+
+    const scheduler = new DigestScheduler(
+      store,
+      { digestIntervalMs: 86_400_000, digestMaxItems: 10 },
+      vi.fn(),
+    );
+
+    const digest = await scheduler.buildDigest();
+    expect(digest).not.toBeNull();
+    expect(digest).toContain('Training Copilot Digest');
+    expect(digest).toContain('2'); // pendingCount
+    expect(digest).toContain('3'); // totalCustomersAffected
+    expect(digest).toContain('/review');
+  });
+
+  it('buildDigest includes top queries', async () => {
+    await store.addQuery(createTestQuery({
+      id: 'q1', status: 'pending', timesAsked: 10,
+      query: 'Most asked question?', uniqueCustomers: ['+111'],
+    }));
+    await store.addQuery(createTestQuery({
+      id: 'q2', status: 'pending', timesAsked: 3,
+      query: 'Less asked question?', uniqueCustomers: ['+222'],
+    }));
+
+    const scheduler = new DigestScheduler(
+      store,
+      { digestIntervalMs: 86_400_000, digestMaxItems: 10 },
+      vi.fn(),
+    );
+
+    const digest = await scheduler.buildDigest();
+    expect(digest).toContain('Most asked question?');
+    expect(digest).toContain('Less asked question?');
+    expect(digest).toContain('10'); // timesAsked for top query
+  });
+
+  it('buildDigest respects digestMaxItems', async () => {
+    for (let i = 0; i < 5; i++) {
+      await store.addQuery(createTestQuery({
+        id: `q${i}`,
+        status: 'pending',
+        timesAsked: (5 - i),
+        query: `Question ${i}?`,
+        uniqueCustomers: [`+${i}`],
+      }));
+    }
+
+    const scheduler = new DigestScheduler(
+      store,
+      { digestIntervalMs: 86_400_000, digestMaxItems: 2 },
+      vi.fn(),
+    );
+
+    const digest = await scheduler.buildDigest();
+    expect(digest).not.toBeNull();
+    // Should include the top 2 (Question 0 with 5 asks, Question 1 with 4 asks)
+    expect(digest).toContain('Question 0?');
+    expect(digest).toContain('Question 1?');
+    // Should NOT include Question 4 (lowest timesAsked)
+    expect(digest).not.toContain('Question 4?');
+  });
+
+  it('start/stop manages the interval timer', () => {
+    const sendMessage = vi.fn();
+    const scheduler = new DigestScheduler(
+      store,
+      { digestIntervalMs: 86_400_000, digestMaxItems: 10 },
+      sendMessage,
+    );
+
+    // start creates a timer, stop clears it -- no assertions needed beyond
+    // verifying it does not throw
+    scheduler.start(['+admin1']);
+    scheduler.stop();
+    // Double stop should be safe
+    scheduler.stop();
+  });
+});