@diegoaltoworks/chatter 0.62.0 → 0.64.0

package/dist/channels/whatsapp/channel.d.ts

@@ -90,6 +90,15 @@ export interface LeaseGatedConnectDeps {
     waitMs?: number;
     schedule?: (fn: () => void, ms: number) => void;
     logger?: Logger;
+    /**
+     * Recovery for a `connect` that threw, replacing the default (release the
+     * session, re-check after `waitMs`). The channel injects one so a thrown
+     * connect backs off on the same failure counter a closed connection uses
+     * instead of re-attempting at a flat interval. Whatever it does, it must
+     * end with another attempt scheduled: a session whose lease is held with
+     * no live socket and nothing pending never recovers on its own.
+     */
+    onConnectFailed?: (sessionId: string, error: unknown) => void;
 }
 /**
  * Acquire `sessionId`'s lease before connecting — two instances must never
@@ -99,6 +108,11 @@ export interface LeaseGatedConnectDeps {
  * heartbeat ever finds the lease gone (this instance went stale and another
  * took over), the session is torn down and this re-enters the same
  * wait-and-retry loop rather than staying connected alongside the new holder.
+ *
+ * Every failed connect attempt lands back here too, whether it threw on its
+ * first try or on a reconnect: this loop is the only way a session recovers,
+ * so an attempt that fails without leaving a socket behind (no socket, no
+ * future "close" event) must re-enter it rather than stop at a log line.
  */
 export declare function acquireSessionLease(sessionId: string, deps: LeaseGatedConnectDeps): Promise<void>;
 /** Sender-registry name for a session — the default session stays unprefixed so single-number deployments see a plain `"whatsapp"` name. */

package/dist/channels/whatsapp/channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../../src/channels/whatsapp/channel.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../../src/channels/whatsapp/channel.ts"],"names":[],"mappings":"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"}

package/dist/channels/whatsapp/index.js

@@ -360,11 +360,17 @@ async function shutdownWaSessions(sessions) {
     })
   );
 }
-async function loseSession(sessionId, sessions) {
+function claimSession(sessionId, sessions) {
   const handle = sessions.get(sessionId);
-  if (!handle) return;
+  if (!handle) return void 0;
   sessions.delete(sessionId);
+  return handle;
+}
+async function loseSession(sessionId, sessions) {
+  const handle = claimSession(sessionId, sessions);
+  if (!handle) return false;
   await shutdownWaSessions(/* @__PURE__ */ new Map([[sessionId, handle]]));
+  return true;
 }
 async function acquireSessionLease(sessionId, deps) {
   const { leaseStore, instanceId, sessions, isStopped, connect } = deps;
@@ -400,7 +406,9 @@ async function acquireSessionLease(sessionId, deps) {
     void leaseStore.tryAcquire(sessionId, instanceId, now(), staleMs).then((stillHeld) => {
       if (stillHeld || isStopped()) return;
       logger.error(`WhatsApp[${sessionId}]: lost the lease to another instance \u2014 disconnecting`);
-      void loseSession(sessionId, sessions).then(retry);
+      void loseSession(sessionId, sessions).then((lost) => {
+        if (lost) retry();
+      });
     }).catch((error) => logger.warn(`WhatsApp[${sessionId}]: lease heartbeat failed:`, error));
   }, heartbeatMs);
   if (typeof heartbeat === "object" && "unref" in heartbeat) heartbeat.unref();
@@ -412,6 +420,10 @@ async function acquireSessionLease(sessionId, deps) {
   try {
     await connect(sessionId);
   } catch (error) {
+    if (deps.onConnectFailed) {
+      deps.onConnectFailed(sessionId, error);
+      return;
+    }
     logger.error(`WhatsApp[${sessionId}]: connect failed right after acquiring the lease:`, error);
     await loseSession(sessionId, sessions);
     retry();
@@ -458,6 +470,50 @@ function createWhatsAppChannel(config) {
       const authStore = config.authStore ?? createTursoWaAuthKV(deps.db);
       senders = deps.senders;
       await loadBaileys2();
+      const leaseDeps = {
+        leaseStore,
+        instanceId,
+        sessions,
+        isStopped: () => stopped,
+        connect,
+        now,
+        staleMs,
+        heartbeatMs,
+        waitMs,
+        schedule,
+        logger: log,
+        onConnectFailed: recoverFromFailedConnect
+      };
+      function nextRetryDelayMs(sessionId) {
+        const failures = failureCounts.get(sessionId) ?? 0;
+        failureCounts.set(sessionId, failures + 1);
+        return reconnectDelayMs(failures);
+      }
+      function attemptConnect(sessionId) {
+        void connect(sessionId).catch((error) => recoverFromFailedConnect(sessionId, error));
+      }
+      function recoverFromFailedConnect(sessionId, error) {
+        if (stopped) return;
+        const handle = claimSession(sessionId, sessions);
+        if (!handle) return;
+        const delay = nextRetryDelayMs(sessionId);
+        log.error(
+          `WhatsApp[${sessionId}]: connect attempt failed, releasing the lease and retrying in ${Math.round(delay / 1e3)}s:`,
+          error
+        );
+        schedule(
+          () => void acquireSessionLease(sessionId, leaseDeps).catch(
+            (retryError) => log.error(`WhatsApp[${sessionId}]: lease re-check failed:`, retryError)
+          ),
+          delay
+        );
+        void shutdownWaSessions(/* @__PURE__ */ new Map([[sessionId, handle]])).catch(
+          (teardownError) => log.warn(
+            `WhatsApp[${sessionId}]: teardown after a failed connect failed:`,
+            teardownError
+          )
+        );
+      }
       async function connect(sessionId) {
         if (stopped || !sessions.has(sessionId)) return;
         const baileys = await loadBaileys2();
@@ -476,7 +532,7 @@ function createWhatsAppChannel(config) {
           log.warn(
             `WhatsApp[${sessionId}]: no paired session found \u2014 pair it first (see docs/channels.md). Re-checking in 60s.`
           );
-          schedule(() => void connect(sessionId).catch(() => void 0), 6e4);
+          schedule(() => attemptConnect(sessionId), 6e4);
           return;
         }
         const { version } = await baileys.fetchLatestBaileysVersion();
@@ -542,17 +598,11 @@ function createWhatsAppChannel(config) {
               return;
             }
             if (!stopped && sessions.has(sessionId)) {
-              const delay = reconnectDelayMs(failureCounts.get(sessionId) ?? 0);
-              failureCounts.set(sessionId, (failureCounts.get(sessionId) ?? 0) + 1);
+              const delay = nextRetryDelayMs(sessionId);
               log.warn(
                 `WhatsApp[${sessionId}]: connection closed (${statusCode ?? "?"}), reconnecting in ${Math.round(delay / 1e3)}s...`
               );
-              schedule(
-                () => void connect(sessionId).catch(
-                  (error) => log.error(`WhatsApp[${sessionId}]: reconnect failed:`, error)
-                ),
-                delay
-              );
+              schedule(() => attemptConnect(sessionId), delay);
             }
           }
         });
@@ -570,19 +620,9 @@ function createWhatsAppChannel(config) {
         }
       }
       for (const sessionId of sessionIds) {
-        void acquireSessionLease(sessionId, {
-          leaseStore,
-          instanceId,
-          sessions,
-          isStopped: () => stopped,
-          connect,
-          now,
-          staleMs,
-          heartbeatMs,
-          waitMs,
-          schedule,
-          logger: log
-        }).catch((error) => log.error(`WhatsApp[${sessionId}]: failed to start:`, error));
+        void acquireSessionLease(sessionId, leaseDeps).catch(
+          (error) => log.error(`WhatsApp[${sessionId}]: failed to start:`, error)
+        );
       }
     },
     async stop() {

package/dist/channels/whatsapp/index.mjs

@@ -295,11 +295,17 @@ async function shutdownWaSessions(sessions) {
     })
   );
 }
-async function loseSession(sessionId, sessions) {
+function claimSession(sessionId, sessions) {
   const handle = sessions.get(sessionId);
-  if (!handle) return;
+  if (!handle) return void 0;
   sessions.delete(sessionId);
+  return handle;
+}
+async function loseSession(sessionId, sessions) {
+  const handle = claimSession(sessionId, sessions);
+  if (!handle) return false;
   await shutdownWaSessions(/* @__PURE__ */ new Map([[sessionId, handle]]));
+  return true;
 }
 async function acquireSessionLease(sessionId, deps) {
   const { leaseStore, instanceId, sessions, isStopped, connect } = deps;
@@ -335,7 +341,9 @@ async function acquireSessionLease(sessionId, deps) {
     void leaseStore.tryAcquire(sessionId, instanceId, now(), staleMs).then((stillHeld) => {
       if (stillHeld || isStopped()) return;
       logger.error(`WhatsApp[${sessionId}]: lost the lease to another instance \u2014 disconnecting`);
-      void loseSession(sessionId, sessions).then(retry);
+      void loseSession(sessionId, sessions).then((lost) => {
+        if (lost) retry();
+      });
     }).catch((error) => logger.warn(`WhatsApp[${sessionId}]: lease heartbeat failed:`, error));
   }, heartbeatMs);
   if (typeof heartbeat === "object" && "unref" in heartbeat) heartbeat.unref();
@@ -347,6 +355,10 @@ async function acquireSessionLease(sessionId, deps) {
   try {
     await connect(sessionId);
   } catch (error) {
+    if (deps.onConnectFailed) {
+      deps.onConnectFailed(sessionId, error);
+      return;
+    }
     logger.error(`WhatsApp[${sessionId}]: connect failed right after acquiring the lease:`, error);
     await loseSession(sessionId, sessions);
     retry();
@@ -393,6 +405,50 @@ function createWhatsAppChannel(config) {
       const authStore = config.authStore ?? createTursoWaAuthKV(deps.db);
       senders = deps.senders;
       await loadBaileys2();
+      const leaseDeps = {
+        leaseStore,
+        instanceId,
+        sessions,
+        isStopped: () => stopped,
+        connect,
+        now,
+        staleMs,
+        heartbeatMs,
+        waitMs,
+        schedule,
+        logger: log,
+        onConnectFailed: recoverFromFailedConnect
+      };
+      function nextRetryDelayMs(sessionId) {
+        const failures = failureCounts.get(sessionId) ?? 0;
+        failureCounts.set(sessionId, failures + 1);
+        return reconnectDelayMs(failures);
+      }
+      function attemptConnect(sessionId) {
+        void connect(sessionId).catch((error) => recoverFromFailedConnect(sessionId, error));
+      }
+      function recoverFromFailedConnect(sessionId, error) {
+        if (stopped) return;
+        const handle = claimSession(sessionId, sessions);
+        if (!handle) return;
+        const delay = nextRetryDelayMs(sessionId);
+        log.error(
+          `WhatsApp[${sessionId}]: connect attempt failed, releasing the lease and retrying in ${Math.round(delay / 1e3)}s:`,
+          error
+        );
+        schedule(
+          () => void acquireSessionLease(sessionId, leaseDeps).catch(
+            (retryError) => log.error(`WhatsApp[${sessionId}]: lease re-check failed:`, retryError)
+          ),
+          delay
+        );
+        void shutdownWaSessions(/* @__PURE__ */ new Map([[sessionId, handle]])).catch(
+          (teardownError) => log.warn(
+            `WhatsApp[${sessionId}]: teardown after a failed connect failed:`,
+            teardownError
+          )
+        );
+      }
       async function connect(sessionId) {
         if (stopped || !sessions.has(sessionId)) return;
         const baileys = await loadBaileys2();
@@ -411,7 +467,7 @@ function createWhatsAppChannel(config) {
           log.warn(
             `WhatsApp[${sessionId}]: no paired session found \u2014 pair it first (see docs/channels.md). Re-checking in 60s.`
           );
-          schedule(() => void connect(sessionId).catch(() => void 0), 6e4);
+          schedule(() => attemptConnect(sessionId), 6e4);
           return;
         }
         const { version } = await baileys.fetchLatestBaileysVersion();
@@ -477,17 +533,11 @@ function createWhatsAppChannel(config) {
               return;
             }
             if (!stopped && sessions.has(sessionId)) {
-              const delay = reconnectDelayMs(failureCounts.get(sessionId) ?? 0);
-              failureCounts.set(sessionId, (failureCounts.get(sessionId) ?? 0) + 1);
+              const delay = nextRetryDelayMs(sessionId);
               log.warn(
                 `WhatsApp[${sessionId}]: connection closed (${statusCode ?? "?"}), reconnecting in ${Math.round(delay / 1e3)}s...`
               );
-              schedule(
-                () => void connect(sessionId).catch(
-                  (error) => log.error(`WhatsApp[${sessionId}]: reconnect failed:`, error)
-                ),
-                delay
-              );
+              schedule(() => attemptConnect(sessionId), delay);
             }
           }
         });
@@ -505,19 +555,9 @@ function createWhatsAppChannel(config) {
         }
       }
       for (const sessionId of sessionIds) {
-        void acquireSessionLease(sessionId, {
-          leaseStore,
-          instanceId,
-          sessions,
-          isStopped: () => stopped,
-          connect,
-          now,
-          staleMs,
-          heartbeatMs,
-          waitMs,
-          schedule,
-          logger: log
-        }).catch((error) => log.error(`WhatsApp[${sessionId}]: failed to start:`, error));
+        void acquireSessionLease(sessionId, leaseDeps).catch(
+          (error) => log.error(`WhatsApp[${sessionId}]: failed to start:`, error)
+        );
       }
     },
     async stop() {

package/dist/core/knowledgeHealth.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Post-boot and periodic health checks for the default `VectorStore`
+ * knowledge base, so a collapse is visible in logs the moment it happens
+ * instead of waiting for a user to notice broken answers - the gap that let
+ * two knowledge-base wipes go unnoticed until someone spotted broken
+ * answers.
+ */
+import type { Client as LibsqlClient } from "@libsql/client";
+import { type BuildLock } from "./buildLock";
+import { type Logger } from "./logger";
+export interface KnowledgeHealth {
+    chunksByBucket: Record<string, number>;
+    totalChunks: number;
+    totalEmbeddings: number;
+    /** Embeddings rows with no matching chunks row. */
+    orphanedEmbeddings: number;
+    /** Chunks rows with no matching embeddings row (e.g. a build interrupted mid-embed). */
+    missingEmbeddings: number;
+}
+/**
+ * Read-only snapshot of chunks/embeddings consistency, logged at `info` -
+ * escalating to `warn` when `totalChunks === 0` (the exact signature of both
+ * knowledge-base wipes) or `orphanedEmbeddings > 0`. The query shape mirrors
+ * the diagnostic used live to investigate the second incident.
+ */
+export declare function checkKnowledgeHealth(db: LibsqlClient, logger: Logger): Promise<KnowledgeHealth>;
+export interface KnowledgeHealthCheckConfig {
+    /** Run post-boot and periodic health checks. Default: true. */
+    enabled?: boolean;
+    /** How often to re-run the check after boot. Default: 30 minutes. */
+    intervalMs?: number;
+    /**
+     * Delete orphaned embeddings rows (no matching chunk) whenever a check
+     * finds them. Default: false - opt-in, since it's a delete even though a
+     * safe/idempotent one. Under normal operation orphans should be rare
+     * (`cleanupStaleChunks` already deletes a stale chunk and its embedding
+     * together); this exists chiefly to clean up historical damage and catch
+     * any future code path that doesn't maintain that invariant.
+     */
+    autoCleanOrphanedEmbeddings?: boolean;
+}
+export declare const DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS: number;
+export interface KnowledgeHealthScheduler {
+    /** Runs one check immediately, applying auto-clean if configured. */
+    runOnce(): Promise<KnowledgeHealth>;
+    /** Stops periodic re-checks. Safe to call even if periodic checks never started. */
+    stop(): void;
+}
+export interface ScheduleKnowledgeHealthChecksOptions {
+    db: LibsqlClient;
+    config?: KnowledgeHealthCheckConfig;
+    /** Default: a console logger writing to stderr. */
+    logger?: Logger;
+    /** Default: a lock table in `db` (see buildLock.ts) - the same lock `VectorStore.build()` uses. */
+    buildLock?: BuildLock;
+    /** Identifies this process while it holds the build lock during cleanup. Default: a random id. */
+    instanceId?: string;
+    /** Injectable for tests; defaults to `setInterval`/`clearInterval`. */
+    schedule?: (fn: () => void, ms: number) => {
+        stop: () => void;
+    };
+}
+/**
+ * Runs {@link checkKnowledgeHealth} once immediately and, unless disabled,
+ * again on `intervalMs` via an unref'd timer - so it never blocks process
+ * exit or leaves an open handle in tests. `enabled: false` skips both the
+ * immediate run and the periodic one.
+ */
+export declare function scheduleKnowledgeHealthChecks(options: ScheduleKnowledgeHealthChecksOptions): Promise<KnowledgeHealthScheduler>;
+//# sourceMappingURL=knowledgeHealth.d.ts.map

package/dist/core/knowledgeHealth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledgeHealth.d.ts","sourceRoot":"","sources":["../../src/core/knowledgeHealth.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAuB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAE5D,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,wFAAwF;IACxF,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,YAAY,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,eAAe,CAAC,CAuC1B;AAsCD,MAAM,WAAW,0BAA0B;IACzC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;OAOG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAED,eAAO,MAAM,oCAAoC,QAAc,CAAC;AAEhE,MAAM,WAAW,wBAAwB;IACvC,qEAAqE;IACrE,OAAO,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;IACpC,oFAAoF;IACpF,IAAI,IAAI,IAAI,CAAC;CACd;AAED,MAAM,WAAW,oCAAoC;IACnD,EAAE,EAAE,YAAY,CAAC;IACjB,MAAM,CAAC,EAAE,0BAA0B,CAAC;IACpC,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mGAAmG;IACnG,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,kGAAkG;IAClG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK;QAAE,IAAI,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;CACjE;AAQD;;;;;GAKG;AACH,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,oCAAoC,GAC5C,OAAO,CAAC,wBAAwB,CAAC,CAyCnC"}

package/dist/index.js

@@ -416,6 +416,119 @@ var init_retrieval = __esm({
   }
 });
 
+// src/core/knowledgeHealth.ts
+var knowledgeHealth_exports = {};
+__export(knowledgeHealth_exports, {
+  DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS: () => DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS,
+  checkKnowledgeHealth: () => checkKnowledgeHealth,
+  scheduleKnowledgeHealthChecks: () => scheduleKnowledgeHealthChecks
+});
+async function checkKnowledgeHealth(db, logger) {
+  const [byBucket, totalChunksRes, totalEmbeddingsRes, orphanedRes, missingRes] = await Promise.all(
+    [
+      db.execute("SELECT bucket, COUNT(*) as count FROM chunks GROUP BY bucket"),
+      db.execute("SELECT COUNT(*) as count FROM chunks"),
+      db.execute("SELECT COUNT(*) as count FROM embeddings"),
+      db.execute(
+        "SELECT COUNT(*) as count FROM embeddings e LEFT JOIN chunks c ON c.id = e.id WHERE c.id IS NULL"
+      ),
+      db.execute(
+        "SELECT COUNT(*) as count FROM chunks c LEFT JOIN embeddings e ON e.id = c.id WHERE e.id IS NULL"
+      )
+    ]
+  );
+  const chunksByBucket = {};
+  for (const row of byBucket.rows) {
+    chunksByBucket[String(row.bucket)] = Number(row.count ?? 0);
+  }
+  const health = {
+    chunksByBucket,
+    totalChunks: Number(totalChunksRes.rows[0]?.count ?? 0),
+    totalEmbeddings: Number(totalEmbeddingsRes.rows[0]?.count ?? 0),
+    orphanedEmbeddings: Number(orphanedRes.rows[0]?.count ?? 0),
+    missingEmbeddings: Number(missingRes.rows[0]?.count ?? 0)
+  };
+  const summary = `chunksByBucket=${JSON.stringify(health.chunksByBucket)} totalChunks=${health.totalChunks} totalEmbeddings=${health.totalEmbeddings} orphanedEmbeddings=${health.orphanedEmbeddings} missingEmbeddings=${health.missingEmbeddings}`;
+  if (health.totalChunks === 0 || health.orphanedEmbeddings > 0) {
+    logger.warn(`Knowledge base health check: ${summary}`);
+  } else {
+    logger.info(`Knowledge base health check: ${summary}`);
+  }
+  return health;
+}
+async function cleanOrphanedEmbeddings(db, buildLock, instanceId, logger) {
+  const acquired = await buildLock.tryAcquire(
+    BUILD_LOCK_KEY,
+    instanceId,
+    Date.now(),
+    BUILD_LOCK_STALE_MS
+  );
+  if (!acquired) {
+    logger.warn(
+      "Knowledge health: skipping orphaned-embeddings cleanup - the build lock is held by another instance."
+    );
+    return;
+  }
+  try {
+    const result = await db.execute(
+      "DELETE FROM embeddings WHERE id NOT IN (SELECT id FROM chunks)"
+    );
+    if (result.rowsAffected > 0) {
+      logger.warn(`Knowledge health: deleted ${result.rowsAffected} orphaned embedding row(s).`);
+    }
+  } finally {
+    await buildLock.release(BUILD_LOCK_KEY, instanceId);
+  }
+}
+async function scheduleKnowledgeHealthChecks(options) {
+  const logger = options.logger ?? createConsoleLogger();
+  const enabled = options.config?.enabled !== false;
+  const intervalMs = options.config?.intervalMs ?? DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS;
+  const autoClean = options.config?.autoCleanOrphanedEmbeddings === true;
+  const buildLock = options.buildLock ?? createTursoBuildLock(options.db);
+  const instanceId = options.instanceId ?? crypto.randomUUID();
+  const schedule = options.schedule ?? defaultSchedule;
+  async function runOnce() {
+    const health = await checkKnowledgeHealth(options.db, logger);
+    if (autoClean && health.orphanedEmbeddings > 0) {
+      await cleanOrphanedEmbeddings(options.db, buildLock, instanceId, logger);
+    }
+    return health;
+  }
+  let handle;
+  if (enabled) {
+    await runOnce();
+    if (intervalMs > 0) {
+      let ticking = false;
+      handle = schedule(() => {
+        if (ticking) return;
+        ticking = true;
+        runOnce().catch((error) => logger.error("Knowledge health check failed:", error)).finally(() => {
+          ticking = false;
+        });
+      }, intervalMs);
+    }
+  }
+  return {
+    runOnce,
+    stop: () => handle?.stop()
+  };
+}
+var DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS, defaultSchedule;
+var init_knowledgeHealth = __esm({
+  "src/core/knowledgeHealth.ts"() {
+    "use strict";
+    init_buildLock();
+    init_logger();
+    DEFAULT_KNOWLEDGE_HEALTH_INTERVAL_MS = 30 * 6e4;
+    defaultSchedule = (fn, ms) => {
+      const timer = setInterval(fn, ms);
+      if (typeof timer === "object" && "unref" in timer) timer.unref();
+      return { stop: () => clearInterval(timer) };
+    };
+  }
+});
+
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
@@ -1221,6 +1334,7 @@ async function createMCPServer(config) {
   });
   const model = config.openai.model || DEFAULT_MODEL;
   let store;
+  let db;
   if (config.retriever) {
     store = config.retriever;
   } else {
@@ -1228,7 +1342,7 @@ async function createMCPServer(config) {
       throw new Error(DATABASE_CONFIG_REQUIRED_MESSAGE);
     }
     const { DEFAULT_KNOWLEDGE_DIR: DEFAULT_KNOWLEDGE_DIR2, VectorStore: VectorStore2, createOpenAIEmbedder: createOpenAIEmbedder2, openLibsqlClient: openLibsqlClient2 } = await Promise.resolve().then(() => (init_retrieval(), retrieval_exports));
-    const db = await openLibsqlClient2(config.database);
+    db = await openLibsqlClient2(config.database);
     store = new VectorStore2(createOpenAIEmbedder2(client), {
       databaseClient: db,
       knowledgeDir: config.knowledgeDir || DEFAULT_KNOWLEDGE_DIR2,
@@ -1237,6 +1351,15 @@ async function createMCPServer(config) {
   }
   await store.build?.();
   log.info("\u2705 Knowledge base ready");
+  let knowledgeHealth;
+  if (db) {
+    const { scheduleKnowledgeHealthChecks: scheduleKnowledgeHealthChecks2 } = await Promise.resolve().then(() => (init_knowledgeHealth(), knowledgeHealth_exports));
+    knowledgeHealth = await scheduleKnowledgeHealthChecks2({
+      db,
+      config: config.knowledgeHealthCheck,
+      logger: log
+    });
+  }
   const prompts = new PromptLoader(promptsDir, config.bot);
   const server = new McpServer({
     name: config.bot.name,
@@ -1433,7 +1556,9 @@ async function createMCPServer(config) {
   log.info(
     `\u2705 ${config.bot.name} MCP Server ready (transport: ${transportMode}, tools: ${enabledTools.join(", ") || "none"})`
   );
-  return server;
+  return Object.assign(server, {
+    stopKnowledgeHealthChecks: () => knowledgeHealth?.stop()
+  });
 }
 
 // src/middleware/apiKey.ts
@@ -2416,6 +2541,15 @@ async function createServer(config) {
   }
   await store.build?.();
   logger.info("\u2705 Knowledge base ready");
+  let knowledgeHealth;
+  if (db && !config.retriever) {
+    const { scheduleKnowledgeHealthChecks: scheduleKnowledgeHealthChecks2 } = await Promise.resolve().then(() => (init_knowledgeHealth(), knowledgeHealth_exports));
+    knowledgeHealth = await scheduleKnowledgeHealthChecks2({
+      db,
+      config: config.knowledgeHealthCheck,
+      logger
+    });
+  }
   const prompts = new PromptLoader(promptsDir, config.bot);
   let apiKeyManager;
   const secret = config.auth?.secret || process.env.CHATTER_SECRET;
@@ -2546,6 +2680,7 @@ async function createServer(config) {
     // (sync or async) is caught per-channel so one misbehaving channel can't
     // stop the rest from cleaning up.
     stopChannels: async () => {
+      knowledgeHealth?.stop();
       await Promise.allSettled(
         started.map(async (channel) => {
           try {