@operor/copilot 0.1.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/types.ts","../src/SQLiteCopilotStore.ts","../src/InMemoryCopilotStore.ts","../src/UnansweredQueryTracker.ts","../src/QueryClusterer.ts","../src/SuggestionEngine.ts","../src/CopilotCommandHandler.ts","../src/DigestScheduler.ts"],"sourcesContent":["/**\n * Training Copilot types\n */\n\n/** Status of an unanswered query through the review lifecycle */\nexport type QueryStatus = 'pending' | 'taught' | 'dismissed';\n\n/** A customer query that the KB couldn't confidently answer */\nexport interface UnansweredQuery {\n  id: string;\n  query: string;\n  normalizedQuery: string;\n  channel: string;\n  customerPhone: string;\n  kbTopScore: number;\n  kbIsFaqMatch: boolean;\n  kbTopChunkContent?: string;\n  kbResultCount: number;\n  status: QueryStatus;\n  clusterId?: string;\n  timesAsked: number;\n  uniqueCustomers: string[];\n  embedding?: number[];\n  suggestedAnswer?: string;\n  taughtAnswer?: string;\n  createdAt: number;\n  updatedAt: number;\n}\n\n/** A cluster of semantically similar unanswered queries */\nexport interface QueryCluster {\n  id: string;\n  label?: string;\n  representativeQuery: string;\n  centroid?: number[];\n  queryCount: number;\n  uniqueCustomers: string[];\n  status: QueryStatus;\n  createdAt: number;\n  updatedAt: number;\n}\n\n/** Aggregate metrics for the copilot dashboard / digest */\nexport interface ImpactMetrics {\n  pendingCount: number;\n  taughtCount: number;\n  dismissedCount: number;\n  totalCustomersAffected: number;\n  totalTimesAsked: number;\n  topPendingQueries: UnansweredQuery[];\n}\n\n/** Configuration for the copilot subsystem */\nexport interface CopilotConfig {\n  enabled: boolean;\n  trackingThreshold: number;\n  clusterThreshold: number;\n  digestIntervalMs: number;\n  digestMaxItems: number;\n  autoSuggest: boolean;\n}\n\n/** Default copilot configuration values */\nexport const DEFAULT_COPILOT_CONFIG: CopilotConfig = {\n  enabled: false,\n  trackingThreshold: 0.70,\n  clusterThreshold: 0.87,\n  digestIntervalMs: 86_400_000, // 24h\n  digestMaxItems: 10,\n  autoSuggest: true,\n};\n\n/** Embedding service interface — decouples copilot from specific embedding providers */\nexport interface EmbeddingService {\n  embed(text: string): Promise<number[]>;\n  dimensions: number;\n}\n\n/** AI provider interface for suggestion generation */\nexport interface AIProviderLike {\n  generateText(options: {\n    model?: string;\n    system?: string;\n    prompt: string;\n    maxTokens?: number;\n    temperature?: number;\n  }): Promise<{ text: string }>;\n}\n\n/** Store interface for copilot persistence */\nexport interface CopilotStore {\n  initialize(): Promise<void>;\n  close(): Promise<void>;\n\n  // Queries\n  addQuery(query: UnansweredQuery): Promise<void>;\n  getQuery(id: string): Promise<UnansweredQuery | null>;\n  updateQuery(id: string, updates: Partial<UnansweredQuery>): Promise<void>;\n  getPendingQueries(limit?: number): Promise<UnansweredQuery[]>;\n  findSimilarQuery(normalizedQuery: string): Promise<UnansweredQuery | null>;\n  getQueriesByCluster(clusterId: string): Promise<UnansweredQuery[]>;\n\n  // Clusters\n  addCluster(cluster: QueryCluster): Promise<void>;\n  getCluster(id: string): Promise<QueryCluster | null>;\n  updateCluster(id: string, updates: Partial<QueryCluster>): Promise<void>;\n  getOpenClusters(): Promise<QueryCluster[]>;\n\n  // Metrics\n  getImpactMetrics(topN?: number): Promise<ImpactMetrics>;\n\n  // Digest tracking\n  getLastDigestTime(): Promise<number>;\n  setLastDigestTime(time: number): Promise<void>;\n}\n\n/** Event emitted after a message is processed by the agent pipeline */\nexport interface MessageProcessedEvent {\n  query: string;\n  channel: string;\n  customerPhone: string;\n  response: {\n    text: string;\n    metadata?: {\n      kbTopScore?: number;\n      kbIsFaqMatch?: boolean;\n      kbTopChunkContent?: string;\n      kbResultCount?: number;\n    };\n  };\n}\n","import Database from 'better-sqlite3';\nimport * as sqliteVec from 'sqlite-vec';\nimport type { CopilotStore, UnansweredQuery, QueryCluster, ImpactMetrics } from './types.js';\n\n/**\n * SQLite-backed copilot store with sqlite-vec for vector search on cluster centroids.\n */\nexport class SQLiteCopilotStore implements CopilotStore {\n  private db: Database.Database;\n\n  constructor(\n    private dbPath: string,\n    private dimensions: number,\n  ) {\n    this.db = new Database(dbPath);\n    this.db.pragma('journal_mode = WAL');\n    this.db.pragma('foreign_keys = ON');\n    sqliteVec.load(this.db);\n  }\n\n  async initialize(): Promise<void> {\n    this.db.exec(`\n      CREATE TABLE IF NOT EXISTS copilot_queries (\n        id TEXT PRIMARY KEY,\n        query TEXT NOT NULL,\n        normalized_query TEXT NOT NULL,\n        channel TEXT NOT NULL,\n        customer_phone TEXT NOT NULL,\n        kb_top_score REAL NOT NULL DEFAULT 0,\n        kb_is_faq_match INTEGER NOT NULL DEFAULT 0,\n        kb_top_chunk_content TEXT,\n        kb_result_count INTEGER NOT NULL DEFAULT 0,\n        status TEXT NOT NULL DEFAULT 'pending',\n        cluster_id TEXT,\n        times_asked INTEGER NOT NULL DEFAULT 1,\n        unique_customers TEXT NOT NULL DEFAULT '[]',\n        embedding BLOB,\n        suggested_answer TEXT,\n        taught_answer TEXT,\n        created_at INTEGER NOT NULL,\n        updated_at INTEGER NOT NULL\n      );\n\n      CREATE INDEX IF NOT EXISTS idx_copilot_queries_status ON copilot_queries(status);\n      CREATE INDEX IF NOT EXISTS idx_copilot_queries_normalized ON copilot_queries(normalized_query);\n      CREATE INDEX IF NOT EXISTS idx_copilot_queries_cluster ON copilot_queries(cluster_id);\n\n      CREATE TABLE IF NOT EXISTS copilot_clusters (\n        id TEXT PRIMARY KEY,\n        label TEXT,\n        representative_query TEXT NOT NULL,\n        centroid BLOB,\n        query_count INTEGER NOT NULL DEFAULT 1,\n        unique_customers TEXT NOT NULL DEFAULT '[]',\n        status TEXT NOT NULL DEFAULT 'pending',\n        created_at INTEGER NOT NULL,\n        updated_at INTEGER NOT NULL\n      );\n\n      CREATE INDEX IF NOT EXISTS idx_copilot_clusters_status ON copilot_clusters(status);\n\n      CREATE TABLE IF NOT EXISTS copilot_meta (\n        key TEXT PRIMARY KEY,\n        value TEXT NOT NULL\n      );\n    `);\n\n    // Virtual table for vector search on cluster centroids\n    this.db.exec(`\n      CREATE VIRTUAL TABLE IF NOT EXISTS vec_copilot_clusters USING vec0(\n        cluster_id TEXT PRIMARY KEY,\n        centroid float[${this.dimensions}]\n      );\n    `);\n  }\n\n  async close(): Promise<void> {\n    this.db.close();\n  }\n\n  // --- Queries ---\n\n  async addQuery(query: UnansweredQuery): Promise<void> {\n    this.db.prepare(`\n      INSERT OR REPLACE INTO copilot_queries\n        (id, query, normalized_query, channel, customer_phone, kb_top_score, kb_is_faq_match,\n         kb_top_chunk_content, kb_result_count, status, cluster_id, times_asked,\n         unique_customers, embedding, suggested_answer, taught_answer, created_at, updated_at)\n      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)\n    `).run(\n      query.id,\n      query.query,\n      query.normalizedQuery,\n      query.channel,\n      query.customerPhone,\n      query.kbTopScore,\n      query.kbIsFaqMatch ? 1 : 0,\n      query.kbTopChunkContent ?? null,\n      query.kbResultCount,\n      query.status,\n      query.clusterId ?? null,\n      query.timesAsked,\n      JSON.stringify(query.uniqueCustomers),\n      query.embedding ? Buffer.from(new Float32Array(query.embedding).buffer) : null,\n      query.suggestedAnswer ?? null,\n      query.taughtAnswer ?? null,\n      query.createdAt,\n      query.updatedAt,\n    );\n  }\n\n  async getQuery(id: string): Promise<UnansweredQuery | null> {\n    const row = this.db.prepare('SELECT * FROM copilot_queries WHERE id = ?').get(id) as any;\n    return row ? this.rowToQuery(row) : null;\n  }\n\n  async updateQuery(id: string, updates: Partial<UnansweredQuery>): Promise<void> {\n    const existing = await this.getQuery(id);\n    if (!existing) return;\n\n    const merged = { ...existing, ...updates, updatedAt: Date.now() };\n    await this.addQuery(merged);\n  }\n\n  async getPendingQueries(limit?: number): Promise<UnansweredQuery[]> {\n    const sql = limit\n      ? 'SELECT * FROM copilot_queries WHERE status = ? ORDER BY times_asked DESC LIMIT ?'\n      : 'SELECT * FROM copilot_queries WHERE status = ? ORDER BY times_asked DESC';\n    const rows = limit\n      ? (this.db.prepare(sql).all('pending', limit) as any[])\n      : (this.db.prepare(sql).all('pending') as any[]);\n    return rows.map(r => this.rowToQuery(r));\n  }\n\n  async findSimilarQuery(normalizedQuery: string): Promise<UnansweredQuery | null> {\n    const row = this.db.prepare(\n      'SELECT * FROM copilot_queries WHERE normalized_query = ? AND status = ? LIMIT 1'\n    ).get(normalizedQuery, 'pending') as any;\n    return row ? this.rowToQuery(row) : null;\n  }\n\n  async getQueriesByCluster(clusterId: string): Promise<UnansweredQuery[]> {\n    const rows = this.db.prepare(\n      'SELECT * FROM copilot_queries WHERE cluster_id = ? ORDER BY times_asked DESC'\n    ).all(clusterId) as any[];\n    return rows.map(r => this.rowToQuery(r));\n  }\n\n  // --- Clusters ---\n\n  async addCluster(cluster: QueryCluster): Promise<void> {\n    this.db.prepare(`\n      INSERT OR REPLACE INTO copilot_clusters\n        (id, label, representative_query, centroid, query_count, unique_customers, status, created_at, updated_at)\n      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)\n    `).run(\n      cluster.id,\n      cluster.label ?? null,\n      cluster.representativeQuery,\n      cluster.centroid ? Buffer.from(new Float32Array(cluster.centroid).buffer) : null,\n      cluster.queryCount,\n      JSON.stringify(cluster.uniqueCustomers),\n      cluster.status,\n      cluster.createdAt,\n      cluster.updatedAt,\n    );\n\n    // Upsert into vector table for similarity search\n    if (cluster.centroid) {\n      this.db.prepare('DELETE FROM vec_copilot_clusters WHERE cluster_id = ?').run(cluster.id);\n      this.db.prepare(\n        'INSERT INTO vec_copilot_clusters (cluster_id, centroid) VALUES (?, ?)'\n      ).run(cluster.id, new Float32Array(cluster.centroid));\n    }\n  }\n\n  async getCluster(id: string): Promise<QueryCluster | null> {\n    const row = this.db.prepare('SELECT * FROM copilot_clusters WHERE id = ?').get(id) as any;\n    return row ? this.rowToCluster(row) : null;\n  }\n\n  async updateCluster(id: string, updates: Partial<QueryCluster>): Promise<void> {\n    const existing = await this.getCluster(id);\n    if (!existing) return;\n\n    const merged = { ...existing, ...updates, updatedAt: Date.now() };\n    await this.addCluster(merged);\n  }\n\n  async getOpenClusters(): Promise<QueryCluster[]> {\n    const rows = this.db.prepare(\n      'SELECT * FROM copilot_clusters WHERE status = ? ORDER BY query_count DESC'\n    ).all('pending') as any[];\n    return rows.map(r => this.rowToCluster(r));\n  }\n\n  /** Vector search cluster centroids — returns closest clusters by cosine distance */\n  async searchClusters(embedding: number[], limit: number): Promise<Array<{ clusterId: string; distance: number }>> {\n    const rows = this.db.prepare(`\n      SELECT cluster_id, distance\n      FROM vec_copilot_clusters\n      WHERE centroid MATCH ?\n      ORDER BY distance\n      LIMIT ?\n    `).all(new Float32Array(embedding), limit) as any[];\n\n    return rows.map(r => ({\n      clusterId: r.cluster_id as string,\n      distance: r.distance as number,\n    }));\n  }\n\n  // --- Metrics ---\n\n  async getImpactMetrics(topN = 10): Promise<ImpactMetrics> {\n    const counts = this.db.prepare(`\n      SELECT\n        SUM(CASE WHEN status = 'pending' THEN 1 ELSE 0 END) as pending_count,\n        SUM(CASE WHEN status = 'taught' THEN 1 ELSE 0 END) as taught_count,\n        SUM(CASE WHEN status = 'dismissed' THEN 1 ELSE 0 END) as dismissed_count,\n        SUM(times_asked) as total_times_asked\n      FROM copilot_queries\n    `).get() as any;\n\n    // Aggregate unique customers across all queries\n    const allCustomerRows = this.db.prepare(\n      'SELECT unique_customers FROM copilot_queries'\n    ).all() as any[];\n    const allCustomers = new Set<string>();\n    for (const row of allCustomerRows) {\n      const customers: string[] = JSON.parse(row.unique_customers);\n      customers.forEach(c => allCustomers.add(c));\n    }\n\n    const topPending = await this.getPendingQueries(topN);\n\n    return {\n      pendingCount: counts.pending_count ?? 0,\n      taughtCount: counts.taught_count ?? 0,\n      dismissedCount: counts.dismissed_count ?? 0,\n      totalCustomersAffected: allCustomers.size,\n      totalTimesAsked: counts.total_times_asked ?? 0,\n      topPendingQueries: topPending,\n    };\n  }\n\n  // --- Digest tracking ---\n\n  async getLastDigestTime(): Promise<number> {\n    const row = this.db.prepare(\n      \"SELECT value FROM copilot_meta WHERE key = 'last_digest_time'\"\n    ).get() as any;\n    return row ? parseInt(row.value, 10) : 0;\n  }\n\n  async setLastDigestTime(time: number): Promise<void> {\n    this.db.prepare(\n      \"INSERT OR REPLACE INTO copilot_meta (key, value) VALUES ('last_digest_time', ?)\"\n    ).run(String(time));\n  }\n\n  // --- Row mappers ---\n\n  private rowToQuery(row: any): UnansweredQuery {\n    return {\n      id: row.id,\n      query: row.query,\n      normalizedQuery: row.normalized_query,\n      channel: row.channel,\n      customerPhone: row.customer_phone,\n      kbTopScore: row.kb_top_score,\n      kbIsFaqMatch: !!row.kb_is_faq_match,\n      kbTopChunkContent: row.kb_top_chunk_content ?? undefined,\n      kbResultCount: row.kb_result_count,\n      status: row.status,\n      clusterId: row.cluster_id ?? undefined,\n      timesAsked: row.times_asked,\n      uniqueCustomers: JSON.parse(row.unique_customers),\n      embedding: row.embedding ? Array.from(new Float32Array(row.embedding.buffer ?? row.embedding)) : undefined,\n      suggestedAnswer: row.suggested_answer ?? undefined,\n      taughtAnswer: row.taught_answer ?? undefined,\n      createdAt: row.created_at,\n      updatedAt: row.updated_at,\n    };\n  }\n\n  private rowToCluster(row: any): QueryCluster {\n    return {\n      id: row.id,\n      label: row.label ?? undefined,\n      representativeQuery: row.representative_query,\n      centroid: row.centroid ? Array.from(new Float32Array(row.centroid.buffer ?? row.centroid)) : undefined,\n      queryCount: row.query_count,\n      uniqueCustomers: JSON.parse(row.unique_customers),\n      status: row.status,\n      createdAt: row.created_at,\n      updatedAt: row.updated_at,\n    };\n  }\n}\n","import type { CopilotStore, UnansweredQuery, QueryCluster, ImpactMetrics } from './types.js';\n\n/**\n * In-memory copilot store for testing and development.\n */\nexport class InMemoryCopilotStore implements CopilotStore {\n  private queries = new Map<string, UnansweredQuery>();\n  private clusters = new Map<string, QueryCluster>();\n  private lastDigestTime = 0;\n\n  async initialize(): Promise<void> {}\n  async close(): Promise<void> {}\n\n  async addQuery(query: UnansweredQuery): Promise<void> {\n    this.queries.set(query.id, { ...query });\n  }\n\n  async getQuery(id: string): Promise<UnansweredQuery | null> {\n    return this.queries.get(id) ?? null;\n  }\n\n  async updateQuery(id: string, updates: Partial<UnansweredQuery>): Promise<void> {\n    const q = this.queries.get(id);\n    if (q) this.queries.set(id, { ...q, ...updates, updatedAt: Date.now() });\n  }\n\n  async getPendingQueries(limit?: number): Promise<UnansweredQuery[]> {\n    const pending = [...this.queries.values()]\n      .filter(q => q.status === 'pending')\n      .sort((a, b) => b.timesAsked - a.timesAsked);\n    return limit ? pending.slice(0, limit) : pending;\n  }\n\n  async findSimilarQuery(normalizedQuery: string): Promise<UnansweredQuery | null> {\n    for (const q of this.queries.values()) {\n      if (q.normalizedQuery === normalizedQuery) return q;\n    }\n    return null;\n  }\n\n  async getQueriesByCluster(clusterId: string): Promise<UnansweredQuery[]> {\n    return [...this.queries.values()].filter(q => q.clusterId === clusterId);\n  }\n\n  async addCluster(cluster: QueryCluster): Promise<void> {\n    this.clusters.set(cluster.id, { ...cluster });\n  }\n\n  async getCluster(id: string): Promise<QueryCluster | null> {\n    return this.clusters.get(id) ?? null;\n  }\n\n  async updateCluster(id: string, updates: Partial<QueryCluster>): Promise<void> {\n    const c = this.clusters.get(id);\n    if (c) this.clusters.set(id, { ...c, ...updates, updatedAt: Date.now() });\n  }\n\n  async getOpenClusters(): Promise<QueryCluster[]> {\n    return [...this.clusters.values()].filter(c => c.status === 'pending');\n  }\n\n  async getImpactMetrics(topN = 10): Promise<ImpactMetrics> {\n    const all = [...this.queries.values()];\n    const pending = all.filter(q => q.status === 'pending');\n    const allCustomers = new Set<string>();\n    let totalAsked = 0;\n    for (const q of all) {\n      q.uniqueCustomers.forEach(c => allCustomers.add(c));\n      totalAsked += q.timesAsked;\n    }\n    return {\n      pendingCount: pending.length,\n      taughtCount: all.filter(q => q.status === 'taught').length,\n      dismissedCount: all.filter(q => q.status === 'dismissed').length,\n      totalCustomersAffected: allCustomers.size,\n      totalTimesAsked: totalAsked,\n      topPendingQueries: pending\n        .sort((a, b) => b.timesAsked - a.timesAsked)\n        .slice(0, topN),\n    };\n  }\n\n  async getLastDigestTime(): Promise<number> {\n    return this.lastDigestTime;\n  }\n\n  async setLastDigestTime(time: number): Promise<void> {\n    this.lastDigestTime = time;\n  }\n}\n","import crypto from 'node:crypto';\nimport type { CopilotStore, EmbeddingService, MessageProcessedEvent, UnansweredQuery } from './types.js';\nimport type { QueryClusterer } from './QueryClusterer.js';\n\n/**\n * Tracks unanswered queries by listening to message:processed events.\n * Runs non-blocking — errors are caught and logged, never thrown.\n */\nexport class UnansweredQueryTracker {\n  constructor(\n    private store: CopilotStore,\n    private config: { enabled: boolean; trackingThreshold: number },\n    private embedder: EmbeddingService,\n    private clusterer?: QueryClusterer,\n  ) {}\n\n  /**\n   * Called after each message is processed. Decides whether to track the query.\n   * Non-blocking: catches all errors internally.\n   */\n  async maybeTrack(event: MessageProcessedEvent): Promise<void> {\n    try {\n      if (!this.config.enabled) return;\n\n      const kbTopScore = event.response.metadata?.kbTopScore ?? 0;\n      const kbResultCount = event.response.metadata?.kbResultCount ?? 0;\n\n      // If KB answered confidently, skip tracking\n      if (kbResultCount > 0 && kbTopScore >= this.config.trackingThreshold) return;\n\n      const normalizedQuery = this.normalizeQuery(event.query);\n\n      const existing = await this.store.findSimilarQuery(normalizedQuery);\n\n      if (existing) {\n        const uniqueCustomers = existing.uniqueCustomers.includes(event.customerPhone)\n          ? existing.uniqueCustomers\n          : [...existing.uniqueCustomers, event.customerPhone];\n\n        await this.store.updateQuery(existing.id, {\n          timesAsked: existing.timesAsked + 1,\n          uniqueCustomers,\n          updatedAt: Date.now(),\n        });\n      } else {\n        const embedding = await this.embedder.embed(normalizedQuery);\n        const now = Date.now();\n        const id = crypto.randomUUID();\n\n        const newQuery: UnansweredQuery = {\n          id,\n          query: event.query,\n          normalizedQuery,\n          channel: event.channel,\n          customerPhone: event.customerPhone,\n          kbTopScore,\n          kbIsFaqMatch: event.response.metadata?.kbIsFaqMatch ?? false,\n          kbTopChunkContent: event.response.metadata?.kbTopChunkContent,\n          kbResultCount,\n          status: 'pending',\n          timesAsked: 1,\n          uniqueCustomers: [event.customerPhone],\n          embedding,\n          createdAt: now,\n          updatedAt: now,\n        };\n\n        await this.store.addQuery(newQuery);\n\n        if (this.clusterer) {\n          await this.clusterer.assignCluster(id, normalizedQuery, embedding);\n        }\n      }\n    } catch (_err) {\n      // Silently swallow — tracking must never disrupt the pipeline\n    }\n  }\n\n  /** Normalize query text for deduplication */\n  normalizeQuery(text: string): string {\n    return text.toLowerCase().trim().replace(/\\s+/g, ' ');\n  }\n}\n","import crypto from 'node:crypto';\nimport type { CopilotStore, EmbeddingService, QueryCluster } from './types.js';\n\n/**\n * Groups semantically similar unanswered queries into clusters.\n */\nexport class QueryClusterer {\n  constructor(\n    private store: CopilotStore,\n    private embedder: EmbeddingService,\n    private config: { clusterThreshold: number } = { clusterThreshold: 0.87 },\n  ) {}\n\n  /**\n   * Assign a query to an existing cluster or create a new one.\n   * Returns the cluster ID.\n   */\n  async assignCluster(queryId: string, queryText: string, embedding: number[]): Promise<string> {\n    const clusters = await this.store.getOpenClusters();\n\n    let bestCluster: QueryCluster | null = null;\n    let bestScore = -1;\n\n    for (const cluster of clusters) {\n      if (!cluster.centroid) continue;\n      const score = this.cosineSimilarity(embedding, cluster.centroid);\n      if (score > bestScore) {\n        bestScore = score;\n        bestCluster = cluster;\n      }\n    }\n\n    if (bestCluster && bestScore >= this.config.clusterThreshold) {\n      const newCount = bestCluster.queryCount + 1;\n      const newCentroid = this.updateCentroid(bestCluster.centroid!, embedding, newCount);\n\n      await this.store.updateCluster(bestCluster.id, {\n        centroid: newCentroid,\n        queryCount: newCount,\n        updatedAt: Date.now(),\n      });\n\n      await this.store.updateQuery(queryId, { clusterId: bestCluster.id });\n\n      return bestCluster.id;\n    }\n\n    // Create a new cluster\n    const clusterId = crypto.randomUUID();\n    const now = Date.now();\n\n    const newCluster: QueryCluster = {\n      id: clusterId,\n      representativeQuery: queryText,\n      centroid: embedding,\n      queryCount: 1,\n      uniqueCustomers: [],\n      status: 'pending',\n      createdAt: now,\n      updatedAt: now,\n    };\n\n    await this.store.addCluster(newCluster);\n    await this.store.updateQuery(queryId, { clusterId });\n\n    return clusterId;\n  }\n\n  /** Cosine similarity between two vectors */\n  cosineSimilarity(a: number[], b: number[]): number {\n    let dot = 0, magA = 0, magB = 0;\n    for (let i = 0; i < a.length; i++) {\n      dot += a[i] * b[i];\n      magA += a[i] * a[i];\n      magB += b[i] * b[i];\n    }\n    return dot / (Math.sqrt(magA) * Math.sqrt(magB));\n  }\n\n  /** Compute running average centroid */\n  updateCentroid(current: number[], newVec: number[], count: number): number[] {\n    return current.map((v, i) => (v * (count - 1) + newVec[i]) / count);\n  }\n}\n","import type { AIProviderLike } from './types.js';\nimport type { KnowledgeBaseRuntime } from '@operor/core';\n\nconst SYSTEM_PROMPT = `You are a helpful assistant that drafts FAQ answers for a knowledge base. Write concise, accurate answers based on the available context. If the context doesn't contain enough information, say so.`;\n\n/**\n * Generates suggested answers for unanswered queries using the LLM + KB context.\n */\nexport class SuggestionEngine {\n  constructor(\n    private aiProvider: AIProviderLike,\n    private kb: KnowledgeBaseRuntime,\n  ) {}\n\n  /**\n   * Generate a suggested answer for a query, optionally including related queries from a cluster.\n   */\n  async suggest(query: string, relatedQueries?: string[]): Promise<string> {\n    const kbResult = await this.kb.retrieve(query);\n\n    let prompt = `Customer query: \"${query}\"\\n`;\n\n    if (relatedQueries && relatedQueries.length > 0) {\n      prompt += `\\nRelated queries from other customers:\\n`;\n      for (const rq of relatedQueries) {\n        prompt += `- \"${rq}\"\\n`;\n      }\n    }\n\n    if (kbResult.context) {\n      prompt += `\\nKnowledge base context:\\n${kbResult.context}\\n`;\n    }\n\n    prompt += `\\nPlease draft a concise, helpful FAQ answer for this query.`;\n\n    const result = await this.aiProvider.generateText({\n      system: SYSTEM_PROMPT,\n      prompt,\n      temperature: 0.3,\n    });\n\n    return result.text;\n  }\n}\n","import type { CopilotStore, UnansweredQuery } from './types.js';\nimport type { KnowledgeBaseRuntime } from '@operor/core';\nimport type { SuggestionEngine } from './SuggestionEngine.js';\nimport type { QueryClusterer } from './QueryClusterer.js';\n\ninterface AdminSession {\n  currentQuery: UnansweredQuery | null;\n}\n\n/**\n * Handles /review commands from admin users in training mode.\n */\nexport class CopilotCommandHandler {\n  /** Per-admin session state: tracks which query they're currently reviewing */\n  private sessions = new Map<string, AdminSession>();\n\n  constructor(\n    private store: CopilotStore,\n    private suggestionEngine: SuggestionEngine | undefined,\n    private kb: KnowledgeBaseRuntime,\n    private clusterer?: QueryClusterer,\n  ) {}\n\n  /**\n   * Handle a /review subcommand.\n   * @param command The full command (always '/review')\n   * @param args Subcommand + arguments (e.g. 'accept This is the answer')\n   * @param adminPhone The admin's phone number\n   * @param reply Function to send a reply back to the admin\n   */\n  async handleCommand(\n    command: string,\n    args: string,\n    adminPhone: string,\n    reply: (text: string) => Promise<void>,\n  ): Promise<void> {\n    const trimmed = args.trim();\n    const spaceIndex = trimmed.indexOf(' ');\n    const subcommand = spaceIndex === -1 ? trimmed.toLowerCase() : trimmed.slice(0, spaceIndex).toLowerCase();\n    const subArgs = spaceIndex === -1 ? '' : trimmed.slice(spaceIndex + 1).trim();\n\n    switch (subcommand) {\n      case '':\n      case 'next':\n        return this.handleNext(adminPhone, reply);\n      case 'accept':\n        return this.handleAccept(adminPhone, subArgs, reply);\n      case 'edit':\n        return this.handleEdit(adminPhone, subArgs, reply);\n      case 'skip':\n        return this.handleSkip(adminPhone, reply);\n      case 'stats':\n        return this.handleStats(reply);\n      case 'cluster':\n        return this.handleCluster(adminPhone, reply);\n      case 'help':\n        return this.handleHelp(reply);\n      default:\n        await reply(`Unknown subcommand: *${subcommand}*\\n\\nType */review help* to see available commands.`);\n    }\n  }\n\n  private getSession(adminPhone: string): AdminSession {\n    let session = this.sessions.get(adminPhone);\n    if (!session) {\n      session = { currentQuery: null };\n      this.sessions.set(adminPhone, session);\n    }\n    return session;\n  }\n\n  private async handleNext(adminPhone: string, reply: (text: string) => Promise<void>): Promise<void> {\n    const session = this.getSession(adminPhone);\n    const pending = await this.store.getPendingQueries(1);\n\n    if (pending.length === 0) {\n      session.currentQuery = null;\n      await reply('No pending queries to review. Great job! 🎉');\n      return;\n    }\n\n    const query = pending[0];\n    session.currentQuery = query;\n\n    let text = `*📋 Query for Review*\\n\\n`;\n    text += `*Question:* ${query.query}\\n`;\n    text += `*Times asked:* ${query.timesAsked}\\n`;\n    text += `*Unique customers:* ${query.uniqueCustomers.length}\\n`;\n\n    if (query.suggestedAnswer) {\n      text += `\\n*💡 Suggested answer:*\\n${query.suggestedAnswer}\\n`;\n    } else if (this.suggestionEngine) {\n      try {\n        const suggested = await this.suggestionEngine.suggest(query.query);\n        if (suggested) {\n          query.suggestedAnswer = suggested;\n          await this.store.updateQuery(query.id, { suggestedAnswer: suggested });\n          text += `\\n*💡 Suggested answer:*\\n${suggested}\\n`;\n        }\n      } catch {\n        // Suggestion failed — continue without it\n      }\n    }\n\n    text += `\\n*Actions:*`;\n    text += `\\n/review accept [answer] — Teach this answer`;\n    text += `\\n/review edit <answer> — Provide your own answer`;\n    text += `\\n/review skip — Skip this query`;\n\n    await reply(text);\n  }\n\n  private async handleAccept(\n    adminPhone: string,\n    answerText: string,\n    reply: (text: string) => Promise<void>,\n  ): Promise<void> {\n    const session = this.getSession(adminPhone);\n    const query = session.currentQuery;\n\n    if (!query) {\n      await reply('No query selected. Use */review next* to load one.');\n      return;\n    }\n\n    const answer = answerText || query.suggestedAnswer;\n    if (!answer) {\n      await reply('No answer provided and no suggestion available. Use */review edit <answer>* to provide one.');\n      return;\n    }\n\n    await this.kb.ingestFaq(query.query, answer);\n    await this.store.updateQuery(query.id, {\n      status: 'taught',\n      taughtAnswer: answer,\n      updatedAt: Date.now(),\n    });\n\n    session.currentQuery = null;\n\n    await reply(`*✅ Taught!*\\n\\n*Q:* ${query.query}\\n*A:* ${answer}`);\n  }\n\n  private async handleEdit(\n    adminPhone: string,\n    answerText: string,\n    reply: (text: string) => Promise<void>,\n  ): Promise<void> {\n    const session = this.getSession(adminPhone);\n    const query = session.currentQuery;\n\n    if (!query) {\n      await reply('No query selected. Use */review next* to load one.');\n      return;\n    }\n\n    if (!answerText) {\n      await reply('Please provide an answer: */review edit <your answer>*');\n      return;\n    }\n\n    await this.kb.ingestFaq(query.query, answerText);\n    await this.store.updateQuery(query.id, {\n      status: 'taught',\n      taughtAnswer: answerText,\n      updatedAt: Date.now(),\n    });\n\n    session.currentQuery = null;\n\n    await reply(`*✅ Taught!*\\n\\n*Q:* ${query.query}\\n*A:* ${answerText}`);\n  }\n\n  private async handleSkip(adminPhone: string, reply: (text: string) => Promise<void>): Promise<void> {\n    const session = this.getSession(adminPhone);\n    const query = session.currentQuery;\n\n    if (!query) {\n      await reply('No query selected. Use */review next* to load one.');\n      return;\n    }\n\n    await this.store.updateQuery(query.id, {\n      status: 'dismissed',\n      updatedAt: Date.now(),\n    });\n\n    session.currentQuery = null;\n\n    await reply(`*⏭️ Skipped:* ${query.query}`);\n  }\n\n  private async handleStats(reply: (text: string) => Promise<void>): Promise<void> {\n    const metrics = await this.store.getImpactMetrics();\n\n    let text = `*📊 Copilot Stats*\\n\\n`;\n    text += `*Pending:* ${metrics.pendingCount}\\n`;\n    text += `*Taught:* ${metrics.taughtCount}\\n`;\n    text += `*Dismissed:* ${metrics.dismissedCount}\\n`;\n    text += `*Customers affected:* ${metrics.totalCustomersAffected}\\n`;\n    text += `*Total times asked:* ${metrics.totalTimesAsked}`;\n\n    if (metrics.topPendingQueries.length > 0) {\n      text += `\\n\\n*Top pending queries:*`;\n      for (const q of metrics.topPendingQueries) {\n        text += `\\n• ${q.query} (×${q.timesAsked})`;\n      }\n    }\n\n    await reply(text);\n  }\n\n  private async handleCluster(adminPhone: string, reply: (text: string) => Promise<void>): Promise<void> {\n    const session = this.getSession(adminPhone);\n    const query = session.currentQuery;\n\n    if (!query) {\n      await reply('No query selected. Use */review next* to load one.');\n      return;\n    }\n\n    if (!query.clusterId) {\n      await reply('This query is not part of any cluster.');\n      return;\n    }\n\n    const cluster = await this.store.getCluster(query.clusterId);\n    if (!cluster) {\n      await reply('Cluster not found.');\n      return;\n    }\n\n    const queries = await this.store.getQueriesByCluster(query.clusterId);\n\n    let text = `*🔗 Cluster: ${cluster.label || cluster.representativeQuery}*\\n\\n`;\n    text += `*Queries in cluster:* ${queries.length}\\n`;\n    text += `*Unique customers:* ${cluster.uniqueCustomers.length}\\n\\n`;\n\n    for (const q of queries) {\n      const marker = q.id === query.id ? '👉 ' : '• ';\n      text += `${marker}${q.query} (×${q.timesAsked})\\n`;\n    }\n\n    await reply(text);\n  }\n\n  private async handleHelp(reply: (text: string) => Promise<void>): Promise<void> {\n    const text = [\n      '*📖 Review Commands*',\n      '',\n      '*/review* — Show next pending query',\n      '*/review next* — Same as above',\n      '*/review accept [answer]* — Teach with answer (or suggested)',\n      '*/review edit <answer>* — Teach with your own answer',\n      '*/review skip* — Dismiss current query',\n      '*/review stats* — Show impact metrics',\n      '*/review cluster* — Show related queries in cluster',\n      '*/review help* — This help message',\n    ].join('\\n');\n\n    await reply(text);\n  }\n}\n","import type { CopilotStore } from './types.js';\n\n/**\n * Periodically sends digest summaries of unanswered queries to admin phones.\n */\nexport class DigestScheduler {\n  private timer: ReturnType<typeof setInterval> | null = null;\n\n  constructor(\n    private store: CopilotStore,\n    private config: { digestIntervalMs: number; digestMaxItems: number },\n    private sendMessage: (phone: string, text: string) => Promise<void>,\n  ) {}\n\n  /** Start the digest scheduler for the given admin phones */\n  start(adminPhones: string[]): void {\n    if (this.timer) {\n      clearInterval(this.timer);\n    }\n\n    this.timer = setInterval(async () => {\n      try {\n        const lastDigest = await this.store.getLastDigestTime();\n        const now = Date.now();\n\n        if (now - lastDigest < this.config.digestIntervalMs) {\n          return;\n        }\n\n        const digest = await this.buildDigest();\n        if (!digest) {\n          return;\n        }\n\n        for (const phone of adminPhones) {\n          await this.sendMessage(phone, digest);\n        }\n\n        await this.store.setLastDigestTime(now);\n      } catch {\n        // Digest tick failed — will retry next interval\n      }\n    }, this.config.digestIntervalMs);\n  }\n\n  /** Stop the digest scheduler */\n  stop(): void {\n    if (this.timer) {\n      clearInterval(this.timer);\n      this.timer = null;\n    }\n  }\n\n  /** Build the digest message text */\n  async buildDigest(): Promise<string | null> {\n    const metrics = await this.store.getImpactMetrics(this.config.digestMaxItems);\n\n    if (metrics.pendingCount === 0) {\n      return null;\n    }\n\n    let text = `*📬 Training Copilot Digest*\\n\\n`;\n    text += `*${metrics.pendingCount}* pending queries from *${metrics.totalCustomersAffected}* customers\\n`;\n\n    if (metrics.topPendingQueries.length > 0) {\n      text += `\\n*Top unanswered queries:*\\n`;\n      for (const q of metrics.topPendingQueries) {\n        text += `• ${q.query} (×${q.timesAsked})\\n`;\n      }\n    }\n\n    text += `\\nReply */review* to start reviewing`;\n\n    return text;\n  }\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@operor/copilot",
+  "version": "0.1.0",
+  "description": "Training Copilot — surfaces unanswered questions, clusters them, and lets admins teach the KB via chat",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "ai": "^6.0.0",
+    "better-sqlite3": "^12.0.0",
+    "sqlite-vec": "^0.1.7-alpha.2",
+    "@operor/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.0.0",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/CopilotCommandHandler.ts

@@ -0,0 +1,263 @@
+import type { CopilotStore, UnansweredQuery } from './types.js';
+import type { KnowledgeBaseRuntime } from '@operor/core';
+import type { SuggestionEngine } from './SuggestionEngine.js';
+import type { QueryClusterer } from './QueryClusterer.js';
+
+interface AdminSession {
+  currentQuery: UnansweredQuery | null;
+}
+
+/**
+ * Handles /review commands from admin users in training mode.
+ */
+export class CopilotCommandHandler {
+  /** Per-admin session state: tracks which query they're currently reviewing */
+  private sessions = new Map<string, AdminSession>();
+
+  constructor(
+    private store: CopilotStore,
+    private suggestionEngine: SuggestionEngine | undefined,
+    private kb: KnowledgeBaseRuntime,
+    private clusterer?: QueryClusterer,
+  ) {}
+
+  /**
+   * Handle a /review subcommand.
+   * @param command The full command (always '/review')
+   * @param args Subcommand + arguments (e.g. 'accept This is the answer')
+   * @param adminPhone The admin's phone number
+   * @param reply Function to send a reply back to the admin
+   */
+  async handleCommand(
+    command: string,
+    args: string,
+    adminPhone: string,
+    reply: (text: string) => Promise<void>,
+  ): Promise<void> {
+    const trimmed = args.trim();
+    const spaceIndex = trimmed.indexOf(' ');
+    const subcommand = spaceIndex === -1 ? trimmed.toLowerCase() : trimmed.slice(0, spaceIndex).toLowerCase();
+    const subArgs = spaceIndex === -1 ? '' : trimmed.slice(spaceIndex + 1).trim();
+
+    switch (subcommand) {
+      case '':
+      case 'next':
+        return this.handleNext(adminPhone, reply);
+      case 'accept':
+        return this.handleAccept(adminPhone, subArgs, reply);
+      case 'edit':
+        return this.handleEdit(adminPhone, subArgs, reply);
+      case 'skip':
+        return this.handleSkip(adminPhone, reply);
+      case 'stats':
+        return this.handleStats(reply);
+      case 'cluster':
+        return this.handleCluster(adminPhone, reply);
+      case 'help':
+        return this.handleHelp(reply);
+      default:
+        await reply(`Unknown subcommand: *${subcommand}*\n\nType */review help* to see available commands.`);
+    }
+  }
+
+  private getSession(adminPhone: string): AdminSession {
+    let session = this.sessions.get(adminPhone);
+    if (!session) {
+      session = { currentQuery: null };
+      this.sessions.set(adminPhone, session);
+    }
+    return session;
+  }
+
+  private async handleNext(adminPhone: string, reply: (text: string) => Promise<void>): Promise<void> {
+    const session = this.getSession(adminPhone);
+    const pending = await this.store.getPendingQueries(1);
+
+    if (pending.length === 0) {
+      session.currentQuery = null;
+      await reply('No pending queries to review. Great job! 🎉');
+      return;
+    }
+
+    const query = pending[0];
+    session.currentQuery = query;
+
+    let text = `*📋 Query for Review*\n\n`;
+    text += `*Question:* ${query.query}\n`;
+    text += `*Times asked:* ${query.timesAsked}\n`;
+    text += `*Unique customers:* ${query.uniqueCustomers.length}\n`;
+
+    if (query.suggestedAnswer) {
+      text += `\n*💡 Suggested answer:*\n${query.suggestedAnswer}\n`;
+    } else if (this.suggestionEngine) {
+      try {
+        const suggested = await this.suggestionEngine.suggest(query.query);
+        if (suggested) {
+          query.suggestedAnswer = suggested;
+          await this.store.updateQuery(query.id, { suggestedAnswer: suggested });
+          text += `\n*💡 Suggested answer:*\n${suggested}\n`;
+        }
+      } catch {
+        // Suggestion failed — continue without it
+      }
+    }
+
+    text += `\n*Actions:*`;
+    text += `\n/review accept [answer] — Teach this answer`;
+    text += `\n/review edit <answer> — Provide your own answer`;
+    text += `\n/review skip — Skip this query`;
+
+    await reply(text);
+  }
+
+  private async handleAccept(
+    adminPhone: string,
+    answerText: string,
+    reply: (text: string) => Promise<void>,
+  ): Promise<void> {
+    const session = this.getSession(adminPhone);
+    const query = session.currentQuery;
+
+    if (!query) {
+      await reply('No query selected. Use */review next* to load one.');
+      return;
+    }
+
+    const answer = answerText || query.suggestedAnswer;
+    if (!answer) {
+      await reply('No answer provided and no suggestion available. Use */review edit <answer>* to provide one.');
+      return;
+    }
+
+    await this.kb.ingestFaq(query.query, answer);
+    await this.store.updateQuery(query.id, {
+      status: 'taught',
+      taughtAnswer: answer,
+      updatedAt: Date.now(),
+    });
+
+    session.currentQuery = null;
+
+    await reply(`*✅ Taught!*\n\n*Q:* ${query.query}\n*A:* ${answer}`);
+  }
+
+  private async handleEdit(
+    adminPhone: string,
+    answerText: string,
+    reply: (text: string) => Promise<void>,
+  ): Promise<void> {
+    const session = this.getSession(adminPhone);
+    const query = session.currentQuery;
+
+    if (!query) {
+      await reply('No query selected. Use */review next* to load one.');
+      return;
+    }
+
+    if (!answerText) {
+      await reply('Please provide an answer: */review edit <your answer>*');
+      return;
+    }
+
+    await this.kb.ingestFaq(query.query, answerText);
+    await this.store.updateQuery(query.id, {
+      status: 'taught',
+      taughtAnswer: answerText,
+      updatedAt: Date.now(),
+    });
+
+    session.currentQuery = null;
+
+    await reply(`*✅ Taught!*\n\n*Q:* ${query.query}\n*A:* ${answerText}`);
+  }
+
+  private async handleSkip(adminPhone: string, reply: (text: string) => Promise<void>): Promise<void> {
+    const session = this.getSession(adminPhone);
+    const query = session.currentQuery;
+
+    if (!query) {
+      await reply('No query selected. Use */review next* to load one.');
+      return;
+    }
+
+    await this.store.updateQuery(query.id, {
+      status: 'dismissed',
+      updatedAt: Date.now(),
+    });
+
+    session.currentQuery = null;
+
+    await reply(`*⏭️ Skipped:* ${query.query}`);
+  }
+
+  private async handleStats(reply: (text: string) => Promise<void>): Promise<void> {
+    const metrics = await this.store.getImpactMetrics();
+
+    let text = `*📊 Copilot Stats*\n\n`;
+    text += `*Pending:* ${metrics.pendingCount}\n`;
+    text += `*Taught:* ${metrics.taughtCount}\n`;
+    text += `*Dismissed:* ${metrics.dismissedCount}\n`;
+    text += `*Customers affected:* ${metrics.totalCustomersAffected}\n`;
+    text += `*Total times asked:* ${metrics.totalTimesAsked}`;
+
+    if (metrics.topPendingQueries.length > 0) {
+      text += `\n\n*Top pending queries:*`;
+      for (const q of metrics.topPendingQueries) {
+        text += `\n• ${q.query} (×${q.timesAsked})`;
+      }
+    }
+
+    await reply(text);
+  }
+
+  private async handleCluster(adminPhone: string, reply: (text: string) => Promise<void>): Promise<void> {
+    const session = this.getSession(adminPhone);
+    const query = session.currentQuery;
+
+    if (!query) {
+      await reply('No query selected. Use */review next* to load one.');
+      return;
+    }
+
+    if (!query.clusterId) {
+      await reply('This query is not part of any cluster.');
+      return;
+    }
+
+    const cluster = await this.store.getCluster(query.clusterId);
+    if (!cluster) {
+      await reply('Cluster not found.');
+      return;
+    }
+
+    const queries = await this.store.getQueriesByCluster(query.clusterId);
+
+    let text = `*🔗 Cluster: ${cluster.label || cluster.representativeQuery}*\n\n`;
+    text += `*Queries in cluster:* ${queries.length}\n`;
+    text += `*Unique customers:* ${cluster.uniqueCustomers.length}\n\n`;
+
+    for (const q of queries) {
+      const marker = q.id === query.id ? '👉 ' : '• ';
+      text += `${marker}${q.query} (×${q.timesAsked})\n`;
+    }
+
+    await reply(text);
+  }
+
+  private async handleHelp(reply: (text: string) => Promise<void>): Promise<void> {
+    const text = [
+      '*📖 Review Commands*',
+      '',
+      '*/review* — Show next pending query',
+      '*/review next* — Same as above',
+      '*/review accept [answer]* — Teach with answer (or suggested)',
+      '*/review edit <answer>* — Teach with your own answer',
+      '*/review skip* — Dismiss current query',
+      '*/review stats* — Show impact metrics',
+      '*/review cluster* — Show related queries in cluster',
+      '*/review help* — This help message',
+    ].join('\n');
+
+    await reply(text);
+  }
+}

package/src/DigestScheduler.ts

@@ -0,0 +1,76 @@
+import type { CopilotStore } from './types.js';
+
+/**
+ * Periodically sends digest summaries of unanswered queries to admin phones.
+ */
+export class DigestScheduler {
+  private timer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(
+    private store: CopilotStore,
+    private config: { digestIntervalMs: number; digestMaxItems: number },
+    private sendMessage: (phone: string, text: string) => Promise<void>,
+  ) {}
+
+  /** Start the digest scheduler for the given admin phones */
+  start(adminPhones: string[]): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+    }
+
+    this.timer = setInterval(async () => {
+      try {
+        const lastDigest = await this.store.getLastDigestTime();
+        const now = Date.now();
+
+        if (now - lastDigest < this.config.digestIntervalMs) {
+          return;
+        }
+
+        const digest = await this.buildDigest();
+        if (!digest) {
+          return;
+        }
+
+        for (const phone of adminPhones) {
+          await this.sendMessage(phone, digest);
+        }
+
+        await this.store.setLastDigestTime(now);
+      } catch {
+        // Digest tick failed — will retry next interval
+      }
+    }, this.config.digestIntervalMs);
+  }
+
+  /** Stop the digest scheduler */
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /** Build the digest message text */
+  async buildDigest(): Promise<string | null> {
+    const metrics = await this.store.getImpactMetrics(this.config.digestMaxItems);
+
+    if (metrics.pendingCount === 0) {
+      return null;
+    }
+
+    let text = `*📬 Training Copilot Digest*\n\n`;
+    text += `*${metrics.pendingCount}* pending queries from *${metrics.totalCustomersAffected}* customers\n`;
+
+    if (metrics.topPendingQueries.length > 0) {
+      text += `\n*Top unanswered queries:*\n`;
+      for (const q of metrics.topPendingQueries) {
+        text += `• ${q.query} (×${q.timesAsked})\n`;
+      }
+    }
+
+    text += `\nReply */review* to start reviewing`;
+
+    return text;
+  }
+}

package/src/InMemoryCopilotStore.ts

@@ -0,0 +1,90 @@
+import type { CopilotStore, UnansweredQuery, QueryCluster, ImpactMetrics } from './types.js';
+
+/**
+ * In-memory copilot store for testing and development.
+ */
+export class InMemoryCopilotStore implements CopilotStore {
+  private queries = new Map<string, UnansweredQuery>();
+  private clusters = new Map<string, QueryCluster>();
+  private lastDigestTime = 0;
+
+  async initialize(): Promise<void> {}
+  async close(): Promise<void> {}
+
+  async addQuery(query: UnansweredQuery): Promise<void> {
+    this.queries.set(query.id, { ...query });
+  }
+
+  async getQuery(id: string): Promise<UnansweredQuery | null> {
+    return this.queries.get(id) ?? null;
+  }
+
+  async updateQuery(id: string, updates: Partial<UnansweredQuery>): Promise<void> {
+    const q = this.queries.get(id);
+    if (q) this.queries.set(id, { ...q, ...updates, updatedAt: Date.now() });
+  }
+
+  async getPendingQueries(limit?: number): Promise<UnansweredQuery[]> {
+    const pending = [...this.queries.values()]
+      .filter(q => q.status === 'pending')
+      .sort((a, b) => b.timesAsked - a.timesAsked);
+    return limit ? pending.slice(0, limit) : pending;
+  }
+
+  async findSimilarQuery(normalizedQuery: string): Promise<UnansweredQuery | null> {
+    for (const q of this.queries.values()) {
+      if (q.normalizedQuery === normalizedQuery) return q;
+    }
+    return null;
+  }
+
+  async getQueriesByCluster(clusterId: string): Promise<UnansweredQuery[]> {
+    return [...this.queries.values()].filter(q => q.clusterId === clusterId);
+  }
+
+  async addCluster(cluster: QueryCluster): Promise<void> {
+    this.clusters.set(cluster.id, { ...cluster });
+  }
+
+  async getCluster(id: string): Promise<QueryCluster | null> {
+    return this.clusters.get(id) ?? null;
+  }
+
+  async updateCluster(id: string, updates: Partial<QueryCluster>): Promise<void> {
+    const c = this.clusters.get(id);
+    if (c) this.clusters.set(id, { ...c, ...updates, updatedAt: Date.now() });
+  }
+
+  async getOpenClusters(): Promise<QueryCluster[]> {
+    return [...this.clusters.values()].filter(c => c.status === 'pending');
+  }
+
+  async getImpactMetrics(topN = 10): Promise<ImpactMetrics> {
+    const all = [...this.queries.values()];
+    const pending = all.filter(q => q.status === 'pending');
+    const allCustomers = new Set<string>();
+    let totalAsked = 0;
+    for (const q of all) {
+      q.uniqueCustomers.forEach(c => allCustomers.add(c));
+      totalAsked += q.timesAsked;
+    }
+    return {
+      pendingCount: pending.length,
+      taughtCount: all.filter(q => q.status === 'taught').length,
+      dismissedCount: all.filter(q => q.status === 'dismissed').length,
+      totalCustomersAffected: allCustomers.size,
+      totalTimesAsked: totalAsked,
+      topPendingQueries: pending
+        .sort((a, b) => b.timesAsked - a.timesAsked)
+        .slice(0, topN),
+    };
+  }
+
+  async getLastDigestTime(): Promise<number> {
+    return this.lastDigestTime;
+  }
+
+  async setLastDigestTime(time: number): Promise<void> {
+    this.lastDigestTime = time;
+  }
+}

package/src/QueryClusterer.ts

@@ -0,0 +1,84 @@
+import crypto from 'node:crypto';
+import type { CopilotStore, EmbeddingService, QueryCluster } from './types.js';
+
+/**
+ * Groups semantically similar unanswered queries into clusters.
+ */
+export class QueryClusterer {
+  constructor(
+    private store: CopilotStore,
+    private embedder: EmbeddingService,
+    private config: { clusterThreshold: number } = { clusterThreshold: 0.87 },
+  ) {}
+
+  /**
+   * Assign a query to an existing cluster or create a new one.
+   * Returns the cluster ID.
+   */
+  async assignCluster(queryId: string, queryText: string, embedding: number[]): Promise<string> {
+    const clusters = await this.store.getOpenClusters();
+
+    let bestCluster: QueryCluster | null = null;
+    let bestScore = -1;
+
+    for (const cluster of clusters) {
+      if (!cluster.centroid) continue;
+      const score = this.cosineSimilarity(embedding, cluster.centroid);
+      if (score > bestScore) {
+        bestScore = score;
+        bestCluster = cluster;
+      }
+    }
+
+    if (bestCluster && bestScore >= this.config.clusterThreshold) {
+      const newCount = bestCluster.queryCount + 1;
+      const newCentroid = this.updateCentroid(bestCluster.centroid!, embedding, newCount);
+
+      await this.store.updateCluster(bestCluster.id, {
+        centroid: newCentroid,
+        queryCount: newCount,
+        updatedAt: Date.now(),
+      });
+
+      await this.store.updateQuery(queryId, { clusterId: bestCluster.id });
+
+      return bestCluster.id;
+    }
+
+    // Create a new cluster
+    const clusterId = crypto.randomUUID();
+    const now = Date.now();
+
+    const newCluster: QueryCluster = {
+      id: clusterId,
+      representativeQuery: queryText,
+      centroid: embedding,
+      queryCount: 1,
+      uniqueCustomers: [],
+      status: 'pending',
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    await this.store.addCluster(newCluster);
+    await this.store.updateQuery(queryId, { clusterId });
+
+    return clusterId;
+  }
+
+  /** Cosine similarity between two vectors */
+  cosineSimilarity(a: number[], b: number[]): number {
+    let dot = 0, magA = 0, magB = 0;
+    for (let i = 0; i < a.length; i++) {
+      dot += a[i] * b[i];
+      magA += a[i] * a[i];
+      magB += b[i] * b[i];
+    }
+    return dot / (Math.sqrt(magA) * Math.sqrt(magB));
+  }
+
+  /** Compute running average centroid */
+  updateCentroid(current: number[], newVec: number[], count: number): number[] {
+    return current.map((v, i) => (v * (count - 1) + newVec[i]) / count);
+  }
+}