@diegoaltoworks/chatter 0.29.0 → 0.31.0

package/dist/channels/whatsapp/index.mjs

@@ -410,6 +410,324 @@ function createWhatsAppChannel(config) {
     }
   };
 }
+
+// src/core/guardrails.ts
+function detectLeakage(text) {
+  const flags = [
+    /system prompt/i,
+    /hidden instruction/i,
+    /here (are|is) (my|the) rules/i,
+    /BEGIN SYSTEM PROMPT/i,
+    /tool instructions/i
+  ];
+  return flags.some((rx) => rx.test(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) {
+  if (detectLeakage(text)) {
+    return "Sorry, I can't share internal instructions. How else can I help?";
+  }
+  return scrubOutput(text);
+}
+
+// src/core/llm.ts
+var DEFAULT_MODEL = "gpt-4o";
+async function completeOnce({
+  client,
+  system,
+  messages,
+  temperature = 0.2,
+  model = DEFAULT_MODEL
+}) {
+  const res = await client.chat.completions.create({
+    model,
+    temperature,
+    messages: [{ role: "system", content: system }, ...messages]
+  });
+  const text = res.choices[0]?.message?.content ?? "";
+  return {
+    content: guardOutput(text),
+    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 }) {
+  const result = await answerFn({ system, messages, mode, sender });
+  const raw = typeof result === "string" ? result : result?.content;
+  const usage = typeof result === "string" ? void 0 : result?.usage;
+  return {
+    content: guardOutput(typeof raw === "string" ? raw : ""),
+    usage: usage ?? noUsage()
+  };
+}
+async function answerOnce({
+  answerFn,
+  client,
+  system,
+  messages,
+  mode,
+  sender,
+  temperature,
+  model
+}) {
+  if (answerFn) {
+    return runAnswerFn(answerFn, { system, messages, mode, sender });
+  }
+  return completeOnce({ client, system, messages, temperature, model });
+}
+
+// src/core/buckets.ts
+function defaultBuckets(mode) {
+  return ["base", mode];
+}
+function isIdentified(sender) {
+  return typeof sender === "string" && sender.trim().length > 0;
+}
+function normalize(buckets) {
+  const out = [];
+  for (const raw of buckets) {
+    if (typeof raw !== "string") continue;
+    const bucket = raw.trim();
+    if (bucket && !out.includes(bucket)) out.push(bucket);
+  }
+  return out;
+}
+async function resolveBuckets({
+  mode,
+  sender,
+  bucketsFor
+}) {
+  if (!bucketsFor) return void 0;
+  const identified = isIdentified(sender);
+  const requested = await bucketsFor(identified ? { mode, sender } : { mode });
+  if (!Array.isArray(requested)) return void 0;
+  const cleaned = normalize(requested);
+  if (identified) return cleaned;
+  const ceiling = new Set(defaultBuckets(mode));
+  return cleaned.filter((bucket) => ceiling.has(bucket));
+}
+
+// src/core/pipeline.ts
+var MODE_SETTINGS = {
+  public: { topK: 6, label: "Context" },
+  private: { topK: 8, label: "Internal Context" }
+};
+async function prepareChat({
+  store,
+  prompts,
+  mode,
+  messages,
+  personaLayer,
+  channelHint,
+  buckets
+}) {
+  const lastUserMsg = [...messages].reverse().find((m) => m.role === "user");
+  if (!lastUserMsg) {
+    throw new Error("no user message found in conversation");
+  }
+  const { topK, label } = MODE_SETTINGS[mode];
+  const ctx = await store.query(lastUserMsg.content, topK, buckets ?? defaultBuckets(mode));
+  const persona = personaLayer?.trim() || (mode === "private" ? prompts.privatePersona : prompts.publicPersona);
+  const hint = channelHint?.trim();
+  const system = [
+    prompts.baseSystemRules,
+    persona,
+    ...hint ? [hint] : [],
+    `${label}:
+${ctx.join("\n\n")}`
+  ].join("\n\n");
+  return { system, messages };
+}
+
+// src/channels/gates.ts
+function matches(re, text) {
+  return new RegExp(re.source, re.flags.replace(/[gy]/g, "")).test(text);
+}
+function decideChannelAction(msg, config) {
+  if (msg.fromBot || !msg.text.trim()) return "ignore";
+  if (!msg.isDirectMessage) {
+    if (config.allowedChats.length > 0 && !config.allowedChats.includes(msg.chatId)) {
+      return "ignore";
+    }
+    if (config.muteRegex && matches(config.muteRegex, msg.text)) return "mute";
+    if (config.unmuteRegex && matches(config.unmuteRegex, msg.text)) return "unmute";
+    if (config.mutedChats.has(msg.chatId)) return "ignore";
+    return msg.mentionsBot || msg.isReplyToBot ? "reply" : "ignore";
+  }
+  return "reply";
+}
+function createSlidingWindowRateLimiter(maxPerWindow, windowMs, now = Date.now) {
+  const log = /* @__PURE__ */ new Map();
+  return function allow(key) {
+    const cutoff = now() - windowMs;
+    const entries = (log.get(key) ?? []).filter((t) => t > cutoff);
+    if (entries.length >= maxPerWindow) {
+      if (entries.length > 0) log.set(key, entries);
+      else log.delete(key);
+      return false;
+    }
+    entries.push(now());
+    log.set(key, entries);
+    return true;
+  };
+}
+function underReplyRateLimit(msg, limiters) {
+  return msg.isDirectMessage ? limiters.dm(msg.chatId) : limiters.group(msg.chatId);
+}
+function isFromAnySession(id, registry) {
+  if (!id) return false;
+  for (const ids of registry.values()) {
+    if (ids.includes(id)) return true;
+  }
+  return false;
+}
+function isEffectivelyFromSelf(msg, registry) {
+  return msg.fromBot || isFromAnySession(msg.senderId, registry);
+}
+
+// src/channels/whatsapp/inbound.ts
+function isGroupJid(jid) {
+  return jid.endsWith("@g.us");
+}
+function jidsMatch(a, b) {
+  if (!a || !b) return false;
+  const bare = (jid) => jid.split("@")[0]?.split(":")[0] ?? jid;
+  return bare(a) === bare(b);
+}
+function jidToPhoneNumber(jid) {
+  const bare = jid.split("@")[0]?.split(":")[0] ?? "";
+  return bare.startsWith("+") ? bare : `+${bare}`;
+}
+function normalizeJid(jid) {
+  const [user = "", domain] = jid.split("@");
+  const bareUser = user.split(":")[0] ?? user;
+  return domain ? `${bareUser}@${domain}` : bareUser;
+}
+async function senderPhoneFor(sock, message, chatJid) {
+  const key = message.key;
+  let jid = [key.participantPn, key.senderPn, key.participant, key.remoteJidAlt, chatJid].find(
+    (candidate) => typeof candidate === "string" && candidate.length > 0
+  ) ?? chatJid;
+  if (jid.endsWith("@lid")) {
+    try {
+      const mapped = await sock.signalRepository?.lidMapping?.getPNForLID?.(jid);
+      if (mapped) jid = mapped;
+    } catch {
+    }
+  }
+  return jid.endsWith("@lid") ? `lid:${jid.split("@")[0]?.split(":")[0] ?? jid}` : jidToPhoneNumber(jid);
+}
+function messageContext(message) {
+  const content = message.message;
+  const contextInfo = content?.extendedTextMessage?.contextInfo ?? content?.imageMessage?.contextInfo ?? content?.videoMessage?.contextInfo ?? content?.documentMessage?.contextInfo;
+  return {
+    mentionedJids: contextInfo?.mentionedJid ?? [],
+    quotedParticipantJid: contextInfo?.participant ?? void 0
+  };
+}
+function extractText(message) {
+  const content = message.message;
+  if (!content) return "";
+  return content.conversation ?? content.extendedTextMessage?.text ?? content.imageMessage?.caption ?? content.videoMessage?.caption ?? content.documentMessage?.caption ?? "";
+}
+var DEFAULT_GROUP_RATE_LIMIT = { max: 30, windowMs: 60 * 60 * 1e3 };
+var DEFAULT_DM_RATE_LIMIT = { max: 20, windowMs: 60 * 60 * 1e3 };
+async function resolvePersonaLayer(config, ctx) {
+  if (!config.personaResolver) return void 0;
+  try {
+    return await config.personaResolver(ctx);
+  } catch {
+    return void 0;
+  }
+}
+function createWhatsAppInboundHandler(config) {
+  const mutedChats = /* @__PURE__ */ new Set();
+  const now = config.now ?? Date.now;
+  const group = config.groupRateLimit ?? DEFAULT_GROUP_RATE_LIMIT;
+  const dm = config.dmRateLimit ?? DEFAULT_DM_RATE_LIMIT;
+  const underGroupRateLimit = createSlidingWindowRateLimiter(group.max, group.windowMs, now);
+  const underDmRateLimit = createSlidingWindowRateLimiter(dm.max, dm.windowMs, now);
+  return async function handleWhatsAppMessage(event) {
+    const { sessionId, sock, message } = event;
+    try {
+      const chatId = message.key.remoteJid ?? "";
+      if (!chatId || chatId === "status@broadcast") return;
+      const text = extractText(message);
+      const context = messageContext(message);
+      const senderId = message.key.participant ?? chatId;
+      const ownIds = [sock.user?.id, sock.user?.lid].filter((id) => Boolean(id)).map(normalizeJid);
+      config.registry.set(sessionId, ownIds);
+      const fromBot = isEffectivelyFromSelf(
+        { fromBot: message.key.fromMe ?? false, senderId: normalizeJid(senderId) },
+        config.registry
+      );
+      const msg = {
+        chatId,
+        senderId,
+        text,
+        isDirectMessage: !isGroupJid(chatId),
+        mentionsBot: context.mentionedJids.some((jid) => ownIds.some((own) => jidsMatch(jid, own))),
+        isReplyToBot: ownIds.some((own) => jidsMatch(context.quotedParticipantJid, own)),
+        fromBot
+      };
+      const action = decideChannelAction(msg, {
+        allowedChats: config.allowedChats ?? [],
+        mutedChats,
+        muteRegex: config.muteRegex,
+        unmuteRegex: config.unmuteRegex
+      });
+      if (action === "mute") {
+        mutedChats.add(chatId);
+        if (config.muteReply) await sock.sendMessage(chatId, { text: config.muteReply });
+        return;
+      }
+      if (action === "unmute") {
+        mutedChats.delete(chatId);
+        if (config.unmuteReply) await sock.sendMessage(chatId, { text: config.unmuteReply });
+        return;
+      }
+      if (action !== "reply") return;
+      if (!underReplyRateLimit(msg, { dm: underDmRateLimit, group: underGroupRateLimit })) {
+        return;
+      }
+      const senderPhone = await senderPhoneFor(sock, message, chatId);
+      const personaLayer = await resolvePersonaLayer(config, { senderPhone, text });
+      const buckets = await resolveBuckets({
+        mode: "public",
+        sender: senderPhone,
+        bucketsFor: config.bucketsFor
+      });
+      const messages = [{ role: "user", content: text }];
+      const { system } = await prepareChat({
+        store: config.store,
+        prompts: config.prompts,
+        mode: "public",
+        messages,
+        personaLayer,
+        channelHint: config.channelHint,
+        buckets
+      });
+      const { content } = await answerOnce({
+        answerFn: config.answerFn,
+        client: config.client,
+        system,
+        messages,
+        mode: "public",
+        sender: senderPhone,
+        model: config.model
+      });
+      if (content) {
+        await sock.sendMessage(chatId, { text: content }, { quoted: message });
+      }
+    } catch (error) {
+      console.warn(`WhatsApp[${sessionId}]: inbound message handling failed:`, error);
+    }
+  };
+}
 export {
   LEASE_HEARTBEAT_MS,
   LEASE_STALE_MS,
@@ -418,11 +736,18 @@ export {
   canAcquireLease,
   createTursoWaLeaseStore,
   createWhatsAppChannel,
+  createWhatsAppInboundHandler,
   decrypt,
   encrypt,
+  extractText,
+  isGroupJid,
+  jidToPhoneNumber,
+  jidsMatch,
   loadBaileys,
+  messageContext,
   reconnectDelayMs,
   senderNameFor,
+  senderPhoneFor,
   shutdownWaSessions,
   useTursoAuthState
 };

package/dist/personas/greeter.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Named greetings for known contacts — rides the same persona window as the
+ * chat that follows, so a call greeted in one persona/language continues in
+ * it. Ships no content: templates are entirely caller-supplied.
+ */
+import type { PersonaResolver } from "./resolver";
+export interface GreeterOptions {
+    resolver: PersonaResolver;
+    /** Greeting templates keyed by persona id, each containing a `{name}` placeholder. */
+    templates: Record<string, readonly string[]>;
+    /** Injectable randomness for tests. Default `Math.random`. */
+    random?: () => number;
+}
+export interface Greeter {
+    /** A named greeting for a known contact in their current persona, or null (unknown contact, or no template pool for that persona). */
+    greet(contactId: string): string | null;
+}
+export declare function createGreeter({ resolver, templates, random, }: GreeterOptions): Greeter;
+//# sourceMappingURL=greeter.d.ts.map

package/dist/personas/greeter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"greeter.d.ts","sourceRoot":"","sources":["../../src/personas/greeter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,eAAe,CAAC;IAC1B,sFAAsF;IACtF,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;IAC7C,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,OAAO;IACtB,sIAAsI;IACtI,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACzC;AAMD,wBAAgB,aAAa,CAAC,EAC5B,QAAQ,EACR,SAAS,EACT,MAAoB,GACrB,EAAE,cAAc,GAAG,OAAO,CAmB1B"}

package/dist/personas/greeter.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=greeter.test.d.ts.map

package/dist/personas/greeter.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"greeter.test.d.ts","sourceRoot":"","sources":["../../src/personas/greeter.test.ts"],"names":[],"mappings":""}

package/dist/personas/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Persona machinery — dynamic prompt layers and named greetings driven by a
+ * JSON registry. Published as the `@diegoaltoworks/chatter/personas` subpath
+ * so the core install stays untouched by it; this module adds no required
+ * dependencies.
+ *
+ * @packageDocumentation
+ */
+export type { Greeter, GreeterOptions } from "./greeter";
+export { createGreeter } from "./greeter";
+export type { PersonaContact, PersonaDefinition, PersonaRegistry, PersonaResolver, PersonaResolverOptions, } from "./resolver";
+export { createPersonaResolver } from "./resolver";
+export { timeContext } from "./timeContext";
+//# sourceMappingURL=index.d.ts.map

package/dist/personas/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/personas/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,sBAAsB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/personas/index.js

@@ -0,0 +1,206 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/personas/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createGreeter: () => createGreeter,
+  createPersonaResolver: () => createPersonaResolver,
+  timeContext: () => timeContext
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/personas/greeter.ts
+function capitalize(name) {
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+function createGreeter({
+  resolver,
+  templates,
+  random = Math.random
+}) {
+  return {
+    greet(contactId) {
+      try {
+        const contact = resolver.contactFor(contactId);
+        if (!contact?.name) return null;
+        const personaId = resolver.rollPersonaId(contactId) ?? resolver.defaultPersonaId();
+        const pool = personaId ? templates[personaId] : void 0;
+        if (!pool || pool.length === 0) return null;
+        const template = pool[Math.floor(random() * pool.length)];
+        if (!template) return null;
+        return template.replaceAll("{name}", capitalize(contact.name));
+      } catch {
+        return null;
+      }
+    }
+  };
+}
+
+// src/personas/resolver.ts
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+var DEFAULT_WINDOW_MINUTES = 10;
+var DEFAULT_PROBABILITY = 0.5;
+function interpolate(template, vars) {
+  return Object.entries(vars).reduce(
+    (acc, [key, value]) => acc.replaceAll(`{{${key}}}`, value),
+    template
+  );
+}
+function createPersonaResolver(options = {}) {
+  if (!options.registry && !options.registryPath) {
+    throw new Error("createPersonaResolver requires a registry or registryPath");
+  }
+  const random = options.random ?? Math.random;
+  const now = options.now ?? Date.now;
+  const vars = options.vars ?? {};
+  const promptsDir = options.promptsDir ?? (options.registryPath ? (0, import_node_path.dirname)(options.registryPath) : process.cwd());
+  let registry = options.registry;
+  let registryLoadError;
+  const promptCache = /* @__PURE__ */ new Map();
+  const window = /* @__PURE__ */ new Map();
+  const warned = /* @__PURE__ */ new Set();
+  function warnOnce(kind, message, error) {
+    if (warned.has(kind)) return;
+    warned.add(kind);
+    console.warn(message, error);
+  }
+  function loadRegistry() {
+    if (registry) return registry;
+    if (registryLoadError !== void 0) throw registryLoadError;
+    try {
+      registry = JSON.parse((0, import_node_fs.readFileSync)(options.registryPath, "utf-8"));
+      return registry;
+    } catch (error) {
+      registryLoadError = error;
+      warnOnce(
+        "registry",
+        `Persona registry load failed (${options.registryPath}); falling back to the default persona for every contact.`,
+        error
+      );
+      throw error;
+    }
+  }
+  function contactFor(contactId) {
+    try {
+      return loadRegistry().contacts?.[contactId];
+    } catch {
+      return void 0;
+    }
+  }
+  function rollPersonaId(contactId) {
+    try {
+      const reg = loadRegistry();
+      const nowMs = now();
+      const existing = window.get(contactId);
+      if (existing && existing.expiresAt > nowMs) {
+        return existing.personaId;
+      }
+      for (const [key, value] of window) {
+        if (value.expiresAt <= nowMs) window.delete(key);
+      }
+      const contact = reg.contacts?.[contactId];
+      let personaId = null;
+      const probability = contact?.probability ?? reg.personaProbability ?? DEFAULT_PROBABILITY;
+      if (contact && random() < probability) {
+        personaId = contact.persona === reg.defaultPersona ? null : contact.persona;
+      }
+      const windowMs = (reg.personaWindowMinutes ?? DEFAULT_WINDOW_MINUTES) * 60 * 1e3;
+      window.set(contactId, { personaId, expiresAt: nowMs + windowMs });
+      return personaId;
+    } catch {
+      return null;
+    }
+  }
+  function personaLayerFor(personaId) {
+    if (!personaId) return null;
+    try {
+      const definition = loadRegistry().personas[personaId];
+      if (!definition) return null;
+      if (promptCache.has(personaId)) return promptCache.get(personaId) ?? null;
+      try {
+        const prompt = interpolate(
+          (0, import_node_fs.readFileSync)((0, import_node_path.resolve)(promptsDir, definition.prompt), "utf-8"),
+          vars
+        );
+        promptCache.set(personaId, prompt);
+        return prompt;
+      } catch (error) {
+        promptCache.set(personaId, null);
+        warnOnce(
+          `prompt:${personaId}`,
+          `Persona prompt load failed for "${personaId}" (${definition.prompt}); falling back to the default persona.`,
+          error
+        );
+        return null;
+      }
+    } catch {
+      return null;
+    }
+  }
+  function defaultPersonaId() {
+    try {
+      return loadRegistry().defaultPersona ?? null;
+    } catch {
+      return null;
+    }
+  }
+  function resolvePersonaLayer(contactId) {
+    return personaLayerFor(rollPersonaId(contactId)) ?? personaLayerFor(defaultPersonaId());
+  }
+  return {
+    rollPersonaId,
+    resolvePersonaLayer,
+    personaLayerFor,
+    contactFor,
+    defaultPersonaId
+  };
+}
+
+// src/personas/timeContext.ts
+function timeContext(zones, now = Date.now()) {
+  if (zones.length === 0) return "";
+  const at = new Date(now);
+  const parts = zones.flatMap((zone) => {
+    try {
+      const formatted = new Intl.DateTimeFormat("en-GB", {
+        timeZone: zone,
+        weekday: "long",
+        day: "numeric",
+        month: "long",
+        year: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+        hour12: false
+      }).format(at);
+      return [`${formatted} (${zone})`];
+    } catch {
+      return [];
+    }
+  });
+  if (parts.length === 0) return "";
+  return `Current date and time: ${parts.join(" / ")}.`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createGreeter,
+  createPersonaResolver,
+  timeContext
+});