@diegoaltoworks/chatter 1.0.0 → 2.1.0

package/dist/channels/whatsapp/index.js

@@ -475,6 +475,7 @@ function createWhatsAppChannel(config) {
   assertStrongSecret(config.sessionSecret, "WhatsApp sessionSecret (e.g. WA_SESSION_SECRET)");
   const channelName = config.name ?? "whatsapp";
   const sessionIds = config.sessionIds && config.sessionIds.length > 0 ? config.sessionIds : ["default"];
+  const multiEndpoint = config.name !== void 0 || sessionIds.length > 1;
   const now = config.now ?? Date.now;
   const schedule = config.schedule ?? ((fn, ms) => void setTimeout(fn, ms));
   const staleMs = config.staleMs ?? LEASE_STALE_MS;
@@ -668,7 +669,12 @@ function createWhatsAppChannel(config) {
             if (type !== "notify") return;
             for (const message of messages) {
               try {
-                await config.onMessage?.({ sessionId, sock, message });
+                await config.onMessage?.({
+                  sessionId,
+                  sock,
+                  message,
+                  endpointId: multiEndpoint ? sessionId : void 0
+                });
               } catch (error) {
                 log.warn(`WhatsApp[${sessionId}]: onMessage handler failed:`, error);
               }
@@ -866,9 +872,10 @@ function detectLeakage(text) {
 function scrubOutput(text) {
   return text.replace(/sk-[A-Za-z0-9]{15,}/g, "[REDACTED]").replace(/AIza[0-9A-Za-z_-]{30,}/g, "[REDACTED]");
 }
-function guardOutput(text) {
+var DEFAULT_REFUSAL = "Sorry, I can't share internal instructions. How else can I help?";
+function guardOutput(text, refusal) {
   if (detectLeakage(text)) {
-    return "Sorry, I can't share internal instructions. How else can I help?";
+    return typeof refusal === "string" && refusal.trim() ? refusal : DEFAULT_REFUSAL;
   }
   return scrubOutput(text);
 }
@@ -880,7 +887,8 @@ async function completeOnce({
   system,
   messages,
   temperature = 0.2,
-  model = DEFAULT_MODEL
+  model = DEFAULT_MODEL,
+  refusal
 }) {
   const res = await client.chat.completions.create({
     model,
@@ -889,19 +897,19 @@ async function completeOnce({
   });
   const text = res.choices[0]?.message?.content ?? "";
   return {
-    content: guardOutput(text),
+    content: guardOutput(text, refusal),
     usage: res.usage || { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 }
   };
 }
 
 // src/core/answer.ts
 var noUsage = () => ({ prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 });
-async function runAnswerFn(answerFn, { system, messages, mode, sender, conversationId }) {
+async function runAnswerFn(answerFn, { system, messages, mode, sender, conversationId }, refusal) {
   const result = await answerFn({ system, messages, mode, sender, conversationId });
   const raw = typeof result === "string" ? result : result?.content;
   const usage = typeof result === "string" ? void 0 : result?.usage;
   return {
-    content: guardOutput(typeof raw === "string" ? raw : ""),
+    content: guardOutput(typeof raw === "string" ? raw : "", refusal),
     usage: usage ?? noUsage()
   };
 }
@@ -914,12 +922,13 @@ async function answerOnce({
   sender,
   conversationId,
   temperature,
-  model
+  model,
+  refusal
 }) {
   if (answerFn) {
-    return runAnswerFn(answerFn, { system, messages, mode, sender, conversationId });
+    return runAnswerFn(answerFn, { system, messages, mode, sender, conversationId }, refusal);
   }
-  return completeOnce({ client, system, messages, temperature, model });
+  return completeOnce({ client, system, messages, temperature, model, refusal });
 }
 async function applyTransformReply(transformReply, input, logger) {
   if (!transformReply) return input.text;
@@ -1125,9 +1134,17 @@ function resolveBrainHooks(config, fallback) {
     rewriteQuery: config.rewriteQuery ?? fallback?.rewriteQuery,
     rerankContext: config.rerankContext ?? fallback?.rerankContext,
     fallbackFn: config.fallbackFn ?? fallback?.fallbackFn,
-    transformReply: config.transformReply ?? fallback?.transformReply
+    transformReply: config.transformReply ?? fallback?.transformReply,
+    refusal: config.refusal ?? fallback?.refusal
   };
 }
+function escapeKeyPart(part) {
+  return part.replaceAll("%", "%25").replaceAll("#", "%23");
+}
+function conversationKeyFor(chatId, endpointId) {
+  if (!endpointId) return chatId;
+  return `${escapeKeyPart(chatId)}#${escapeKeyPart(endpointId)}`;
+}
 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 };
@@ -1186,11 +1203,15 @@ function createInboundPipeline(deps, config) {
       return { action: "rate-limited" };
     }
     const sender = typeof turn.sender === "function" ? await turn.sender() : turn.sender ?? msg.senderId;
-    const conversationId = turn.conversationId ?? msg.chatId;
+    const conversationId = turn.conversationId ?? conversationKeyFor(msg.chatId, msg.endpointId);
     if (turn.intercept && await turn.intercept(sender)) {
       return { action: "intercepted" };
     }
-    const personaLayer = await resolvePersonaLayer(config, { sender, text: msg.text });
+    const personaLayer = await resolvePersonaLayer(config, {
+      sender,
+      text: msg.text,
+      endpointId: msg.endpointId
+    });
     const buckets = await resolveBuckets({ mode, sender, bucketsFor: config.bucketsFor });
     const historyEnabled = config.history ? await isHistoryEnabled(config, sender) : false;
     const priorTurns = config.history && historyEnabled ? await config.history.store.load(
@@ -1223,7 +1244,8 @@ function createInboundPipeline(deps, config) {
       mode,
       sender,
       conversationId,
-      model: config.model
+      model: config.model,
+      refusal: config.refusal
     });
     const content = await applyTransformReply(
       config.transformReply,
@@ -1310,7 +1332,7 @@ function stripOwnMentions(text, ownIds) {
   return cleaned ? cleaned : text;
 }
 function resolveWaMessage(event, registry) {
-  const { sessionId, sock, message } = event;
+  const { sessionId, sock, message, endpointId } = event;
   const chatId = message.key.remoteJid ?? "";
   const rawText = extractText(message);
   const context = messageContext(message);
@@ -1334,7 +1356,13 @@ function resolveWaMessage(event, registry) {
     // targets. Exposed generically so a caller reaching `msg` through
     // `createInboundPipeline` (not just the WhatsApp-specific router) can
     // still react to it via `ChannelSenderRegistry.sendReaction`.
-    messageRef: message.key
+    messageRef: message.key,
+    // The session id this channel instance was configured with, not a wire
+    // identity - stable across the number's own SIM or token changing.
+    // Unset for a default single-session channel (see
+    // WhatsAppMessageEvent.endpointId) so a host that hasn't opted into
+    // multiple endpoints sees no change.
+    endpointId
   };
   return { msg, ownIds };
 }
@@ -1351,7 +1379,7 @@ function createWhatsAppInboundHandler(config) {
       ...resolveBrainHooks(config, config.serverConfig),
       model: config.model,
       channelHint: config.channelHint ?? "Channel: WhatsApp.",
-      personaResolver: personaResolver ? ({ sender, text }) => personaResolver({ senderPhone: sender, text }) : void 0,
+      personaResolver: personaResolver ? ({ sender, text, endpointId }) => personaResolver({ senderPhone: sender, text, endpointId }) : void 0,
       history: config.history,
       allowedChats,
       muteRegex: config.muteRegex,
@@ -1388,7 +1416,6 @@ function createWhatsAppInboundHandler(config) {
       };
       await pipeline(msg, {
         reply,
-        conversationId: chatId,
         sender: () => senderPhoneFor(sock, message, chatId),
         intercept: images ? (senderPhone) => images({
           sock,

package/dist/channels/whatsapp/index.mjs

@@ -410,6 +410,7 @@ function createWhatsAppChannel(config) {
   assertStrongSecret(config.sessionSecret, "WhatsApp sessionSecret (e.g. WA_SESSION_SECRET)");
   const channelName = config.name ?? "whatsapp";
   const sessionIds = config.sessionIds && config.sessionIds.length > 0 ? config.sessionIds : ["default"];
+  const multiEndpoint = config.name !== void 0 || sessionIds.length > 1;
   const now = config.now ?? Date.now;
   const schedule = config.schedule ?? ((fn, ms) => void setTimeout(fn, ms));
   const staleMs = config.staleMs ?? LEASE_STALE_MS;
@@ -603,7 +604,12 @@ function createWhatsAppChannel(config) {
             if (type !== "notify") return;
             for (const message of messages) {
               try {
-                await config.onMessage?.({ sessionId, sock, message });
+                await config.onMessage?.({
+                  sessionId,
+                  sock,
+                  message,
+                  endpointId: multiEndpoint ? sessionId : void 0
+                });
               } catch (error) {
                 log.warn(`WhatsApp[${sessionId}]: onMessage handler failed:`, error);
               }
@@ -801,9 +807,10 @@ function detectLeakage(text) {
 function scrubOutput(text) {
   return text.replace(/sk-[A-Za-z0-9]{15,}/g, "[REDACTED]").replace(/AIza[0-9A-Za-z_-]{30,}/g, "[REDACTED]");
 }
-function guardOutput(text) {
+var DEFAULT_REFUSAL = "Sorry, I can't share internal instructions. How else can I help?";
+function guardOutput(text, refusal) {
   if (detectLeakage(text)) {
-    return "Sorry, I can't share internal instructions. How else can I help?";
+    return typeof refusal === "string" && refusal.trim() ? refusal : DEFAULT_REFUSAL;
   }
   return scrubOutput(text);
 }
@@ -815,7 +822,8 @@ async function completeOnce({
   system,
   messages,
   temperature = 0.2,
-  model = DEFAULT_MODEL
+  model = DEFAULT_MODEL,
+  refusal
 }) {
   const res = await client.chat.completions.create({
     model,
@@ -824,19 +832,19 @@ async function completeOnce({
   });
   const text = res.choices[0]?.message?.content ?? "";
   return {
-    content: guardOutput(text),
+    content: guardOutput(text, refusal),
     usage: res.usage || { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 }
   };
 }
 
 // src/core/answer.ts
 var noUsage = () => ({ prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 });
-async function runAnswerFn(answerFn, { system, messages, mode, sender, conversationId }) {
+async function runAnswerFn(answerFn, { system, messages, mode, sender, conversationId }, refusal) {
   const result = await answerFn({ system, messages, mode, sender, conversationId });
   const raw = typeof result === "string" ? result : result?.content;
   const usage = typeof result === "string" ? void 0 : result?.usage;
   return {
-    content: guardOutput(typeof raw === "string" ? raw : ""),
+    content: guardOutput(typeof raw === "string" ? raw : "", refusal),
     usage: usage ?? noUsage()
   };
 }
@@ -849,12 +857,13 @@ async function answerOnce({
   sender,
   conversationId,
   temperature,
-  model
+  model,
+  refusal
 }) {
   if (answerFn) {
-    return runAnswerFn(answerFn, { system, messages, mode, sender, conversationId });
+    return runAnswerFn(answerFn, { system, messages, mode, sender, conversationId }, refusal);
   }
-  return completeOnce({ client, system, messages, temperature, model });
+  return completeOnce({ client, system, messages, temperature, model, refusal });
 }
 async function applyTransformReply(transformReply, input, logger) {
   if (!transformReply) return input.text;
@@ -1060,9 +1069,17 @@ function resolveBrainHooks(config, fallback) {
     rewriteQuery: config.rewriteQuery ?? fallback?.rewriteQuery,
     rerankContext: config.rerankContext ?? fallback?.rerankContext,
     fallbackFn: config.fallbackFn ?? fallback?.fallbackFn,
-    transformReply: config.transformReply ?? fallback?.transformReply
+    transformReply: config.transformReply ?? fallback?.transformReply,
+    refusal: config.refusal ?? fallback?.refusal
   };
 }
+function escapeKeyPart(part) {
+  return part.replaceAll("%", "%25").replaceAll("#", "%23");
+}
+function conversationKeyFor(chatId, endpointId) {
+  if (!endpointId) return chatId;
+  return `${escapeKeyPart(chatId)}#${escapeKeyPart(endpointId)}`;
+}
 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 };
@@ -1121,11 +1138,15 @@ function createInboundPipeline(deps, config) {
       return { action: "rate-limited" };
     }
     const sender = typeof turn.sender === "function" ? await turn.sender() : turn.sender ?? msg.senderId;
-    const conversationId = turn.conversationId ?? msg.chatId;
+    const conversationId = turn.conversationId ?? conversationKeyFor(msg.chatId, msg.endpointId);
     if (turn.intercept && await turn.intercept(sender)) {
       return { action: "intercepted" };
     }
-    const personaLayer = await resolvePersonaLayer(config, { sender, text: msg.text });
+    const personaLayer = await resolvePersonaLayer(config, {
+      sender,
+      text: msg.text,
+      endpointId: msg.endpointId
+    });
     const buckets = await resolveBuckets({ mode, sender, bucketsFor: config.bucketsFor });
     const historyEnabled = config.history ? await isHistoryEnabled(config, sender) : false;
     const priorTurns = config.history && historyEnabled ? await config.history.store.load(
@@ -1158,7 +1179,8 @@ function createInboundPipeline(deps, config) {
       mode,
       sender,
       conversationId,
-      model: config.model
+      model: config.model,
+      refusal: config.refusal
     });
     const content = await applyTransformReply(
       config.transformReply,
@@ -1245,7 +1267,7 @@ function stripOwnMentions(text, ownIds) {
   return cleaned ? cleaned : text;
 }
 function resolveWaMessage(event, registry) {
-  const { sessionId, sock, message } = event;
+  const { sessionId, sock, message, endpointId } = event;
   const chatId = message.key.remoteJid ?? "";
   const rawText = extractText(message);
   const context = messageContext(message);
@@ -1269,7 +1291,13 @@ function resolveWaMessage(event, registry) {
     // targets. Exposed generically so a caller reaching `msg` through
     // `createInboundPipeline` (not just the WhatsApp-specific router) can
     // still react to it via `ChannelSenderRegistry.sendReaction`.
-    messageRef: message.key
+    messageRef: message.key,
+    // The session id this channel instance was configured with, not a wire
+    // identity - stable across the number's own SIM or token changing.
+    // Unset for a default single-session channel (see
+    // WhatsAppMessageEvent.endpointId) so a host that hasn't opted into
+    // multiple endpoints sees no change.
+    endpointId
   };
   return { msg, ownIds };
 }
@@ -1286,7 +1314,7 @@ function createWhatsAppInboundHandler(config) {
       ...resolveBrainHooks(config, config.serverConfig),
       model: config.model,
       channelHint: config.channelHint ?? "Channel: WhatsApp.",
-      personaResolver: personaResolver ? ({ sender, text }) => personaResolver({ senderPhone: sender, text }) : void 0,
+      personaResolver: personaResolver ? ({ sender, text, endpointId }) => personaResolver({ senderPhone: sender, text, endpointId }) : void 0,
       history: config.history,
       allowedChats,
       muteRegex: config.muteRegex,
@@ -1323,7 +1351,6 @@ function createWhatsAppInboundHandler(config) {
       };
       await pipeline(msg, {
         reply,
-        conversationId: chatId,
         sender: () => senderPhoneFor(sock, message, chatId),
         intercept: images ? (senderPhone) => images({
           sock,

package/dist/core/answer.d.ts

@@ -59,11 +59,18 @@ export interface AnswerOptions {
     conversationId?: string;
     temperature?: number;
     model?: string;
+    /**
+     * Wording for the guardrail refusal, for a surface that has already
+     * resolved whose voice this answer speaks in. Falls back to the
+     * server/channel-level `BrainHooks.refusal` the call site passes, and then
+     * to `DEFAULT_REFUSAL`. Detection and scrubbing stay Chatter's either way.
+     */
+    refusal?: string;
 }
 /**
  * Produce one complete answer, from `answerFn` when configured.
  */
-export declare function answerOnce({ answerFn, client, system, messages, mode, sender, conversationId, temperature, model, }: AnswerOptions): Promise<{
+export declare function answerOnce({ answerFn, client, system, messages, mode, sender, conversationId, temperature, model, refusal, }: AnswerOptions): Promise<{
     content: string;
     usage: AnswerUsage;
 }>;
@@ -114,5 +121,5 @@ export declare function applyTransformReply(transformReply: TransformReply | und
  * built-in stream only scrubs each delta, since leakage detection needs text
  * no streamed chunk has yet.
  */
-export declare function answerStream({ answerFn, client, system, messages, mode, sender, conversationId, temperature, model, }: AnswerOptions): AsyncGenerator<string>;
+export declare function answerStream({ answerFn, client, system, messages, mode, sender, conversationId, temperature, model, refusal, }: AnswerOptions): AsyncGenerator<string>;
 //# sourceMappingURL=answer.d.ts.map

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;;;;;;;;;;;;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"}
+{"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;IACf;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAsBD;;GAEG;AACH,wBAAsB,UAAU,CAAC,EAC/B,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,cAAc,EACd,WAAW,EACX,KAAK,EACL,OAAO,GACR,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,EACL,OAAO,GACR,EAAE,aAAa,GAAG,cAAc,CAAC,MAAM,CAAC,CAWxC"}

package/dist/core/chunking.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Section-aware Markdown chunking.
+ *
+ * A pure line scanner (no Markdown parser dependency) that splits a document at
+ * every ATX heading, records the heading trail each chunk sat under, and keeps
+ * fenced code blocks, lists and tables whole. A section longer than the cap is
+ * split on blank-line paragraph boundaries; consecutive small sections are
+ * never merged.
+ */
+/** One chunk of a document, in reading order. */
+export type SectionChunk = {
+    /** The chunk's text. A section's first chunk starts with its heading line. */
+    text: string;
+    /** Heading trail from the H1 down; empty for text before the first heading. */
+    section: string[];
+    /** Zero-based index of the chunk within the document. */
+    position: number;
+};
+/**
+ * Split Markdown `text` into structure-aware chunks of at most `max` characters
+ * where the structure allows it.
+ *
+ * Every ATX heading starts a new chunk, with the heading line kept at its top.
+ * A section longer than `max` is split on paragraph boundaries, each piece
+ * keeping the section's trail. A fenced code block, list or table is atomic and
+ * is emitted whole even if it alone exceeds `max`. Empty chunks are never
+ * produced, and every non-blank input line appears in exactly one chunk, in
+ * order.
+ */
+export declare function chunkSections(text: string, max?: number): SectionChunk[];
+//# sourceMappingURL=chunking.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunking.d.ts","sourceRoot":"","sources":["../../src/core/chunking.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,iDAAiD;AACjD,MAAM,MAAM,YAAY,GAAG;IACzB,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AA+GF;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAM,GAAG,YAAY,EAAE,CA6BrE"}

package/dist/core/guardrails.d.ts

@@ -1,11 +1,21 @@
 export declare function detectLeakage(text: string): boolean;
 export declare function scrubOutput(text: string): string;
+/**
+ * The refusal sent when leaked instructions are detected and no host has
+ * supplied its own wording.
+ */
+export declare const DEFAULT_REFUSAL = "Sorry, I can't share internal instructions. How else can I help?";
 /**
  * Apply the full output guardrails to a complete answer: refuse leaked
  * instructions outright, then scrub credentials from whatever remains.
  *
  * Used for every non-streamed answer, whoever produced it — the built-in
  * completion or a caller-supplied brain (`answerFn`).
+ *
+ * `refusal` only replaces the wording of the refusal. Detection and scrubbing
+ * are not configurable, so a host can voice the guard but never weaken it; a
+ * blank or non-string `refusal` falls back to `DEFAULT_REFUSAL` rather than
+ * letting a host silence the refusal by supplying an empty line.
  */
-export declare function guardOutput(text: string): string;
+export declare function guardOutput(text: string, refusal?: string): string;
 //# sourceMappingURL=guardrails.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"guardrails.d.ts","sourceRoot":"","sources":["../../src/core/guardrails.ts"],"names":[],"mappings":"AAAA,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CASnD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKhD"}
+{"version":3,"file":"guardrails.d.ts","sourceRoot":"","sources":["../../src/core/guardrails.ts"],"names":[],"mappings":"AAAA,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CASnD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,qEAAqE,CAAC;AAElG;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAKlE"}

package/dist/core/llm.d.ts

@@ -1,6 +1,6 @@
 import type OpenAI from "openai";
 export declare const DEFAULT_MODEL = "gpt-4o";
-export declare function completeOnce({ client, system, messages, temperature, model, }: {
+export declare function completeOnce({ client, system, messages, temperature, model, refusal, }: {
     client: OpenAI;
     system: string;
     messages: {
@@ -9,6 +9,8 @@ export declare function completeOnce({ client, system, messages, temperature, mo
     }[];
     temperature?: number;
     model?: string;
+    /** Wording for the guardrail refusal; falls back to `DEFAULT_REFUSAL`. */
+    refusal?: string;
 }): Promise<{
     content: string;
     usage: OpenAI.CompletionUsage;

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

@@ -1 +1 @@
-{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../src/core/llm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAGjC,eAAO,MAAM,aAAa,WAAW,CAAC;AAEtC,wBAAsB,YAAY,CAAC,EACjC,MAAM,EACN,MAAM,EACN,QAAQ,EACR,WAAiB,EACjB,KAAqB,GACtB,EAAE;IACD,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;;;GAWA;AAGD,wBAAuB,cAAc,CAAC,EACpC,MAAM,EACN,MAAM,EACN,QAAQ,EACR,WAAiB,EACjB,KAAqB,GACtB,EAAE;IACD,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,yCAYA"}
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../src/core/llm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAGjC,eAAO,MAAM,aAAa,WAAW,CAAC;AAEtC,wBAAsB,YAAY,CAAC,EACjC,MAAM,EACN,MAAM,EACN,QAAQ,EACR,WAAiB,EACjB,KAAqB,EACrB,OAAO,GACR,EAAE;IACD,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;;;GAWA;AAGD,wBAAuB,cAAc,CAAC,EACpC,MAAM,EACN,MAAM,EACN,QAAQ,EACR,WAAiB,EACjB,KAAqB,GACtB,EAAE;IACD,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,yCAYA"}

package/dist/core/retrieval.d.ts

@@ -16,6 +16,13 @@ export declare const DEFAULT_KNOWLEDGE_DIR = "./config/knowledge";
 export interface Retriever {
     /** Retrieve up to `k` chunks across `allowedBuckets` for `query`, most relevant first. */
     query(query: string, k: number, allowedBuckets: string[]): Promise<string[]>;
+    /**
+     * Optional record-returning variant of `query`, for a host that needs to
+     * know where a passage came from (a search route, citations). `prepareChat`
+     * never calls it; implement it only if your own code wants provenance.
+     * Same scoping and ordering rules as `query`.
+     */
+    queryChunks?(query: string, k: number, allowedBuckets: string[]): Promise<RetrievedChunk[]>;
     /**
      * Optional one-time ingest/warm-up step, run once at server startup before
      * the store answers any query. Omit it for a retriever that is always
@@ -23,6 +30,18 @@ export interface Retriever {
      */
     build?(): Promise<void>;
 }
+/** One retrieval result with its provenance. See {@link Retriever.queryChunks}. */
+export interface RetrievedChunk {
+    /** The chunk text alone, without any embedding context line. */
+    text: string;
+    bucket: string;
+    /** Where the chunk came from; knowledgeDir-relative for rows ingested in `'sections'` mode. */
+    source: string;
+    /** Heading trail from the H1 down; empty when the row has none (every `'lines'` row). */
+    section: string[];
+    /** Cosine similarity between the query and the chunk embedding. */
+    score: number;
+}
 /**
  * Embeds a batch of texts into vectors, in input order. Lets
  * {@link VectorStore} stay decoupled from any specific embeddings provider -
@@ -52,6 +71,8 @@ export declare function openLibsqlClient(database: {
     url: string;
     authToken: string;
 }): Promise<LibsqlClient>;
+/** Chunking strategy for {@link VectorStoreOptions.chunking}. */
+export type ChunkingMode = "lines" | "sections";
 /**
  * `VectorStore` always takes an already-open libsql client rather than
  * credentials to open its own - the same rule every other store in this
@@ -68,6 +89,15 @@ export interface VectorStoreOptions {
     databaseClient: LibsqlClient;
     /** Directory of markdown knowledge files. Default: `./config/knowledge` */
     knowledgeDir?: string;
+    /**
+     * How knowledge files are cut into chunks. `'lines'` (default) keeps the
+     * original fixed-size line chunks, so ids and embeddings are unchanged.
+     * `'sections'` cuts at Markdown headings (see
+     * [chunking.ts](./chunking.ts)), records each chunk's heading trail and
+     * position, and embeds it with a `<source> > <heading trail>` context line.
+     * Switching modes re-embeds every chunk once on the next build.
+     */
+    chunking?: ChunkingMode;
     /** Logger for build progress. Default: a console logger writing to stderr. */
     logger?: Logger;
     /**
@@ -92,6 +122,7 @@ export declare class VectorStore implements Retriever {
      */
     readonly db: LibsqlClient;
     private knowledgeDir;
+    private chunking;
     private logger;
     private buildLock;
     private instanceId;
@@ -113,6 +144,12 @@ export declare class VectorStore implements Retriever {
     private renewBuildLock;
     /** The ingest itself. Only ever runs with the build lock held. */
     private buildUnderLock;
+    /**
+     * Adds the nullable `section`/`position` columns to a `chunks` table that
+     * every released version created without them. Checked via table_info so it
+     * is a no-op once present; only `'sections'` mode ever calls it.
+     */
+    private ensureSectionColumns;
     private cleanupStaleChunks;
     private static cosine;
     /**
@@ -126,6 +163,8 @@ export declare class VectorStore implements Retriever {
      * interpolated. An empty list retrieves nothing, and short-circuits before
      * the embedding call.
      */
+    queryChunks(q: string, k?: number, allowed?: string[]): Promise<RetrievedChunk[]>;
+    /** Same results as {@link queryChunks}, as bare text. */
     query(q: string, k?: number, allowed?: string[]): Promise<string[]>;
 }
 //# sourceMappingURL=retrieval.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"retrieval.d.ts","sourceRoot":"","sources":["../../src/core/retrieval.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,aAAa,CAAC;AAErB,OAAO,EAAuB,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAI5D,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAE1D;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,0FAA0F;IAC1F,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7E;;;;OAIG;IACH,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAEhE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAK7D;AAED,2KAA2K;AAC3K,eAAO,MAAM,gCAAgC,QAG4B,CAAC;AAE1E,0MAA0M;AAC1M,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAO5D;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,YAAY,CAAC,CAKxB;AAuBD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,cAAc,EAAE,YAAY,CAAC;IAC7B,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,6FAA6F;IAC7F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2HAA2H;IAC3H,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,WAAY,YAAW,SAAS;IAczC,OAAO,CAAC,KAAK;IAbf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,gBAAgB,CAAS;IAEjC,YACU,KAAK,EAAE,QAAQ,EACvB,OAAO,EAAE,kBAAkB,EAQ5B;IAED;;;;;;;;;;OAUG;IACG,KAAK,kBAyBV;IAED,0FAA0F;IAC1F,OAAO,CAAC,cAAc;IAStB,kEAAkE;YACpD,cAAc;YA8Gd,kBAAkB;IAqChC,OAAO,CAAC,MAAM,CAAC,MAAM;IAYrB;;;;;;;;;;OAUG;IACG,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,SAAI,EAAE,OAAO,GAAE,MAAM,EAAa,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAuB7E;CACF"}
+{"version":3,"file":"retrieval.d.ts","sourceRoot":"","sources":["../../src/core/retrieval.ts"],"names":[],"mappings":"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"}

package/dist/history/index.js

@@ -41,9 +41,10 @@ function detectLeakage(text) {
 function scrubOutput(text) {
   return text.replace(/sk-[A-Za-z0-9]{15,}/g, "[REDACTED]").replace(/AIza[0-9A-Za-z_-]{30,}/g, "[REDACTED]");
 }
-function guardOutput(text) {
+var DEFAULT_REFUSAL = "Sorry, I can't share internal instructions. How else can I help?";
+function guardOutput(text, refusal) {
   if (detectLeakage(text)) {
-    return "Sorry, I can't share internal instructions. How else can I help?";
+    return typeof refusal === "string" && refusal.trim() ? refusal : DEFAULT_REFUSAL;
   }
   return scrubOutput(text);
 }
@@ -55,7 +56,8 @@ async function completeOnce({
   system,
   messages,
   temperature = 0.2,
-  model = DEFAULT_MODEL
+  model = DEFAULT_MODEL,
+  refusal
 }) {
   const res = await client.chat.completions.create({
     model,
@@ -64,19 +66,19 @@ async function completeOnce({
   });
   const text = res.choices[0]?.message?.content ?? "";
   return {
-    content: guardOutput(text),
+    content: guardOutput(text, refusal),
     usage: res.usage || { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 }
   };
 }
 
 // src/core/answer.ts
 var noUsage = () => ({ prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 });
-async function runAnswerFn(answerFn, { system, messages, mode, sender, conversationId }) {
+async function runAnswerFn(answerFn, { system, messages, mode, sender, conversationId }, refusal) {
   const result = await answerFn({ system, messages, mode, sender, conversationId });
   const raw = typeof result === "string" ? result : result?.content;
   const usage = typeof result === "string" ? void 0 : result?.usage;
   return {
-    content: guardOutput(typeof raw === "string" ? raw : ""),
+    content: guardOutput(typeof raw === "string" ? raw : "", refusal),
     usage: usage ?? noUsage()
   };
 }
@@ -89,12 +91,13 @@ async function answerOnce({
   sender,
   conversationId,
   temperature,
-  model
+  model,
+  refusal
 }) {
   if (answerFn) {
-    return runAnswerFn(answerFn, { system, messages, mode, sender, conversationId });
+    return runAnswerFn(answerFn, { system, messages, mode, sender, conversationId }, refusal);
   }
-  return completeOnce({ client, system, messages, temperature, model });
+  return completeOnce({ client, system, messages, temperature, model, refusal });
 }
 
 // src/history/compaction.ts