@diegoaltoworks/chatter 0.61.0 → 0.62.0

package/dist/index.mjs

@@ -1,3 +1,398 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/core/buildLock.ts
+function canAcquireBuildLock(existing, holderId, now, staleMs = BUILD_LOCK_STALE_MS) {
+  if (!existing) return true;
+  if (existing.holderId === holderId) return true;
+  return now - existing.heartbeatAt >= staleMs;
+}
+function ensureBuildLockSchema(client) {
+  let ready = schemaReady.get(client);
+  if (!ready) {
+    ready = client.execute(
+      `CREATE TABLE IF NOT EXISTS chatter_build_lock (
+          lock_key TEXT PRIMARY KEY,
+          holder_id TEXT NOT NULL,
+          heartbeat_at INTEGER NOT NULL
+        )`
+    ).catch((error) => {
+      schemaReady.delete(client);
+      throw error;
+    });
+    schemaReady.set(client, ready);
+  }
+  return ready;
+}
+function createTursoBuildLock(client) {
+  return {
+    async tryAcquire(key, holderId, now, staleMs) {
+      await ensureBuildLockSchema(client);
+      const result = await client.execute({
+        sql: `INSERT INTO chatter_build_lock (lock_key, holder_id, heartbeat_at) VALUES (?, ?, ?)
+              ON CONFLICT(lock_key) DO UPDATE SET
+                holder_id = excluded.holder_id,
+                heartbeat_at = excluded.heartbeat_at
+              WHERE chatter_build_lock.holder_id = excluded.holder_id
+                 OR chatter_build_lock.heartbeat_at <= excluded.heartbeat_at - ?
+              RETURNING holder_id`,
+        args: [key, holderId, now, staleMs]
+      });
+      const row = result.rows[0];
+      return Boolean(row) && row.holder_id === holderId;
+    },
+    async release(key, holderId) {
+      await ensureBuildLockSchema(client);
+      await client.execute({
+        sql: "DELETE FROM chatter_build_lock WHERE lock_key = ? AND holder_id = ?",
+        args: [key, holderId]
+      });
+    }
+  };
+}
+var BUILD_LOCK_KEY, BUILD_LOCK_STALE_MS, schemaReady;
+var init_buildLock = __esm({
+  "src/core/buildLock.ts"() {
+    "use strict";
+    BUILD_LOCK_KEY = "knowledge_build";
+    BUILD_LOCK_STALE_MS = 10 * 6e4;
+    schemaReady = /* @__PURE__ */ new WeakMap();
+  }
+});
+
+// src/core/loaders.ts
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+function walk(dir) {
+  const items = [];
+  try {
+    for (const e of readdirSync(dir)) {
+      const p = join(dir, e);
+      const st = statSync(p);
+      if (st.isDirectory()) items.push(...walk(p));
+      else if (p.endsWith(".md")) items.push(p);
+    }
+  } catch {
+  }
+  return items;
+}
+function loadKnowledge(root = "config/knowledge") {
+  const docs = [];
+  for (const bucket of ["base", "public", "private"]) {
+    const dir = join(root, bucket);
+    for (const f of walk(dir)) {
+      docs.push({ id: f, text: readFileSync(f, "utf8"), source: f, bucket });
+    }
+  }
+  return docs;
+}
+var init_loaders = __esm({
+  "src/core/loaders.ts"() {
+    "use strict";
+  }
+});
+
+// src/core/logger.ts
+function createConsoleLogger(level = "info") {
+  const threshold = LEVEL_ORDER[level];
+  const write = (at) => (...args) => {
+    if (LEVEL_ORDER[at] < threshold) return;
+    console.error(`[${at}]`, ...args);
+  };
+  return {
+    debug: write("debug"),
+    info: write("info"),
+    warn: write("warn"),
+    error: write("error")
+  };
+}
+function resolveLogger(logger, level) {
+  return logger ?? createConsoleLogger(level);
+}
+var LEVEL_ORDER;
+var init_logger = __esm({
+  "src/core/logger.ts"() {
+    "use strict";
+    LEVEL_ORDER = { debug: 0, info: 1, warn: 2, error: 3 };
+  }
+});
+
+// src/core/retrieval.ts
+var retrieval_exports = {};
+__export(retrieval_exports, {
+  DATABASE_CONFIG_REQUIRED_MESSAGE: () => DATABASE_CONFIG_REQUIRED_MESSAGE,
+  DEFAULT_KNOWLEDGE_DIR: () => DEFAULT_KNOWLEDGE_DIR,
+  VectorStore: () => VectorStore,
+  createOpenAIEmbedder: () => createOpenAIEmbedder,
+  openLibsqlClient: () => openLibsqlClient,
+  wrapMissingLibsqlError: () => wrapMissingLibsqlError
+});
+function createOpenAIEmbedder(client) {
+  return async (input) => {
+    const res = await client.embeddings.create({ model: EMB_MODEL, input });
+    return res.data.map((d) => d.embedding);
+  };
+}
+function wrapMissingLibsqlError(cause) {
+  return new Error(
+    "Chatter's default knowledge store needs the optional peer dependency '@libsql/client', which is not installed. Install it with `bun add @libsql/client` (or npm/pnpm/yarn), or set config.retriever to use your own retrieval backend instead.",
+    { cause }
+  );
+}
+async function openLibsqlClient(database) {
+  const mod = await import("@libsql/client").catch((error) => {
+    throw wrapMissingLibsqlError(error);
+  });
+  return mod.createClient({ url: database.url, authToken: database.authToken });
+}
+function chunk(text, max = 900) {
+  const out = [];
+  let buf = "";
+  for (const line of text.replace(/\r/g, "").split("\n")) {
+    if (`${buf}
+${line}`.length > max) {
+      out.push(buf.trim());
+      buf = line;
+    } else buf += `
+${line}`;
+  }
+  if (buf.trim()) out.push(buf.trim());
+  return out;
+}
+async function sha256(input) {
+  const data = new TextEncoder().encode(input);
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var EMB_MODEL, DEFAULT_KNOWLEDGE_DIR, DATABASE_CONFIG_REQUIRED_MESSAGE, VectorStore;
+var init_retrieval = __esm({
+  "src/core/retrieval.ts"() {
+    "use strict";
+    init_buildLock();
+    init_loaders();
+    init_logger();
+    EMB_MODEL = "text-embedding-3-large";
+    DEFAULT_KNOWLEDGE_DIR = "./config/knowledge";
+    DATABASE_CONFIG_REQUIRED_MESSAGE = "config.database is required unless config.retriever is set - Chatter's default knowledge store (VectorStore) needs a Turso/libsql connection. Set config.database, or supply config.retriever to use your own retrieval backend instead.";
+    VectorStore = class _VectorStore {
+      constructor(embed, options) {
+        this.embed = embed;
+        this.db = options.databaseClient;
+        this.knowledgeDir = options.knowledgeDir || DEFAULT_KNOWLEDGE_DIR;
+        this.logger = options.logger ?? createConsoleLogger();
+        this.buildLock = options.buildLock ?? createTursoBuildLock(this.db);
+        this.instanceId = options.instanceId ?? crypto.randomUUID();
+        this.buildLockStaleMs = options.buildLockStaleMs ?? BUILD_LOCK_STALE_MS;
+      }
+      embed;
+      /**
+       * The libsql client backing this store - the same instance passed in as
+       * `databaseClient`, so callers holding it (e.g. `ServerDependencies.db`)
+       * and the store share one connection.
+       */
+      db;
+      knowledgeDir;
+      logger;
+      buildLock;
+      instanceId;
+      buildLockStaleMs;
+      /**
+       * On boot: ingest new chunks and embed only missing ones.
+       *
+       * The whole ingest runs under a single-writer lock held in the database
+       * (see [buildLock.ts](./buildLock.ts)), because the cleanup step deletes
+       * every chunk id the current `knowledgeDir` did not produce. Without the
+       * lock, a second instance booting mid-build diffs against a database the
+       * first one is still writing and deletes its chunks. An instance that
+       * cannot take the lock skips its build entirely and serves what the holder
+       * has already written, rather than racing it.
+       */
+      async build() {
+        this.logger.info("Building knowledge base...");
+        await this.db.execute(`
+      CREATE TABLE IF NOT EXISTS chunks (id TEXT PRIMARY KEY, bucket TEXT NOT NULL, source TEXT NOT NULL, text TEXT NOT NULL);
+    `);
+        await this.db.execute(`
+      CREATE TABLE IF NOT EXISTS embeddings (id TEXT PRIMARY KEY, model TEXT NOT NULL, embedding BLOB NOT NULL);
+    `);
+        await this.db.execute("CREATE INDEX IF NOT EXISTS idx_chunks_bucket ON chunks(bucket);");
+        if (!await this.renewBuildLock()) {
+          this.logger.warn(
+            "Another instance is building the knowledge base against this database - skipping this build and using what it has written. Nothing was deleted."
+          );
+          return;
+        }
+        try {
+          await this.buildUnderLock();
+        } finally {
+          await this.buildLock.release(BUILD_LOCK_KEY, this.instanceId);
+        }
+      }
+      /** Acquires the build lock, or refreshes the heartbeat if this store already holds it. */
+      renewBuildLock() {
+        return this.buildLock.tryAcquire(
+          BUILD_LOCK_KEY,
+          this.instanceId,
+          Date.now(),
+          this.buildLockStaleMs
+        );
+      }
+      /** The ingest itself. Only ever runs with the build lock held. */
+      async buildUnderLock() {
+        const docs = loadKnowledge(this.knowledgeDir);
+        this.logger.info(`Loaded ${docs.length} knowledge documents`);
+        if (docs.length === 0) {
+          const existing = await this.db.execute("SELECT COUNT(*) as count FROM chunks");
+          const existingCount = Number(existing.rows[0]?.count ?? 0);
+          if (existingCount > 0) {
+            throw new Error(
+              `Refusing to build: loaded 0 knowledge documents from "${this.knowledgeDir}", but ${existingCount} chunks already exist. Proceeding would delete all of them as stale. Check that knowledgeDir resolves to the right path.`
+            );
+          }
+          this.logger.info("No knowledge documents and no existing chunks - nothing to build");
+          return;
+        }
+        const rows = [];
+        for (const d of docs) {
+          for (const part of chunk(d.text)) {
+            const id = await sha256(`${d.bucket}|${d.source}|${part}`);
+            rows.push({ id, bucket: d.bucket, source: d.source, text: part });
+          }
+        }
+        this.logger.info(`Created ${rows.length} chunks from knowledge documents`);
+        await this.cleanupStaleChunks(rows.map((r) => r.id));
+        const UPSERT_BATCH = 500;
+        for (let i = 0; i < rows.length; i += UPSERT_BATCH) {
+          const batch = rows.slice(i, i + UPSERT_BATCH);
+          await this.db.batch(
+            batch.map((r) => ({
+              sql: `INSERT INTO chunks(id,bucket,source,text) VALUES(?,?,?,?)
+                ON CONFLICT(id) DO NOTHING`,
+              args: [r.id, r.bucket, r.source, r.text]
+            })),
+            "write"
+          );
+        }
+        const ids = rows.map((r) => r.id);
+        const missing = [];
+        for (let i = 0; i < ids.length; i += 500) {
+          const batch = ids.slice(i, i + 500);
+          const placeholders = batch.map(() => "?").join(",");
+          const res = await this.db.execute({
+            sql: `SELECT id FROM chunks WHERE id IN (${placeholders})
+              EXCEPT SELECT id FROM embeddings`,
+            args: batch
+          });
+          for (const row of res.rows) missing.push(String(row.id));
+        }
+        if (missing.length === 0) {
+          this.logger.info("No new chunks to embed - knowledge base is up to date");
+          return;
+        }
+        this.logger.info(`Embedding ${missing.length} new/updated chunks with ${EMB_MODEL}...`);
+        const textById = new Map(rows.map((r) => [r.id, r.text]));
+        const BATCH = 96;
+        for (let i = 0; i < missing.length; i += BATCH) {
+          const batchIds = missing.slice(i, i + BATCH);
+          const inputs = batchIds.map((id) => textById.get(id) || "");
+          const vectors = await this.embed(inputs);
+          await this.db.batch(
+            vectors.map((embedding, idx) => ({
+              sql: "INSERT INTO embeddings(id,model,embedding) VALUES(?,?,?)",
+              args: [batchIds[idx], EMB_MODEL, JSON.stringify(embedding)]
+            })),
+            "write"
+          );
+          if (!await this.renewBuildLock()) {
+            this.logger.warn(
+              "Lost the knowledge-base build lock to another instance mid-build - remaining chunks may be embedded by that instance instead."
+            );
+          }
+        }
+        this.logger.info(`Successfully embedded ${missing.length} new chunks`);
+      }
+      // Remove chunks from database that no longer exist in markdown files
+      async cleanupStaleChunks(currentIds) {
+        const result = await this.db.execute("SELECT id FROM chunks");
+        const dbIds = result.rows.map((row) => String(row.id));
+        const currentIdSet = new Set(currentIds);
+        const staleIds = dbIds.filter((id) => !currentIdSet.has(id));
+        if (staleIds.length === 0) {
+          return;
+        }
+        this.logger.info(`Cleaning up ${staleIds.length} stale chunks...`);
+        const BATCH_SIZE = 500;
+        for (let i = 0; i < staleIds.length; i += BATCH_SIZE) {
+          const batch = staleIds.slice(i, i + BATCH_SIZE);
+          const placeholders = batch.map(() => "?").join(",");
+          await this.db.batch(
+            [
+              { sql: `DELETE FROM chunks WHERE id IN (${placeholders})`, args: batch },
+              { sql: `DELETE FROM embeddings WHERE id IN (${placeholders})`, args: batch }
+            ],
+            "write"
+          );
+        }
+        this.logger.info(`Cleaned up ${staleIds.length} stale chunks and their embeddings`);
+      }
+      static cosine(a, b) {
+        let dot = 0;
+        let na = 0;
+        let nb = 0;
+        for (let i = 0; i < a.length; i++) {
+          dot += a[i] * b[i];
+          na += a[i] * a[i];
+          nb += b[i] * b[i];
+        }
+        return dot / (Math.sqrt(na) * Math.sqrt(nb));
+      }
+      /**
+       * Retrieve top-k across allowed buckets; compute similarity in app (simple
+       * & portable).
+       *
+       * `allowed` is a bucket-name list rather than the {@link Bucket} union: the
+       * `chunks` table constrains nothing, so a deployment that ingests its own
+       * buckets can query them (`build` only writes and prunes the three the
+       * knowledge loader walks). Names are bound as query parameters, never
+       * interpolated. An empty list retrieves nothing, and short-circuits before
+       * the embedding call.
+       */
+      async query(q, k = 6, allowed = ["base"]) {
+        if (allowed.length === 0) return [];
+        const [qv] = await this.embed([q]);
+        const placeholders = allowed.map(() => "?").join(",");
+        const res = await this.db.execute({
+          sql: `SELECT c.id, c.text, e.embedding
+            FROM chunks c
+            JOIN embeddings e ON e.id = c.id
+            WHERE c.bucket IN (${placeholders})`,
+          args: allowed
+        });
+        const scored = [];
+        for (const row of res.rows) {
+          const emb = JSON.parse(String(row.embedding));
+          const s = _VectorStore.cosine(qv, emb);
+          scored.push({ s, text: String(row.text) });
+        }
+        scored.sort((a, b) => b.s - a.s);
+        return scored.slice(0, k).map((r) => r.text);
+      }
+    };
+  }
+});
+
 // src/auth/apikeys.ts
 import { randomUUID } from "node:crypto";
 import { jwtVerify, SignJWT } from "jose";
@@ -212,7 +607,8 @@ async function answerOnce({
 async function applyTransformReply(transformReply, input, logger) {
   if (!transformReply) return input.text;
   try {
-    return await transformReply(input);
+    const result = await transformReply(input);
+    return typeof result === "string" ? result : null;
   } catch (error) {
     logger?.error(
       `transformReply threw for channel "${input.channel}"; sending the original reply`,
@@ -277,51 +673,10 @@ async function resolveBuckets({
   return cleaned.filter((bucket) => ceiling.has(bucket));
 }
 
-// src/core/loaders.ts
-import { readdirSync, readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
-function walk(dir) {
-  const items = [];
-  try {
-    for (const e of readdirSync(dir)) {
-      const p = join(dir, e);
-      const st = statSync(p);
-      if (st.isDirectory()) items.push(...walk(p));
-      else if (p.endsWith(".md")) items.push(p);
-    }
-  } catch {
-  }
-  return items;
-}
-function loadKnowledge(root = "config/knowledge") {
-  const docs = [];
-  for (const bucket of ["base", "public", "private"]) {
-    const dir = join(root, bucket);
-    for (const f of walk(dir)) {
-      docs.push({ id: f, text: readFileSync(f, "utf8"), source: f, bucket });
-    }
-  }
-  return docs;
-}
-
-// src/core/logger.ts
-var LEVEL_ORDER = { debug: 0, info: 1, warn: 2, error: 3 };
-function createConsoleLogger(level = "info") {
-  const threshold = LEVEL_ORDER[level];
-  const write = (at) => (...args) => {
-    if (LEVEL_ORDER[at] < threshold) return;
-    console.error(`[${at}]`, ...args);
-  };
-  return {
-    debug: write("debug"),
-    info: write("info"),
-    warn: write("warn"),
-    error: write("error")
-  };
-}
-function resolveLogger(logger, level) {
-  return logger ?? createConsoleLogger(level);
-}
+// src/index.ts
+init_buildLock();
+init_loaders();
+init_logger();
 
 // src/core/messages.ts
 function isClientRole(role) {
@@ -388,6 +743,7 @@ async function prepareChat({
   sender,
   rewriteQuery,
   rerankContext,
+  fallbackFn,
   logger
 }) {
   const lastUserMsg = lastUserMessage(messages);
@@ -404,21 +760,39 @@ async function prepareChat({
       logger?.error("rewriteQuery threw; falling back to the original query", error);
     }
   }
-  let ctx = await store.query(query, topK, buckets ?? defaultBuckets(mode));
+  const resolvedBuckets = buckets ?? defaultBuckets(mode);
+  const retrievedChunks = await store.query(query, topK, resolvedBuckets);
+  let ctx = retrievedChunks;
   if (rerankContext) {
     try {
-      const reranked = await rerankContext({ query, chunks: ctx });
+      const reranked = await rerankContext({ query, chunks: [...ctx] });
       if (Array.isArray(reranked) && reranked.every((c) => typeof c === "string")) ctx = reranked;
     } catch (error) {
       logger?.error("rerankContext threw; falling back to the original chunks", error);
     }
   }
+  let fallback;
+  if (ctx.length === 0 && fallbackFn) {
+    try {
+      const guidance = await fallbackFn({
+        query,
+        mode,
+        buckets: resolvedBuckets,
+        sender,
+        retrievedChunks
+      });
+      if (typeof guidance === "string" && guidance.trim()) fallback = guidance.trim();
+    } catch (error) {
+      logger?.error("fallbackFn threw; proceeding without fallback guidance", error);
+    }
+  }
   const persona = personaLayer?.trim() || (mode === "private" ? prompts.privatePersona : prompts.publicPersona);
   const hint = channelHint?.trim();
   const system = [
     prompts.baseSystemRules,
     persona,
     ...hint ? [hint] : [],
+    ...fallback ? [fallback] : [],
     `${label}:
 ${ctx.join("\n\n")}`
   ].join("\n\n");
@@ -428,6 +802,7 @@ ${ctx.join("\n\n")}`
 // src/core/prompts.ts
 import { readFileSync as readFileSync2 } from "node:fs";
 import { join as join2 } from "node:path";
+var DEFAULT_PROMPTS_DIR = "./config/prompts";
 var PromptLoader = class {
   constructor(promptsDir, bot) {
     this.promptsDir = promptsDir;
@@ -458,196 +833,32 @@ var PromptLoader = class {
   }
 };
 
-// src/core/retrieval.ts
-import { createClient } from "@libsql/client";
-var EMB_MODEL = "text-embedding-3-large";
-function chunk(text, max = 900) {
-  const out = [];
-  let buf = "";
-  for (const line of text.replace(/\r/g, "").split("\n")) {
-    if (`${buf}
-${line}`.length > max) {
-      out.push(buf.trim());
-      buf = line;
-    } else buf += `
-${line}`;
-  }
-  if (buf.trim()) out.push(buf.trim());
-  return out;
-}
-async function sha256(input) {
-  const data = new TextEncoder().encode(input);
-  const hash = await crypto.subtle.digest("SHA-256", data);
-  return Array.from(new Uint8Array(hash)).map((b) => b.toString(16).padStart(2, "0")).join("");
-}
-var VectorStore = class _VectorStore {
-  constructor(client, options) {
-    this.client = client;
-    this.db = options.databaseClient ? options.databaseClient : createClient({
-      url: options.databaseUrl,
-      authToken: options.databaseAuthToken
-    });
-    this.knowledgeDir = options.knowledgeDir || "./config/knowledge";
-    this.logger = options.logger ?? createConsoleLogger();
-  }
-  client;
-  /**
-   * The libsql client backing this store. When a client was injected this is
-   * that same instance, so callers holding it (e.g. `ServerDependencies.db`)
-   * and the store share one connection.
-   */
-  db;
-  knowledgeDir;
-  logger;
-  // On boot: ingest new chunks and embed only missing ones.
-  async build() {
-    this.logger.info("\u{1F504} Building knowledge base...");
-    await this.db.execute(`
-      CREATE TABLE IF NOT EXISTS chunks (id TEXT PRIMARY KEY, bucket TEXT NOT NULL, source TEXT NOT NULL, text TEXT NOT NULL);
-    `);
-    await this.db.execute(`
-      CREATE TABLE IF NOT EXISTS embeddings (id TEXT PRIMARY KEY, model TEXT NOT NULL, embedding BLOB NOT NULL);
-    `);
-    await this.db.execute("CREATE INDEX IF NOT EXISTS idx_chunks_bucket ON chunks(bucket);");
-    const docs = loadKnowledge(this.knowledgeDir);
-    this.logger.info(`\u{1F4DA} Loaded ${docs.length} knowledge documents`);
-    const rows = [];
-    for (const d of docs) {
-      for (const part of chunk(d.text)) {
-        const id = await sha256(`${d.bucket}|${d.source}|${part}`);
-        rows.push({ id, bucket: d.bucket, source: d.source, text: part });
-      }
-    }
-    this.logger.info(`\u{1F4E6} Created ${rows.length} chunks from knowledge documents`);
-    await this.cleanupStaleChunks(rows.map((r) => r.id));
-    const UPSERT_BATCH = 500;
-    for (let i = 0; i < rows.length; i += UPSERT_BATCH) {
-      const batch = rows.slice(i, i + UPSERT_BATCH);
-      await this.db.batch(
-        batch.map((r) => ({
-          sql: `INSERT INTO chunks(id,bucket,source,text) VALUES(?,?,?,?)
-                ON CONFLICT(id) DO NOTHING`,
-          args: [r.id, r.bucket, r.source, r.text]
-        })),
-        "write"
-      );
-    }
-    const ids = rows.map((r) => r.id);
-    const missing = [];
-    for (let i = 0; i < ids.length; i += 500) {
-      const batch = ids.slice(i, i + 500);
-      const placeholders = batch.map(() => "?").join(",");
-      const res = await this.db.execute({
-        sql: `SELECT id FROM chunks WHERE id IN (${placeholders})
-              EXCEPT SELECT id FROM embeddings`,
-        args: batch
-      });
-      for (const row of res.rows) missing.push(String(row.id));
-    }
-    if (missing.length === 0) {
-      this.logger.info("\u2705 No new chunks to embed - knowledge base is up to date");
-      return;
-    }
-    this.logger.info(`\u{1F52E} Embedding ${missing.length} new/updated chunks with ${EMB_MODEL}...`);
-    const textById = new Map(rows.map((r) => [r.id, r.text]));
-    const BATCH = 96;
-    for (let i = 0; i < missing.length; i += BATCH) {
-      const batchIds = missing.slice(i, i + BATCH);
-      const inputs = batchIds.map((id) => textById.get(id) || "");
-      const emb = await this.client.embeddings.create({ model: EMB_MODEL, input: inputs });
-      await this.db.batch(
-        emb.data.map((d, idx) => ({
-          sql: "INSERT INTO embeddings(id,model,embedding) VALUES(?,?,?)",
-          args: [batchIds[idx], EMB_MODEL, JSON.stringify(d.embedding)]
-        })),
-        "write"
-      );
-    }
-    this.logger.info(`\u2705 Successfully embedded ${missing.length} new chunks`);
-  }
-  // Remove chunks from database that no longer exist in markdown files
-  async cleanupStaleChunks(currentIds) {
-    const result = await this.db.execute("SELECT id FROM chunks");
-    const dbIds = result.rows.map((row) => String(row.id));
-    const currentIdSet = new Set(currentIds);
-    const staleIds = dbIds.filter((id) => !currentIdSet.has(id));
-    if (staleIds.length === 0) {
-      return;
-    }
-    this.logger.info(`\u{1F9F9} Cleaning up ${staleIds.length} stale chunks...`);
-    const BATCH_SIZE = 500;
-    for (let i = 0; i < staleIds.length; i += BATCH_SIZE) {
-      const batch = staleIds.slice(i, i + BATCH_SIZE);
-      const placeholders = batch.map(() => "?").join(",");
-      await this.db.execute({
-        sql: `DELETE FROM chunks WHERE id IN (${placeholders})`,
-        args: batch
-      });
-    }
-    this.logger.info(`\u2713 Cleaned up ${staleIds.length} stale chunks and their embeddings`);
-  }
-  static cosine(a, b) {
-    let dot = 0;
-    let na = 0;
-    let nb = 0;
-    for (let i = 0; i < a.length; i++) {
-      dot += a[i] * b[i];
-      na += a[i] * a[i];
-      nb += b[i] * b[i];
-    }
-    return dot / (Math.sqrt(na) * Math.sqrt(nb));
-  }
-  /**
-   * Retrieve top-k across allowed buckets; compute similarity in app (simple
-   * & portable).
-   *
-   * `allowed` is a bucket-name list rather than the {@link Bucket} union: the
-   * `chunks` table constrains nothing, so a deployment that ingests its own
-   * buckets can query them (`build` only writes and prunes the three the
-   * knowledge loader walks). Names are bound as query parameters, never
-   * interpolated. An empty list retrieves nothing, and short-circuits before
-   * the embedding call.
-   */
-  async query(q, k = 6, allowed = ["base"]) {
-    if (allowed.length === 0) return [];
-    const qv = (await this.client.embeddings.create({ model: EMB_MODEL, input: [q] })).data[0].embedding;
-    const placeholders = allowed.map(() => "?").join(",");
-    const res = await this.db.execute({
-      sql: `SELECT c.id, c.text, e.embedding
-            FROM chunks c
-            JOIN embeddings e ON e.id = c.id
-            WHERE c.bucket IN (${placeholders})`,
-      args: allowed
-    });
-    const scored = [];
-    for (const row of res.rows) {
-      const emb = JSON.parse(String(row.embedding));
-      const s = _VectorStore.cosine(qv, emb);
-      scored.push({ s, text: String(row.text) });
-    }
-    scored.sort((a, b) => b.s - a.s);
-    return scored.slice(0, k).map((r) => r.text);
-  }
-};
+// src/index.ts
+init_retrieval();
 
 // src/core/session.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
+var SESSION_KEY_PREFIX = "session_";
+var DEFAULT_SESSION_MAX_REQUESTS = 20;
+var DEFAULT_SESSION_TTL_SECONDS = 3600;
+var SESSION_SWEEP_INTERVAL_MS = 5 * 60 * 1e3;
 var sessions = /* @__PURE__ */ new Map();
-var sessionSweeper = setInterval(
-  () => {
-    const now = Date.now();
-    for (const [key, data] of Array.from(sessions.entries())) {
-      if (now > data.expiresAt) {
-        sessions.delete(key);
-      }
+var sessionSweeper = setInterval(() => {
+  const now = Date.now();
+  for (const [key, data] of Array.from(sessions.entries())) {
+    if (now > data.expiresAt) {
+      sessions.delete(key);
     }
-  },
-  5 * 60 * 1e3
-);
+  }
+}, SESSION_SWEEP_INTERVAL_MS);
 sessionSweeper.unref?.();
 function createSession(options = {}) {
-  const { maxRequests = 20, ttl = 3600, metadata } = options;
-  const key = `session_${randomUUID2()}`;
+  const {
+    maxRequests = DEFAULT_SESSION_MAX_REQUESTS,
+    ttl = DEFAULT_SESSION_TTL_SECONDS,
+    metadata
+  } = options;
+  const key = `${SESSION_KEY_PREFIX}${randomUUID2()}`;
   const now = Date.now();
   const session = {
     key,
@@ -683,6 +894,8 @@ function getActiveSessions() {
 
 // src/mcp-server.ts
 import OpenAI from "openai";
+init_logger();
+init_retrieval();
 
 // src/mcp-server/conversation-id.ts
 function generateConversationId() {
@@ -709,28 +922,38 @@ function calculateCost(usage, rates) {
 }
 
 // src/mcp-server/logger.ts
+init_logger();
 var MCPLogger = class {
   enableConsole;
   callback;
   logger;
-  constructor(enableConsole = true, callback, logger) {
+  logContent;
+  constructor(enableConsole = true, callback, logger, logContent = false) {
     this.enableConsole = enableConsole;
     this.callback = callback;
     this.logger = logger ?? createConsoleLogger();
+    this.logContent = logContent;
   }
   /**
    * Log a chat interaction
    */
   async logChatInteraction(toolName, conversationId, conversationMessages, ragContext, response, duration, cost) {
     const lastUserMsg = lastUserMessage(conversationMessages);
+    const content = {
+      userMessage: scrubOutput(lastUserMsg?.content || ""),
+      conversationHistory: conversationMessages.map((msg) => ({
+        ...msg,
+        content: scrubOutput(msg.content)
+      })),
+      ragContext: ragContext.map(scrubOutput),
+      response: scrubOutput(response)
+    };
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
     const logEvent = {
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      timestamp,
       toolName,
       conversationId,
-      userMessage: lastUserMsg?.content || "",
-      conversationHistory: conversationMessages,
-      ragContext,
-      response,
+      ...content,
       duration,
       cost
     };
@@ -738,9 +961,27 @@ var MCPLogger = class {
       this.logger.info(
         JSON.stringify({
           event: "mcp_chat",
-          ...logEvent
+          timestamp,
+          toolName,
+          conversationId,
+          messageCount: conversationMessages.length,
+          ragContextCount: ragContext.length,
+          responseChars: response.length,
+          duration,
+          cost
         })
       );
+      if (this.logContent) {
+        this.logger.debug(
+          JSON.stringify({
+            event: "mcp_chat_content",
+            timestamp,
+            toolName,
+            conversationId,
+            ...content
+          })
+        );
+      }
     }
     if (this.callback) {
       try {
@@ -751,11 +992,12 @@ var MCPLogger = class {
     }
   }
 };
-function createLogger(enableConsole = true, callback, logger) {
-  return new MCPLogger(enableConsole, callback, logger);
+function createLogger(enableConsole = true, callback, logger, logContent = false) {
+  return new MCPLogger(enableConsole, callback, logger, logContent);
 }
 
 // src/mcp-server/rate-limiter.ts
+var DEFAULT_WINDOW_MS = 6e4;
 var RateLimiter = class {
   requestMap;
   limit;
@@ -764,9 +1006,9 @@ var RateLimiter = class {
    * Create a new rate limiter
    *
    * @param limit - Maximum requests allowed in the time window
-   * @param windowMs - Time window in milliseconds (default: 60000 = 1 minute)
+   * @param windowMs - Time window in milliseconds (default: `DEFAULT_WINDOW_MS`)
    */
-  constructor(limit, windowMs = 6e4) {
+  constructor(limit, windowMs = DEFAULT_WINDOW_MS) {
     this.requestMap = /* @__PURE__ */ new Map();
     this.limit = limit;
     this.windowMs = windowMs;
@@ -830,7 +1072,7 @@ var RateLimiter = class {
     return Math.max(0, timeUntilReset);
   }
 };
-function createRateLimiter(limit, windowMs = 6e4) {
+function createMcpRateLimiter(limit, windowMs = DEFAULT_WINDOW_MS) {
   return limit ? new RateLimiter(limit, windowMs) : null;
 }
 
@@ -880,11 +1122,15 @@ async function createMCPServer(config) {
   const log = resolveLogger(config.logger, config.logLevel);
   log.info(`\u{1F680} Starting ${config.bot.name} MCP Server...`);
   const [McpServer, z] = await Promise.all([loadMcpSdk(), loadZod()]);
-  const knowledgeDir = config.knowledgeDir || "./config/knowledge";
-  const promptsDir = config.promptsDir || "./config/prompts";
+  const promptsDir = config.promptsDir || DEFAULT_PROMPTS_DIR;
   const transportMode = config.transport || "stdio";
-  const rateLimiter = createRateLimiter(config.toolRateLimit);
-  const logger = createLogger(config.logging?.console !== false, config.logging?.onChat, log);
+  const rateLimiter = createMcpRateLimiter(config.toolRateLimit);
+  const logger = createLogger(
+    config.logging?.console !== false,
+    config.logging?.onChat,
+    log,
+    config.logging?.content === true
+  );
   const publicToolConfig = {
     enabled: config.tools?.public?.enabled !== false,
     name: config.tools?.public?.name || "chat_public",
@@ -899,13 +1145,22 @@ async function createMCPServer(config) {
     apiKey: config.openai.apiKey
   });
   const model = config.openai.model || DEFAULT_MODEL;
-  const store = new VectorStore(client, {
-    databaseUrl: config.database.url,
-    databaseAuthToken: config.database.authToken,
-    knowledgeDir,
-    logger: log
-  });
-  await store.build();
+  let store;
+  if (config.retriever) {
+    store = config.retriever;
+  } else {
+    if (!config.database) {
+      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);
+    store = new VectorStore2(createOpenAIEmbedder2(client), {
+      databaseClient: db,
+      knowledgeDir: config.knowledgeDir || DEFAULT_KNOWLEDGE_DIR2,
+      logger: log
+    });
+  }
+  await store.build?.();
   log.info("\u2705 Knowledge base ready");
   const prompts = new PromptLoader(promptsDir, config.bot);
   const server = new McpServer({
@@ -954,6 +1209,7 @@ async function createMCPServer(config) {
           buckets,
           rewriteQuery: config.rewriteQuery,
           rerankContext: config.rerankContext,
+          fallbackFn: config.fallbackFn,
           logger: log
         });
         const result = await answerOnce({
@@ -1043,6 +1299,7 @@ async function createMCPServer(config) {
           buckets,
           rewriteQuery: config.rewriteQuery,
           rerankContext: config.rerankContext,
+          fallbackFn: config.fallbackFn,
           logger: log
         });
         const result = await answerOnce({
@@ -1104,13 +1361,17 @@ async function createMCPServer(config) {
   return server;
 }
 
+// src/middleware/apiKey.ts
+var API_KEY_HEADER = "x-api-key";
+var API_KEY_PREVIEW_LENGTH = 20;
+
 // src/middleware/auth.ts
 function createAuthMiddleware(deps) {
   const { apiKeyManager, logger } = deps;
   return async function requirePublicKey(c, next) {
-    const hdr = c.req.header("x-api-key");
-    if (hdr?.startsWith("session_")) {
-      logger.debug(`[Auth] Session key allowed: ${hdr.slice(0, 20)}...`);
+    const hdr = c.req.header(API_KEY_HEADER);
+    if (hdr?.startsWith(SESSION_KEY_PREFIX)) {
+      logger.debug(`[Auth] Session key allowed: ${hdr.slice(0, API_KEY_PREVIEW_LENGTH)}...`);
       await next();
       return;
     }
@@ -1120,7 +1381,7 @@ function createAuthMiddleware(deps) {
     }
     if (!hdr) {
       logger.debug("[Auth] No API key provided");
-      return c.json({ error: "Unauthorized - Missing x-api-key header" }, 401);
+      return c.json({ error: `Unauthorized - Missing ${API_KEY_HEADER} header` }, 401);
     }
     try {
       const result = await apiKeyManager.verify(hdr);
@@ -1134,7 +1395,7 @@ function createAuthMiddleware(deps) {
     } catch (error) {
       logger.warn(`[Auth] JWT verification error: ${error}`);
     }
-    logger.debug(`[Auth] Invalid API key: ${hdr?.slice(0, 20) || "none"}`);
+    logger.debug(`[Auth] Invalid API key: ${hdr?.slice(0, API_KEY_PREVIEW_LENGTH) || "none"}`);
     return c.json({ error: "Unauthorized" }, 401);
   };
 }
@@ -1150,7 +1411,7 @@ function chatBodyLimit(maxSize = DEFAULT_MAX_REQUEST_BYTES, toError = (message)
 }
 
 // src/middleware/cors.ts
-var ALLOWED_HEADERS = "content-type, x-api-key, authorization, x-conversation-id";
+var ALLOWED_HEADERS = `content-type, ${API_KEY_HEADER}, authorization, x-conversation-id`;
 var ALLOWED_METHODS = "POST, GET, OPTIONS";
 var EXPOSED_HEADERS = "x-conversation-id";
 var cors = (allowedOrigins) => async (c, next) => {
@@ -1266,7 +1527,7 @@ function createWindowBucketLimiter(windowMs, now = Date.now) {
 }
 
 // src/middleware/ratelimit.ts
-function createRateLimiter2(config) {
+function createRateLimiter(config) {
   const limiter = createWindowBucketLimiter(6e4);
   const publicLimit = config.rateLimit?.public || 60;
   const privateLimit = config.rateLimit?.private || 120;
@@ -1277,7 +1538,7 @@ function createRateLimiter2(config) {
     // Demo keys get 10x stricter rate limits
     limitPublic() {
       return async (c, next) => {
-        const apiKey = c.req.header("x-api-key");
+        const apiKey = c.req.header(API_KEY_HEADER);
         const isDemoKey = apiKey ? demoApiKeys.includes(apiKey) : false;
         const key = `pub:${clientRateLimitKey(c, trustProxy)}`;
         const limit = isDemoKey ? Math.floor(publicLimit / 10) : publicLimit;
@@ -1304,6 +1565,9 @@ function createRateLimiter2(config) {
   };
 }
 
+// src/middleware/referrer.ts
+init_logger();
+
 // src/middleware/originMatch.ts
 function matchesAllowedOrigin(origin, referer, allowedOrigins) {
   return allowedOrigins.some((allowed) => {
@@ -1334,14 +1598,14 @@ function matchesAllowedOriginOrLocalhost(origin, referer, allowedOrigins) {
 // src/middleware/referrer.ts
 function requireReferrer(allowedOrigins, demoApiKeys = [], logger = createConsoleLogger()) {
   return async (c, next) => {
-    const apiKey = c.req.header("x-api-key");
+    const apiKey = c.req.header(API_KEY_HEADER);
     const isDemoKey = apiKey ? demoApiKeys.includes(apiKey) : false;
-    const isSessionKey = apiKey?.startsWith("session_");
+    const isSessionKey = apiKey?.startsWith(SESSION_KEY_PREFIX);
     if (isDemoKey || isSessionKey) {
       const referer = c.req.header("referer");
       const origin = c.req.header("origin");
       logger.debug(
-        `[Referrer] Checking ${isSessionKey ? "session" : "demo"} key: ${apiKey?.slice(0, 20)}...`
+        `[Referrer] Checking ${isSessionKey ? "session" : "demo"} key: ${apiKey?.slice(0, API_KEY_PREVIEW_LENGTH)}...`
       );
       logger.debug(`[Referrer] Origin: ${origin || "none"}, Referer: ${referer || "none"}`);
       const isAllowed = matchesAllowedOrigin(origin, referer, allowedOrigins);
@@ -1384,11 +1648,12 @@ function securityHeaders(config) {
 }
 
 // src/middleware/session.ts
+init_logger();
 function validateSessionKey(logger = createConsoleLogger()) {
   return async (c, next) => {
-    const apiKey = c.req.header("x-api-key");
-    if (apiKey?.startsWith("session_")) {
-      logger.debug(`[Session] Validating key: ${apiKey.slice(0, 20)}...`);
+    const apiKey = c.req.header(API_KEY_HEADER);
+    if (apiKey?.startsWith(SESSION_KEY_PREFIX)) {
+      logger.debug(`[Session] Validating key: ${apiKey.slice(0, API_KEY_PREVIEW_LENGTH)}...`);
       const info = getSessionInfo(apiKey);
       if (info) {
         logger.debug(
@@ -1469,6 +1734,8 @@ function limitDemo(trustProxy) {
     await next();
   };
 }
+var DEMO_SESSION_MAX_REQUESTS = 20;
+var DEMO_SESSION_TTL_SECONDS = 3600;
 function demoRoutes(deps) {
   const { client, store, config, prompts, logger } = deps;
   const app = new Hono();
@@ -1481,18 +1748,17 @@ function demoRoutes(deps) {
     limitSessionCreation(trustProxy),
     (c) => {
       const session = createSession({
-        maxRequests: 20,
-        ttl: 3600
-        // 1 hour
+        maxRequests: DEMO_SESSION_MAX_REQUESTS,
+        ttl: DEMO_SESSION_TTL_SECONDS
       });
       logger.debug(
-        `[Demo] Created session: ${session.key.slice(0, 20)}... (${session.maxRequests} requests, ${3600}s TTL)`
+        `[Demo] Created session: ${session.key.slice(0, API_KEY_PREVIEW_LENGTH)}... (${session.maxRequests} requests, ${DEMO_SESSION_TTL_SECONDS}s TTL)`
       );
       return c.json({
         key: session.key,
-        expiresIn: 3600,
+        expiresIn: DEMO_SESSION_TTL_SECONDS,
         maxRequests: session.maxRequests,
-        message: "Use this temporary key in the x-api-key header"
+        message: `Use this temporary key in the ${API_KEY_HEADER} header`
       });
     }
   );
@@ -1526,6 +1792,7 @@ function demoRoutes(deps) {
           buckets,
           rewriteQuery: config.rewriteQuery,
           rerankContext: config.rerankContext,
+          fallbackFn: config.fallbackFn,
           logger
         });
         const model = config.openai.model || DEFAULT_MODEL;
@@ -1606,7 +1873,7 @@ function oversizedBodyError(message) {
 function openaiRoutes(deps) {
   const { client, store, config, prompts, apiKeyManager, logger } = deps;
   const app = new Hono2();
-  const { limitPublic, limitPrivate } = createRateLimiter2(config);
+  const { limitPublic, limitPrivate } = createRateLimiter(config);
   const requirePrivateJWT = createJWTMiddleware(config);
   const enablePublic = config.features?.enablePublicChat !== false;
   const enablePrivate = config.features?.enablePrivateChat !== false;
@@ -1616,9 +1883,13 @@ function openaiRoutes(deps) {
       return errorJson(c, 401, "API key authentication is not configured on this server");
     }
     const bearer = c.req.header("authorization") ?? "";
-    const key = bearer.startsWith("Bearer ") ? bearer.slice("Bearer ".length) : c.req.header("x-api-key");
+    const key = bearer.startsWith("Bearer ") ? bearer.slice("Bearer ".length) : c.req.header(API_KEY_HEADER);
     if (!key) {
-      return errorJson(c, 401, "Missing API key (Authorization: Bearer or x-api-key header)");
+      return errorJson(
+        c,
+        401,
+        `Missing API key (Authorization: Bearer or ${API_KEY_HEADER} header)`
+      );
     }
     try {
       const result = await apiKeyManager.verify(key);
@@ -1658,6 +1929,7 @@ function openaiRoutes(deps) {
         sender,
         rewriteQuery: config.rewriteQuery,
         rerankContext: config.rerankContext,
+        fallbackFn: config.fallbackFn,
         logger
       }));
     } catch {
@@ -1753,7 +2025,7 @@ function privateRoutes(deps) {
   const { client, store, config, prompts, logger } = deps;
   const app = new Hono3();
   const requirePrivateJWT = createJWTMiddleware(config);
-  const { limitPrivate } = createRateLimiter2(config);
+  const { limitPrivate } = createRateLimiter(config);
   app.use("/api/private/*", chatBodyLimit(config.server?.maxRequestBytes));
   app.use("/api/private/*", requirePrivateJWT);
   app.use("/api/private/*", limitPrivate());
@@ -1781,6 +2053,7 @@ function privateRoutes(deps) {
         sender,
         rewriteQuery: config.rewriteQuery,
         rerankContext: config.rerankContext,
+        fallbackFn: config.fallbackFn,
         logger
       }));
     } catch {
@@ -1838,7 +2111,7 @@ function publicRoutes(deps) {
   const { client, store, config, prompts, logger } = deps;
   const app = new Hono4();
   const requirePublicKey = createAuthMiddleware(deps);
-  const { limitPublic } = createRateLimiter2(config);
+  const { limitPublic } = createRateLimiter(config);
   const referrerOrigins = config.server?.allowedOrigins?.length ? config.server.allowedOrigins.filter((o) => o !== "*") : [config.bot.publicUrl, "http://localhost:8181", "http://127.0.0.1:8181"];
   app.use("/api/public/*", chatBodyLimit(config.server?.maxRequestBytes));
   app.use("/api/public/*", validateSessionKey(logger));
@@ -1866,6 +2139,7 @@ function publicRoutes(deps) {
         buckets,
         rewriteQuery: config.rewriteQuery,
         rerankContext: config.rerankContext,
+        fallbackFn: config.fallbackFn,
         logger
       }));
     } catch {
@@ -1903,11 +2177,11 @@ function publicRoutes(deps) {
 
 // src/server.ts
 import { relative } from "node:path";
-import { createClient as createClient2 } from "@libsql/client";
 import { Hono as Hono5 } from "hono";
 import OpenAI2 from "openai";
 
 // src/channels/senders.ts
+init_logger();
 function createSenderRegistry(logger = createConsoleLogger()) {
   const senders = /* @__PURE__ */ new Map();
   return {
@@ -1970,6 +2244,10 @@ function createSenderRegistry(logger = createConsoleLogger()) {
   };
 }
 
+// src/server.ts
+init_logger();
+init_retrieval();
+
 // src/core/serve-static.ts
 var STATIC_ADAPTERS = {
   bun: "hono/bun",
@@ -2030,8 +2308,7 @@ function resolveStatic(configStaticDir) {
 async function createServer(config) {
   const logger = resolveLogger(config.logger, config.logLevel);
   logger.info(`\u{1F680} Starting ${config.bot.name}...`);
-  const knowledgeDir = config.knowledgeDir || "./config/knowledge";
-  const promptsDir = config.promptsDir || "./config/prompts";
+  const promptsDir = config.promptsDir || DEFAULT_PROMPTS_DIR;
   const publicDir = config.publicDir || "./public";
   const enablePublic = config.features?.enablePublicChat !== false;
   const enablePrivate = config.features?.enablePrivateChat !== false;
@@ -2042,16 +2319,26 @@ async function createServer(config) {
   const client = new OpenAI2({
     apiKey: config.openai.apiKey
   });
-  const db = createClient2({
-    url: config.database.url,
-    authToken: config.database.authToken
-  });
-  const store = new VectorStore(client, {
-    databaseClient: db,
-    knowledgeDir,
-    logger
-  });
-  await store.build();
+  let db;
+  if (config.database) {
+    const { openLibsqlClient: openLibsqlClient2 } = await Promise.resolve().then(() => (init_retrieval(), retrieval_exports));
+    db = await openLibsqlClient2(config.database);
+  }
+  let store;
+  if (config.retriever) {
+    store = config.retriever;
+  } else {
+    if (!db) {
+      throw new Error(DATABASE_CONFIG_REQUIRED_MESSAGE);
+    }
+    const { DEFAULT_KNOWLEDGE_DIR: DEFAULT_KNOWLEDGE_DIR2, VectorStore: VectorStore2, createOpenAIEmbedder: createOpenAIEmbedder2 } = await Promise.resolve().then(() => (init_retrieval(), retrieval_exports));
+    store = new VectorStore2(createOpenAIEmbedder2(client), {
+      databaseClient: db,
+      knowledgeDir: config.knowledgeDir || DEFAULT_KNOWLEDGE_DIR2,
+      logger
+    });
+  }
+  await store.build?.();
   logger.info("\u2705 Knowledge base ready");
   const prompts = new PromptLoader(promptsDir, config.bot);
   let apiKeyManager;
@@ -2139,6 +2426,9 @@ async function createServer(config) {
   const deps = {
     client,
     store,
+    // See ServerDependencies.db's doc comment: undefined here (cast to
+    // satisfy the still-required type) exactly when config.database was
+    // never set - i.e. a config.retriever host with nothing else needing db.
     db,
     config,
     prompts,
@@ -2194,13 +2484,16 @@ async function createServer(config) {
 }
 
 // src/shortener.ts
-var DEFAULT_TIMEOUT_MS = 5e3;
+var SHORTENER_TIMEOUT_MS = 5e3;
 function createShortener(config, fetchImpl = fetch) {
   const apiUrl = config.apiUrl.replace(/\/+$/, "");
   return {
     async shorten(url) {
       const controller = new AbortController();
-      const timeout = setTimeout(() => controller.abort(), config.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+      const timeout = setTimeout(
+        () => controller.abort(),
+        config.timeoutMs ?? SHORTENER_TIMEOUT_MS
+      );
       try {
         const response = await fetchImpl(`${apiUrl}/api/v2/links`, {
           method: "POST",
@@ -2228,12 +2521,17 @@ function createShortener(config, fetchImpl = fetch) {
 }
 export {
   ApiKeyManager,
+  BUILD_LOCK_KEY,
+  BUILD_LOCK_STALE_MS,
+  DEFAULT_KNOWLEDGE_DIR,
   DEFAULT_MODEL,
+  DEFAULT_PROMPTS_DIR,
   PromptLoader,
   VectorStore,
   answerOnce,
   answerStream,
   applyTransformReply,
+  canAcquireBuildLock,
   chatBodyLimit,
   completeOnce,
   completeStream,
@@ -2242,12 +2540,14 @@ export {
   createConsoleLogger,
   createJWTMiddleware,
   createMCPServer,
-  createRateLimiter2 as createRateLimiter,
+  createOpenAIEmbedder,
+  createRateLimiter,
   createReferrerCheck,
   createServer,
   createSession,
   createSessionMiddleware,
   createShortener,
+  createTursoBuildLock,
   defaultBuckets,
   demoRoutes,
   detectLeakage,