@diegoaltoworks/chatter 0.61.0 → 0.63.0

package/dist/server.js

@@ -5,6 +5,14 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 });
@@ -27,6 +35,382 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// 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/buildLock.ts
+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
+function walk(dir) {
+  const items = [];
+  try {
+    for (const e of (0, import_node_fs2.readdirSync)(dir)) {
+      const p = (0, import_node_path2.join)(dir, e);
+      const st = (0, import_node_fs2.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 = (0, import_node_path2.join)(root, bucket);
+    for (const f of walk(dir)) {
+      docs.push({ id: f, text: (0, import_node_fs2.readFileSync)(f, "utf8"), source: f, bucket });
+    }
+  }
+  return docs;
+}
+var import_node_fs2, import_node_path2;
+var init_loaders = __esm({
+  "src/core/loaders.ts"() {
+    "use strict";
+    import_node_fs2 = require("node:fs");
+    import_node_path2 = require("node:path");
+  }
+});
+
+// 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/server.ts
 var server_exports = {};
 __export(server_exports, {
@@ -34,7 +418,6 @@ __export(server_exports, {
 });
 module.exports = __toCommonJS(server_exports);
 var import_node_path4 = require("node:path");
-var import_client2 = require("@libsql/client");
 var import_hono5 = require("hono");
 var import_openai = __toESM(require("openai"));
 
@@ -252,7 +635,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`,
@@ -382,6 +766,7 @@ async function prepareChat({
   sender,
   rewriteQuery,
   rerankContext,
+  fallbackFn,
   logger
 }) {
   const lastUserMsg = lastUserMessage(messages);
@@ -398,47 +783,47 @@ 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");
   return { system, messages, context: ctx };
 }
 
-// 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/channels/senders.ts
+init_logger();
 function createSenderRegistry(logger = createConsoleLogger()) {
   const senders = /* @__PURE__ */ new Map();
   return {
@@ -501,9 +886,13 @@ function createSenderRegistry(logger = createConsoleLogger()) {
   };
 }
 
+// src/server.ts
+init_logger();
+
 // src/core/prompts.ts
 var import_node_fs = require("node:fs");
 var import_node_path = require("node:path");
+var DEFAULT_PROMPTS_DIR = "./config/prompts";
 var PromptLoader = class {
   constructor(promptsDir, bot) {
     this.promptsDir = promptsDir;
@@ -534,206 +923,8 @@ var PromptLoader = class {
   }
 };
 
-// src/core/retrieval.ts
-var import_client = require("@libsql/client");
-
-// src/core/loaders.ts
-var import_node_fs2 = require("node:fs");
-var import_node_path2 = require("node:path");
-function walk(dir) {
-  const items = [];
-  try {
-    for (const e of (0, import_node_fs2.readdirSync)(dir)) {
-      const p = (0, import_node_path2.join)(dir, e);
-      const st = (0, import_node_fs2.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 = (0, import_node_path2.join)(root, bucket);
-    for (const f of walk(dir)) {
-      docs.push({ id: f, text: (0, import_node_fs2.readFileSync)(f, "utf8"), source: f, bucket });
-    }
-  }
-  return docs;
-}
-
-// src/core/retrieval.ts
-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 : (0, import_client.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/server.ts
+init_retrieval();
 
 // src/core/serve-static.ts
 var STATIC_ADAPTERS = {
@@ -792,8 +983,12 @@ function resolveStatic(configStaticDir) {
   return { staticDir: null };
 }
 
+// src/middleware/apiKey.ts
+var API_KEY_HEADER = "x-api-key";
+var API_KEY_PREVIEW_LENGTH = 20;
+
 // 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) => {
@@ -857,22 +1052,27 @@ var import_streaming = require("hono/streaming");
 
 // src/core/session.ts
 var import_node_crypto2 = require("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_${(0, import_node_crypto2.randomUUID)()}`;
+  const {
+    maxRequests = DEFAULT_SESSION_MAX_REQUESTS,
+    ttl = DEFAULT_SESSION_TTL_SECONDS,
+    metadata
+  } = options;
+  const key = `${SESSION_KEY_PREFIX}${(0, import_node_crypto2.randomUUID)()}`;
   const now = Date.now();
   const session = {
     key,
@@ -1035,6 +1235,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 import_hono.Hono();
@@ -1047,18 +1249,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`
       });
     }
   );
@@ -1092,6 +1293,7 @@ function demoRoutes(deps) {
           buckets,
           rewriteQuery: config.rewriteQuery,
           rerankContext: config.rerankContext,
+          fallbackFn: config.fallbackFn,
           logger
         });
         const model = config.openai.model || DEFAULT_MODEL;
@@ -1194,7 +1396,7 @@ function createRateLimiter(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;
@@ -1263,9 +1465,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);
@@ -1305,6 +1511,7 @@ function openaiRoutes(deps) {
         sender,
         rewriteQuery: config.rewriteQuery,
         rerankContext: config.rerankContext,
+        fallbackFn: config.fallbackFn,
         logger
       }));
     } catch {
@@ -1428,6 +1635,7 @@ function privateRoutes(deps) {
         sender,
         rewriteQuery: config.rewriteQuery,
         rerankContext: config.rerankContext,
+        fallbackFn: config.fallbackFn,
         logger
       }));
     } catch {
@@ -1480,9 +1688,9 @@ var import_streaming4 = require("hono/streaming");
 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;
     }
@@ -1492,7 +1700,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);
@@ -1506,22 +1714,23 @@ 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);
   };
 }
 
 // src/middleware/referrer.ts
+init_logger();
 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);
@@ -1541,11 +1750,12 @@ function requireReferrer(allowedOrigins, demoApiKeys = [], logger = createConsol
 }
 
 // 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(
@@ -1609,6 +1819,7 @@ function publicRoutes(deps) {
         buckets,
         rewriteQuery: config.rewriteQuery,
         rerankContext: config.rerankContext,
+        fallbackFn: config.fallbackFn,
         logger
       }));
     } catch {
@@ -1648,8 +1859,7 @@ function publicRoutes(deps) {
 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;
@@ -1660,16 +1870,26 @@ async function createServer(config) {
   const client = new import_openai.default({
     apiKey: config.openai.apiKey
   });
-  const db = (0, import_client2.createClient)({
-    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;
@@ -1757,6 +1977,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,