@diegoaltoworks/chatter 0.61.0 → 0.62.0

package/dist/channels/whatsapp/index.mjs

@@ -67,27 +67,55 @@ function ensureAuthSchema(client) {
   }
   return ready;
 }
-async function useTursoAuthState(db, secret, sessionId, runtime) {
-  await ensureAuthSchema(db);
+function createTursoWaAuthKV(db) {
+  return {
+    async read(id) {
+      await ensureAuthSchema(db);
+      const result = await db.execute({
+        sql: "SELECT value FROM wa_auth WHERE id = ?",
+        args: [id]
+      });
+      const row = result.rows[0];
+      return row ? row.value : null;
+    },
+    async write(id, value) {
+      await ensureAuthSchema(db);
+      await db.execute({
+        sql: "INSERT OR REPLACE INTO wa_auth (id, value) VALUES (?, ?)",
+        args: [id, value]
+      });
+    },
+    async remove(id) {
+      await ensureAuthSchema(db);
+      await db.execute({ sql: "DELETE FROM wa_auth WHERE id = ?", args: [id] });
+    },
+    // Mirrors isAuthRowForSession - keep the two in sync.
+    async clear(sessionId) {
+      await ensureAuthSchema(db);
+      if (sessionId === "default") {
+        await db.execute("DELETE FROM wa_auth WHERE id NOT LIKE 's:%'");
+      } else {
+        await db.execute({
+          sql: "DELETE FROM wa_auth WHERE id LIKE ?",
+          args: [`s:${sessionId}/%`]
+        });
+      }
+    }
+  };
+}
+async function useAuthState(store, secret, sessionId, runtime) {
   const rowId = (id) => sessionId === "default" ? id : `s:${sessionId}/${id}`;
   async function read(id) {
-    const result = await db.execute({
-      sql: "SELECT value FROM wa_auth WHERE id = ?",
-      args: [rowId(id)]
-    });
-    const row = result.rows[0];
-    if (!row) return null;
-    return JSON.parse(await decrypt(row.value, secret), runtime.bufferJSON.reviver);
+    const value = await store.read(rowId(id));
+    if (value === null) return null;
+    return JSON.parse(await decrypt(value, secret), runtime.bufferJSON.reviver);
   }
   async function write(id, value) {
     const payload = await encrypt(JSON.stringify(value, runtime.bufferJSON.replacer), secret);
-    await db.execute({
-      sql: "INSERT OR REPLACE INTO wa_auth (id, value) VALUES (?, ?)",
-      args: [rowId(id), payload]
-    });
+    await store.write(rowId(id), payload);
   }
   async function remove(id) {
-    await db.execute({ sql: "DELETE FROM wa_auth WHERE id = ?", args: [rowId(id)] });
+    await store.remove(rowId(id));
   }
   const creds = await read("creds") ?? runtime.initAuthCreds();
   return {
@@ -124,18 +152,13 @@ async function useTursoAuthState(db, secret, sessionId, runtime) {
       }
     },
     saveCreds: () => write("creds", creds),
-    clear: async () => {
-      if (sessionId === "default") {
-        await db.execute("DELETE FROM wa_auth WHERE id NOT LIKE 's:%'");
-      } else {
-        await db.execute({
-          sql: "DELETE FROM wa_auth WHERE id LIKE ?",
-          args: [`s:${sessionId}/%`]
-        });
-      }
-    }
+    // Scoped to THIS session - never nuke a sibling number's pairing.
+    clear: () => store.clear(sessionId)
   };
 }
+async function useTursoAuthState(db, secret, sessionId, runtime) {
+  return useAuthState(createTursoWaAuthKV(db), secret, sessionId, runtime);
+}
 
 // src/channels/whatsapp/baileys.ts
 function wrapMissingBaileysError(cause) {
@@ -198,6 +221,11 @@ function createConsoleLogger(level = "info") {
   };
 }
 
+// src/channels/backoff.ts
+function exponentialBackoffMs(baseMs, maxMs, n) {
+  return Math.min(baseMs * 2 ** Math.max(0, Math.min(n, 20)), maxMs);
+}
+
 // src/channels/whatsapp/lease.ts
 var LEASE_STALE_MS = 9e4;
 var LEASE_HEARTBEAT_MS = 3e4;
@@ -256,7 +284,7 @@ function createTursoWaLeaseStore(client) {
 var RECONNECT_DELAY_MS = 5e3;
 var RECONNECT_MAX_DELAY_MS = 10 * 60 * 1e3;
 function reconnectDelayMs(failures) {
-  return Math.min(RECONNECT_DELAY_MS * 2 ** Math.min(failures, 20), RECONNECT_MAX_DELAY_MS);
+  return exponentialBackoffMs(RECONNECT_DELAY_MS, RECONNECT_MAX_DELAY_MS, failures);
 }
 async function shutdownWaSessions(sessions) {
   await Promise.all(
@@ -327,9 +355,18 @@ async function acquireSessionLease(sessionId, deps) {
 function senderNameFor(channelName, sessionId) {
   return sessionId === "default" ? channelName : `${channelName}:${sessionId}`;
 }
+function normalizeWaMediaPayload(payload) {
+  const media = typeof payload === "string" ? { url: payload } : payload;
+  if (!media || typeof media !== "object" || typeof media.url !== "string" || !media.url) {
+    throw new TypeError(
+      `WhatsApp sendMedia payload must be a URL string or { url, caption? }, got: ${typeof payload}`
+    );
+  }
+  return media;
+}
 function createWhatsAppChannel(config) {
   assertStrongSecret(config.sessionSecret, "WhatsApp sessionSecret (e.g. WA_SESSION_SECRET)");
-  const channelName = "whatsapp";
+  const channelName = config.name ?? "whatsapp";
   const sessionIds = config.sessionIds && config.sessionIds.length > 0 ? config.sessionIds : ["default"];
   const now = config.now ?? Date.now;
   const schedule = config.schedule ?? ((fn, ms) => void setTimeout(fn, ms));
@@ -347,8 +384,13 @@ function createWhatsAppChannel(config) {
     name: channelName,
     async start(deps) {
       const log = config.logger ?? deps.logger ?? createConsoleLogger();
-      const db = deps.db;
-      const leaseStore = createTursoWaLeaseStore(db);
+      if ((!config.leaseStore || !config.authStore) && !deps.db) {
+        throw new Error(
+          "The WhatsApp channel needs a libsql client for auth state and the session lease: set config.database (config.retriever alone does not open one), or supply both config.leaseStore and config.authStore."
+        );
+      }
+      const leaseStore = config.leaseStore ?? createTursoWaLeaseStore(deps.db);
+      const authStore = config.authStore ?? createTursoWaAuthKV(deps.db);
       senders = deps.senders;
       await loadBaileys2();
       async function connect(sessionId) {
@@ -359,8 +401,8 @@ function createWhatsAppChannel(config) {
           initAuthCreds: baileys.initAuthCreds,
           appStateSyncKeyFromObject: (value) => baileys.proto.Message.AppStateSyncKeyData.fromObject(value)
         };
-        const { state, saveCreds } = await useTursoAuthState(
-          db,
+        const { state, saveCreds } = await useAuthState(
+          authStore,
           config.sessionSecret,
           sessionId,
           runtime
@@ -404,6 +446,13 @@ function createWhatsAppChannel(config) {
               sendText: async (chatId, text) => {
                 await sock.sendMessage(chatId, { text });
               },
+              sendMedia: async (chatId, payload) => {
+                const { url, caption } = normalizeWaMediaPayload(payload);
+                await sock.sendMessage(
+                  chatId,
+                  caption !== void 0 ? { image: { url }, caption } : { image: { url } }
+                );
+              },
               sendReaction: async (chatId, messageRef, emoji) => {
                 await sock.sendMessage(chatId, {
                   react: { text: emoji, key: messageRef }
@@ -679,7 +728,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`,
@@ -741,6 +791,7 @@ async function prepareChat({
   sender,
   rewriteQuery,
   rerankContext,
+  fallbackFn,
   logger
 }) {
   const lastUserMsg = lastUserMessage(messages);
@@ -757,21 +808,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");
@@ -779,7 +848,7 @@ ${ctx.join("\n\n")}`
 }
 
 // src/history/compaction.ts
-var DEFAULT_TIMEOUT_MS = 8e3;
+var COMPACTION_TIMEOUT_MS = 8e3;
 var LOAD_ALL = Number.MAX_SAFE_INTEGER;
 var SUMMARY_PREFIX = "Summary of earlier conversation: ";
 function defaultSummarize(client, model) {
@@ -807,7 +876,7 @@ function createHistoryCompactor(deps, options) {
     throw new Error(`Invalid history compaction keep: ${keep}`);
   }
   const summarize = options.summarize ?? defaultSummarize(deps.client, options.model);
-  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const timeoutMs = options.timeoutMs ?? COMPACTION_TIMEOUT_MS;
   return {
     async maybeCompact(store, conversationId) {
       const turns = await store.load(conversationId, LOAD_ALL);
@@ -848,6 +917,16 @@ function createHistoryCompactor(deps, options) {
 }
 
 // src/channels/pipeline.ts
+function resolveBrainHooks(config, fallback) {
+  return {
+    answerFn: config.answerFn ?? fallback?.answerFn,
+    bucketsFor: config.bucketsFor ?? fallback?.bucketsFor,
+    rewriteQuery: config.rewriteQuery ?? fallback?.rewriteQuery,
+    rerankContext: config.rerankContext ?? fallback?.rerankContext,
+    fallbackFn: config.fallbackFn ?? fallback?.fallbackFn,
+    transformReply: config.transformReply ?? fallback?.transformReply
+  };
+}
 var DEFAULT_HISTORY_LIMIT = 20;
 var DEFAULT_GROUP_RATE_LIMIT = { max: 30, windowMs: 60 * 60 * 1e3 };
 var DEFAULT_DM_RATE_LIMIT = { max: 20, windowMs: 60 * 60 * 1e3 };
@@ -932,6 +1011,7 @@ function createInboundPipeline(deps, config) {
       sender,
       rewriteQuery: config.rewriteQuery,
       rerankContext: config.rerankContext,
+      fallbackFn: config.fallbackFn,
       logger: config.logger
     });
     const { content: produced } = await answerOnce({
@@ -1067,13 +1147,9 @@ function createWhatsAppInboundHandler(config) {
     { client: config.client, store: config.store, prompts: config.prompts },
     {
       channel: "whatsapp",
-      answerFn: config.answerFn,
-      bucketsFor: config.bucketsFor,
-      rewriteQuery: config.rewriteQuery,
-      rerankContext: config.rerankContext,
-      transformReply: config.transformReply,
+      ...resolveBrainHooks(config, config.serverConfig),
       model: config.model,
-      channelHint: config.channelHint,
+      channelHint: config.channelHint ?? "Channel: WhatsApp.",
       personaResolver: personaResolver ? ({ sender, text }) => personaResolver({ senderPhone: sender, text }) : void 0,
       history: config.history,
       allowedChats,
@@ -1233,6 +1309,7 @@ export {
   LEASE_WAIT_MS,
   acquireSessionLease,
   canAcquireLease,
+  createTursoWaAuthKV,
   createTursoWaLeaseStore,
   createWhatsAppChannel,
   createWhatsAppImageHandler,
@@ -1248,11 +1325,13 @@ export {
   jidsMatch,
   loadBaileys,
   messageContext,
+  normalizeWaMediaPayload,
   reconnectDelayMs,
   resolveWaMessage,
   senderNameFor,
   senderPhoneFor,
   shutdownWaSessions,
   stripOwnMentions,
+  useAuthState,
   useTursoAuthState
 };

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

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

package/dist/client/src/Chat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Chat.d.ts","sourceRoot":"","sources":["../../../src/client/src/Chat.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEvD,qBAAa,IAAI;IACf,OAAO,CAAC,GAAG,CAAU;IACrB,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAC,CAAa;IAE7B,OAAO,CAAC,iBAAiB,CAAe;IACxC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,UAAU,CAAqB;IAEvC,YAAY,MAAM,EAAE,UAAU,EA4B7B;IAED,OAAO,CAAC,MAAM;IAqBd,OAAO,CAAC,oBAAoB;YA+Cd,UAAU;IAkExB,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,oBAAoB;IAQ5B,OAAO,CAAC,eAAe;IAKvB,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,KAAK,IAAI,IAAI,CAGZ;IAED;;OAEG;IACH,WAAW,IAAI,WAAW,EAAE,CAE3B;IAED;;OAEG;IACH,OAAO,IAAI,IAAI,CAEd;IAED;;OAEG;IACH,OAAO,CAAC,QAAQ;CAGjB"}
+{"version":3,"file":"Chat.d.ts","sourceRoot":"","sources":["../../../src/client/src/Chat.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEvD,qBAAa,IAAI;IACf,OAAO,CAAC,GAAG,CAAU;IACrB,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAC,CAAa;IAE7B,OAAO,CAAC,iBAAiB,CAAe;IACxC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,UAAU,CAAqB;IAEvC,YAAY,MAAM,EAAE,UAAU,EA0B7B;IAED,OAAO,CAAC,MAAM;IAoBd,OAAO,CAAC,oBAAoB;YA8Cd,UAAU;IA4DxB,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,oBAAoB;IAQ5B,OAAO,CAAC,eAAe;IAKvB,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,KAAK,IAAI,IAAI,CAGZ;IAED;;OAEG;IACH,WAAW,IAAI,WAAW,EAAE,CAE3B;IAED;;OAEG;IACH,OAAO,IAAI,IAAI,CAEd;IAED;;OAEG;IACH,OAAO,CAAC,QAAQ;CAGjB"}

package/dist/client/src/ChatButton.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChatButton.d.ts","sourceRoot":"","sources":["../../../src/client/src/ChatButton.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,aAAa,CAAe;IACpC,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,MAAM,CAAS;IAEvB,YAAY,MAAM,EAAE,gBAAgB,EASnC;IAED,OAAO,CAAC,MAAM;IAsBd,OAAO,CAAC,oBAAoB;IAsB5B,OAAO,CAAC,MAAM;IAQd,IAAI,IAAI,IAAI,CAgDX;IAED,KAAK,IAAI,IAAI,CAcZ;IAED;;OAEG;IACH,OAAO,CAAC,QAAQ;IAIhB;;OAEG;IACH,OAAO,IAAI,IAAI,CAId;IAED;;OAEG;IACH,QAAQ,IAAI,OAAO,CAElB;CACF"}
+{"version":3,"file":"ChatButton.d.ts","sourceRoot":"","sources":["../../../src/client/src/ChatButton.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,aAAa,CAAe;IACpC,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,MAAM,CAAS;IAEvB,YAAY,MAAM,EAAE,gBAAgB,EASnC;IAED,OAAO,CAAC,MAAM;IAkBd,OAAO,CAAC,oBAAoB;IAoB5B,OAAO,CAAC,MAAM;IAQd,IAAI,IAAI,IAAI,CA+CX;IAED,KAAK,IAAI,IAAI,CAcZ;IAED;;OAEG;IACH,OAAO,CAAC,QAAQ;IAIhB;;OAEG;IACH,OAAO,IAAI,IAAI,CAId;IAED;;OAEG;IACH,QAAQ,IAAI,OAAO,CAElB;CACF"}

package/dist/client/src/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../src/client/src/browser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,OAAO,EAAE;YACP,OAAO,EAAE,OAAO,OAAO,CAAC;YACxB,IAAI,EAAE,OAAO,IAAI,CAAC;YAClB,UAAU,EAAE,OAAO,UAAU,CAAC;SAC/B,CAAC;KACH;CACF;AAWD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../src/client/src/browser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,OAAO,EAAE;YACP,OAAO,EAAE,OAAO,OAAO,CAAC;YACxB,IAAI,EAAE,OAAO,IAAI,CAAC;YAClB,UAAU,EAAE,OAAO,UAAU,CAAC;SAC/B,CAAC;KACH;CACF;AAYD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/core/answer.d.ts

@@ -95,6 +95,14 @@ export type TransformReply = (input: TransformReplyInput) => string | null | Pro
  * Runs `transformReply` if configured. A throw/rejection is logged and the
  * ORIGINAL text is returned — the delivery invariant: a bug in a plugin hook
  * must never silently swallow an answer the model already produced.
+ *
+ * The result crosses the same plugin boundary `runAnswerFn` does, so it gets
+ * the same treatment: anything that isn't a string is coerced to `null`
+ * (treated as a veto) rather than passed through as whatever a
+ * non-conforming hook happened to return (`undefined` from a missing
+ * `return`, say). Every call site already treats a falsy result as "nothing
+ * delivered", but only a normalized `string | null` matches this function's
+ * own declared return type.
  */
 export declare function applyTransformReply(transformReply: TransformReply | undefined, input: TransformReplyInput, logger?: Pick<Logger, "error">): Promise<string | null>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"answer.d.ts","sourceRoot":"","sources":["../../src/core/answer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAGjC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEhE,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB;AAKD,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,uCAAuC;IACvC,IAAI,EAAE,YAAY,CAAC;IACnB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,CAAA;CAAE,CAAC;AAE/E;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,CAAC;AAE1F,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAqBD;;GAEG;AACH,wBAAsB,UAAU,CAAC,EAC/B,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,cAAc,EACd,WAAW,EACX,KAAK,GACN,EAAE,aAAa,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC,CAKlE;AAED,4FAA4F;AAC5F,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,mBAAmB,KAAK,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAEpG;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,cAAc,EAAE,cAAc,GAAG,SAAS,EAC1C,KAAK,EAAE,mBAAmB,EAC1B,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWxB;AAED;;;;;;;;GAQG;AACH,wBAAuB,YAAY,CAAC,EAClC,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,cAAc,EACd,WAAW,EACX,KAAK,GACN,EAAE,aAAa,GAAG,cAAc,CAAC,MAAM,CAAC,CAaxC"}
+{"version":3,"file":"answer.d.ts","sourceRoot":"","sources":["../../src/core/answer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAGjC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEhE,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;CACtB;AAKD,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,uCAAuC;IACvC,IAAI,EAAE,YAAY,CAAC;IACnB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,CAAA;CAAE,CAAC;AAE/E;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,CAAC;AAE1F,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAqBD;;GAEG;AACH,wBAAsB,UAAU,CAAC,EAC/B,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,cAAc,EACd,WAAW,EACX,KAAK,GACN,EAAE,aAAa,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC,CAKlE;AAED,4FAA4F;AAC5F,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,mBAAmB,KAAK,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAEpG;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CACvC,cAAc,EAAE,cAAc,GAAG,SAAS,EAC1C,KAAK,EAAE,mBAAmB,EAC1B,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYxB;AAED;;;;;;;;GAQG;AACH,wBAAuB,YAAY,CAAC,EAClC,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,cAAc,EACd,WAAW,EACX,KAAK,GACN,EAAE,aAAa,GAAG,cAAc,CAAC,MAAM,CAAC,CAaxC"}

package/dist/core/buildLock.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Single-writer lock around the destructive half of a knowledge-base build.
+ *
+ * `VectorStore.build()` is a read-diff-delete-insert sequence: it reads the
+ * chunk ids already in the database, computes the ids its own `knowledgeDir`
+ * produces, and deletes everything not in that set. Two instances booting
+ * against the same database at the same time (a rolling deploy, a manual
+ * deploy racing an automated one) each run that sequence against a view of
+ * the data the other is still mutating, so one boot's cleanup can delete
+ * chunks the other has just written or has not finished writing.
+ *
+ * The lock lives in the same database (`chatter_build_lock`) so it is visible
+ * to every instance, and acquiring or renewing it is a single atomic upsert
+ * (see `createTursoBuildLock`) - two instances racing the same key can never
+ * both believe they hold it. A holder that dies without releasing leaves a
+ * stale row instead of wedging every future boot: after `staleMs` with no
+ * heartbeat, the next instance may take it over.
+ */
+import type { Client } from "@libsql/client";
+/** Lock key for the knowledge-base build. One build runs per database at a time. */
+export declare const BUILD_LOCK_KEY = "knowledge_build";
+/**
+ * A held lock this old with no heartbeat is treated as abandoned. Generous
+ * because a first build embeds every chunk it loads, which can take minutes;
+ * a holder renews the lock as it goes (see `VectorStore.build`), so only a
+ * process that actually died lets the lock go stale.
+ */
+export declare const BUILD_LOCK_STALE_MS: number;
+export interface BuildLockRow {
+    holderId: string;
+    heartbeatAt: number;
+}
+/**
+ * Pure: may `holderId` take (or keep) the build lock right now, given the
+ * current row (null = never held)? Mirrors the SQL WHERE clause in
+ * `createTursoBuildLock` - keep the two in sync.
+ */
+export declare function canAcquireBuildLock(existing: BuildLockRow | null, holderId: string, now: number, staleMs?: number): boolean;
+export interface BuildLock {
+    /** Atomically acquires or renews the lock; resolves true iff `holderId` now holds it. */
+    tryAcquire(key: string, holderId: string, now: number, staleMs: number): Promise<boolean>;
+    /** Releases the lock iff still held by `holderId` (no-op otherwise, so a late release never undoes a takeover). */
+    release(key: string, holderId: string): Promise<void>;
+}
+/**
+ * A libsql-backed {@link BuildLock}. The WHERE clause on DO UPDATE encodes
+ * `canAcquireBuildLock`: SQLite skips the update (and RETURNING yields no
+ * row) when it is false, so a losing racer sees zero rows back - no separate
+ * read-then-write, no race window.
+ */
+export declare function createTursoBuildLock(client: Client): BuildLock;
+//# sourceMappingURL=buildLock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"buildLock.d.ts","sourceRoot":"","sources":["../../src/core/buildLock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAE7C,oFAAoF;AACpF,eAAO,MAAM,cAAc,oBAAoB,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAAc,CAAC;AAE/C,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,YAAY,GAAG,IAAI,EAC7B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,MAA4B,GACpC,OAAO,CAIT;AAED,MAAM,WAAW,SAAS;IACxB,yFAAyF;IACzF,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1F,mHAAmH;IACnH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD;AAwBD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAyB9D"}

package/dist/core/pipeline.d.ts

@@ -10,7 +10,7 @@
  */
 import type { Logger } from "./logger";
 import type { PromptLoader } from "./prompts";
-import type { VectorStore } from "./retrieval";
+import type { Retriever } from "./retrieval";
 export type PipelineMode = "public" | "private";
 export interface PipelineMessage {
     role: "user" | "assistant";
@@ -60,11 +60,43 @@ export interface RerankContextArgs {
  * fails closed by design; use this hook for relevance/ordering only.
  */
 export type RerankContext = (ctx: RerankContextArgs) => string[] | Promise<string[]>;
+/** What `fallbackFn` sees for a turn where retrieval came back empty. */
+export interface FallbackContext {
+    /** The query retrieval actually ran with, post-`rewriteQuery` if configured. */
+    query: string;
+    mode: PipelineMode;
+    /** Buckets retrieval ran against for this turn. */
+    buckets: string[];
+    /** Caller identity, where the surface has one. Absent on anonymous surfaces. */
+    sender?: string;
+    /**
+     * What `store.query` returned, before `rerankContext` ran: always
+     * non-empty when this is empty because `rerankContext` filtered
+     * everything out, and always empty when the store itself found nothing.
+     * A hook can use this to tell "some low-confidence signal existed" apart
+     * from "nothing matched at all".
+     */
+    retrievedChunks: string[];
+}
+/**
+ * Runs only when retrieval produced no chunks for a turn (after
+ * `rerankContext`, if configured), the deterministic, testable alternative
+ * to baking "what if there's nothing to retrieve" judgment calls into
+ * freeform system-prompt text. Return a string to inject as an extra system
+ * prompt layer scoped to this turn only (e.g. "no matching context was
+ * found; offer a clearly-labelled guess or decline"); return `undefined` to
+ * leave the prompt exactly as it would be otherwise.
+ *
+ * A throw/rejection is caught by `prepareChat`, which proceeds without
+ * fallback guidance: a broken hook must never break the chat path.
+ */
+export type FallbackFn = (ctx: FallbackContext) => string | undefined | Promise<string | undefined>;
 /**
  * Run retrieval for the latest user message and assemble the system prompt.
  *
  * The assembled system prompt is layered, in order:
- * base rules → persona → channel hint (optional) → retrieved context.
+ * base rules → persona → channel hint (optional) → fallback guidance
+ * (optional, only when retrieval came back empty) → retrieved context.
  *
  * `personaLayer` and `channelHint` let a caller shape those middle layers
  * without hand-rolling its own sandwich around `store`/`prompts`. Both are
@@ -83,10 +115,13 @@ export type RerankContext = (ctx: RerankContextArgs) => string[] | Promise<strin
  * value falls back to what retrieval would have done unmodified, so a buggy
  * hook degrades relevance rather than breaking the chat path.
  *
+ * `fallbackFn` runs after both, only when the chunks folded into the prompt
+ * would otherwise be empty, see {@link FallbackFn}.
+ *
  * @throws if the conversation contains no user message
  */
-export declare function prepareChat({ store, prompts, mode, messages, personaLayer, channelHint, buckets, sender, rewriteQuery, rerankContext, logger, }: {
-    store: VectorStore;
+export declare function prepareChat({ store, prompts, mode, messages, personaLayer, channelHint, buckets, sender, rewriteQuery, rerankContext, fallbackFn, logger, }: {
+    store: Retriever;
     prompts: PromptLoader;
     mode: PipelineMode;
     messages: PipelineMessage[];
@@ -105,7 +140,9 @@ export declare function prepareChat({ store, prompts, mode, messages, personaLay
     rewriteQuery?: RewriteQuery;
     /** Post-processes retrieved chunks before they're folded into the prompt — see {@link RerankContext}. */
     rerankContext?: RerankContext;
-    /** Logs a `rewriteQuery`/`rerankContext` throw before falling back. Unset: the failure is silent. */
+    /** Injects fallback guidance when retrieval comes back empty, see {@link FallbackFn}. */
+    fallbackFn?: FallbackFn;
+    /** Logs a `rewriteQuery`/`rerankContext`/`fallbackFn` throw before falling back. Unset: the failure is silent. */
     logger?: Pick<Logger, "error">;
 }): Promise<PreparedChat>;
 //# sourceMappingURL=pipeline.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/core/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,iIAAiI;IACjI,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,2CAA2C;AAC3C,MAAM,WAAW,gBAAgB;IAC/B,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,YAAY,CAAC;IACnB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,gBAAgB,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE/E,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,iBAAiB,KAAK,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AAOrF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,WAAW,CAAC,EAChC,KAAK,EACL,OAAO,EACP,IAAI,EACJ,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,OAAO,EACP,MAAM,EACN,YAAY,EACZ,aAAa,EACb,MAAM,GACP,EAAE;IACD,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,YAAY,CAAC;IACtB,IAAI,EAAE,YAAY,CAAC;IACnB,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,uFAAuF;IACvF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yFAAyF;IACzF,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,yGAAyG;IACzG,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,qGAAqG;IACrG,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,GAAG,OAAO,CAAC,YAAY,CAAC,CAuCxB"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/core/pipeline.ts"],"names":[],"mappings":"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"}

package/dist/core/prompts.d.ts

@@ -3,6 +3,8 @@
  * Loads prompt templates and interpolates bot configuration
  */
 import type { BotIdentity } from "../types";
+/** Default prompts directory when a caller's `config.promptsDir` is unset. */
+export declare const DEFAULT_PROMPTS_DIR = "./config/prompts";
 /**
  * Prompt loader class that loads and interpolates prompt templates
  * with bot identity information

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

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../src/core/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C;;;GAGG;AACH,qBAAa,YAAY;IAErB,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,GAAG;IAFb,YACU,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,WAAW,EACtB;IAEJ;;OAEG;IACH,OAAO,CAAC,IAAI;IAcZ,+BAA+B;IAC/B,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED,4BAA4B;IAC5B,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,6BAA6B;IAC7B,IAAI,cAAc,IAAI,MAAM,CAE3B;CACF"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../src/core/prompts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,qBAAqB,CAAC;AAEtD;;;GAGG;AACH,qBAAa,YAAY;IAErB,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,GAAG;IAFb,YACU,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,WAAW,EACtB;IAEJ;;OAEG;IACH,OAAO,CAAC,IAAI;IAcZ,+BAA+B;IAC/B,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED,4BAA4B;IAC5B,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,6BAA6B;IAC7B,IAAI,cAAc,IAAI,MAAM,CAE3B;CACF"}