@diegoaltoworks/chatter 1.0.0 → 2.1.0

package/dist/mcp-server.mjs

@@ -92,6 +92,126 @@ var init_buildLock = __esm({
   }
 });
 
+// src/core/chunking.ts
+function headingOf(line) {
+  const match = HEADING.exec(line);
+  if (!match) return void 0;
+  const title = (match[2] ?? "").replace(/[ \t]+#+$/, "").replace(/^#+$/, "").trim();
+  return { level: match[1].length, title };
+}
+function startsTable(lines, i) {
+  return lines[i].includes("|") && i + 1 < lines.length && TABLE_DELIMITER.test(lines[i + 1]);
+}
+function fenceEnd(lines, start) {
+  const opener = FENCE.exec(lines[start]);
+  if (!opener) return start + 1;
+  const marker = opener[1];
+  const closer = new RegExp(`^ {0,3}${marker[0] === "`" ? "`" : "~"}{${marker.length},}[ \\t]*$`);
+  for (let i = start + 1; i < lines.length; i++) if (closer.test(lines[i])) return i + 1;
+  return lines.length;
+}
+function listEnd(lines, start) {
+  let end = start + 1;
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (isBlank(line)) {
+      let next = i + 1;
+      while (next < lines.length && isBlank(lines[next])) next++;
+      if (next < lines.length && (LIST_ITEM.test(lines[next]) || isIndented(lines[next]))) {
+        i = next - 1;
+        continue;
+      }
+      break;
+    }
+    if (headingOf(line) && !isIndented(line)) break;
+    if (FENCE.test(line) && !isIndented(line)) break;
+    end = i + 1;
+  }
+  return end;
+}
+function tableEnd(lines, start) {
+  let end = start + 2;
+  while (end < lines.length && !isBlank(lines[end]) && lines[end].includes("|")) end++;
+  return end;
+}
+function paragraphEnd(lines, start) {
+  let end = start + 1;
+  while (end < lines.length && !isBlank(lines[end]) && !headingOf(lines[end]) && !FENCE.test(lines[end]) && !LIST_ITEM.test(lines[end])) {
+    end++;
+  }
+  return end;
+}
+function scan(text) {
+  const lines = text.replace(/\r\n?/g, "\n").split("\n");
+  const sections = [{ trail: [], blocks: [] }];
+  const stack = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (isBlank(line)) {
+      i++;
+      continue;
+    }
+    const heading = FENCE.test(line) ? void 0 : headingOf(line);
+    if (heading) {
+      while (stack.length && stack[stack.length - 1].level >= heading.level) stack.pop();
+      stack.push(heading);
+      sections.push({ trail: stack.map((h) => h.title), heading: line, blocks: [] });
+      i++;
+      continue;
+    }
+    let end;
+    if (FENCE.test(line)) end = fenceEnd(lines, i);
+    else if (LIST_ITEM.test(line)) end = listEnd(lines, i);
+    else if (startsTable(lines, i)) end = tableEnd(lines, i);
+    else end = paragraphEnd(lines, i);
+    sections[sections.length - 1].blocks.push({ lines: lines.slice(i, end) });
+    i = end;
+  }
+  return sections;
+}
+function chunkSections(text, max = 900) {
+  const cap = Math.max(1, max);
+  const out = [];
+  const emit = (parts, section) => {
+    const body = parts.join("\n\n");
+    if (body.trim() === "") return;
+    out.push({ text: body, section: [...section], position: out.length });
+  };
+  for (const section of scan(text)) {
+    let parts = section.heading ? [section.heading.trim()] : [];
+    let size = parts.join("\n\n").length;
+    let hasBlock = false;
+    for (const block of section.blocks) {
+      const piece = block.lines.join("\n");
+      const added = piece.length + (parts.length ? 2 : 0);
+      if (hasBlock && size + added > cap) {
+        emit(parts, section.trail);
+        parts = [];
+        size = 0;
+        hasBlock = false;
+      }
+      size += piece.length + (parts.length ? 2 : 0);
+      parts.push(piece);
+      hasBlock = true;
+    }
+    emit(parts, section.trail);
+  }
+  return out;
+}
+var FENCE, HEADING, LIST_ITEM, TABLE_DELIMITER, isBlank, isIndented;
+var init_chunking = __esm({
+  "src/core/chunking.ts"() {
+    "use strict";
+    FENCE = /^ {0,3}(`{3,}|~{3,})/;
+    HEADING = /^ {0,3}(#{1,6})(?:[ \t]+(.*?))?[ \t]*$/;
+    LIST_ITEM = /^[ \t]*(?:[-*+]|\d{1,9}[.)])[ \t]+\S/;
+    TABLE_DELIMITER = /^[ \t]*\|?[ \t]*:?-+:?[ \t]*(?:\|[ \t]*:?-+:?[ \t]*)*\|?[ \t]*$/;
+    isBlank = (line) => line.trim() === "";
+    isIndented = (line) => /^(?: {2,}|\t)/.test(line);
+  }
+});
+
 // src/core/loaders.ts
 import { readdirSync, readFileSync as readFileSync2, statSync } from "node:fs";
 import { join as join2 } from "node:path";
@@ -134,6 +254,7 @@ __export(retrieval_exports, {
   openLibsqlClient: () => openLibsqlClient,
   wrapMissingLibsqlError: () => wrapMissingLibsqlError
 });
+import { relative, sep } from "node:path";
 function createOpenAIEmbedder(client) {
   return async (input) => {
     const res = await client.embeddings.create({ model: EMB_MODEL, input });
@@ -176,6 +297,7 @@ var init_retrieval = __esm({
   "src/core/retrieval.ts"() {
     "use strict";
     init_buildLock();
+    init_chunking();
     init_loaders();
     init_logger();
     EMB_MODEL = "text-embedding-3-large";
@@ -186,6 +308,7 @@ var init_retrieval = __esm({
         this.embed = embed;
         this.db = options.databaseClient;
         this.knowledgeDir = options.knowledgeDir || DEFAULT_KNOWLEDGE_DIR;
+        this.chunking = options.chunking ?? "lines";
         this.logger = options.logger ?? createConsoleLogger();
         this.buildLock = options.buildLock ?? createTursoBuildLock(this.db);
         this.instanceId = options.instanceId ?? crypto.randomUUID();
@@ -199,6 +322,7 @@ var init_retrieval = __esm({
        */
       db;
       knowledgeDir;
+      chunking;
       logger;
       buildLock;
       instanceId;
@@ -259,11 +383,41 @@ var init_retrieval = __esm({
           this.logger.info("No knowledge documents and no existing chunks - nothing to build");
           return;
         }
+        this.logger.info(`Chunking mode: ${this.chunking}`);
+        if (this.chunking === "sections") await this.ensureSectionColumns();
         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 });
+          if (this.chunking === "sections") {
+            const source = relative(this.knowledgeDir, d.source).split(sep).join("/");
+            for (const c of chunkSections(d.text)) {
+              const section = c.section.join(" > ");
+              const id = await sha256(`${d.bucket}|${source}|${section}|${c.text}`);
+              const context = section ? `${source} > ${section}` : source;
+              rows.push({
+                id,
+                bucket: d.bucket,
+                source,
+                text: c.text,
+                embedText: `${context}
+
+${c.text}`,
+                section,
+                position: c.position
+              });
+            }
+          } else {
+            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,
+                embedText: part,
+                section: null,
+                position: null
+              });
+            }
           }
         }
         this.logger.info(`Created ${rows.length} chunks from knowledge documents`);
@@ -272,11 +426,17 @@ var init_retrieval = __esm({
         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]
-            })),
+            batch.map(
+              (r) => this.chunking === "sections" ? {
+                sql: `INSERT INTO chunks(id,bucket,source,text,section,position) VALUES(?,?,?,?,?,?)
+                      ON CONFLICT(id) DO NOTHING`,
+                args: [r.id, r.bucket, r.source, r.text, r.section, r.position]
+              } : {
+                sql: `INSERT INTO chunks(id,bucket,source,text) VALUES(?,?,?,?)
+                      ON CONFLICT(id) DO NOTHING`,
+                args: [r.id, r.bucket, r.source, r.text]
+              }
+            ),
             "write"
           );
         }
@@ -297,7 +457,7 @@ var init_retrieval = __esm({
           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 textById = new Map(rows.map((r) => [r.id, r.embedText]));
         const BATCH = 96;
         for (let i = 0; i < missing.length; i += BATCH) {
           const batchIds = missing.slice(i, i + BATCH);
@@ -318,6 +478,18 @@ var init_retrieval = __esm({
         }
         this.logger.info(`Successfully embedded ${missing.length} new chunks`);
       }
+      /**
+       * 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.
+       */
+      async ensureSectionColumns() {
+        const info = await this.db.execute("PRAGMA table_info(chunks)");
+        const have = new Set(info.rows.map((r) => String(r.name)));
+        if (!have.has("section")) await this.db.execute("ALTER TABLE chunks ADD COLUMN section TEXT");
+        if (!have.has("position"))
+          await this.db.execute("ALTER TABLE chunks ADD COLUMN position INTEGER");
+      }
       // Remove chunks from database that no longer exist in markdown files
       async cleanupStaleChunks(currentIds) {
         const result = await this.db.execute("SELECT id FROM chunks");
@@ -364,25 +536,34 @@ var init_retrieval = __esm({
        * interpolated. An empty list retrieves nothing, and short-circuits before
        * the embedding call.
        */
-      async query(q, k = 6, allowed = ["base"]) {
+      async queryChunks(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
+          sql: `SELECT c.*, 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 scored = res.rows.map((row) => {
           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);
+          const trail = row.section == null ? "" : String(row.section);
+          return {
+            text: String(row.text),
+            bucket: String(row.bucket ?? ""),
+            source: String(row.source ?? ""),
+            section: trail ? trail.split(" > ") : [],
+            score: _VectorStore.cosine(qv, emb)
+          };
+        });
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, k);
+      }
+      /** Same results as {@link queryChunks}, as bare text. */
+      async query(q, k = 6, allowed = ["base"]) {
+        return (await this.queryChunks(q, k, allowed)).map((c) => c.text);
       }
     };
   }
@@ -518,9 +699,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);
 }
@@ -532,7 +714,8 @@ async function completeOnce({
   system,
   messages,
   temperature = 0.2,
-  model = DEFAULT_MODEL
+  model = DEFAULT_MODEL,
+  refusal
 }) {
   const res = await client.chat.completions.create({
     model,
@@ -541,19 +724,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()
   };
 }
@@ -566,12 +749,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;
@@ -1001,6 +1185,7 @@ async function createMCPServer(config) {
     store = new VectorStore2(createOpenAIEmbedder2(client), {
       databaseClient: db,
       knowledgeDir: config.knowledgeDir || DEFAULT_KNOWLEDGE_DIR2,
+      chunking: config.chunking,
       logger: log
     });
   }
@@ -1072,7 +1257,8 @@ async function createMCPServer(config) {
           messages: conversationMessages,
           mode: "public",
           conversationId: convId,
-          model
+          model,
+          refusal: config.refusal
         });
         const replyText = await applyTransformReply(
           config.transformReply,
@@ -1162,7 +1348,8 @@ async function createMCPServer(config) {
           messages: conversationMessages,
           mode: "private",
           conversationId: convId,
-          model
+          model,
+          refusal: config.refusal
         });
         const replyText = await applyTransformReply(
           config.transformReply,

package/dist/personas/index.d.ts

@@ -8,7 +8,7 @@
  */
 export type { Greeter, GreeterOptions } from "./greeter";
 export { createGreeter } from "./greeter";
-export type { PersonaContact, PersonaDefinition, PersonaRegistry, PersonaResolver, PersonaResolverOptions, } from "./resolver";
+export type { PersonaContact, PersonaDefinition, PersonaEndpoint, PersonaKey, 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

@@ -1 +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"}
+{"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,UAAU,EACV,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

@@ -124,7 +124,19 @@ function createPersonaResolver(options = {}) {
       return void 0;
     }
   }
-  function rollPersonaId(contactId) {
+  function endpointPersonaId(endpointId) {
+    if (!endpointId) return null;
+    try {
+      return loadRegistry().endpoints?.[endpointId]?.persona ?? null;
+    } catch {
+      return null;
+    }
+  }
+  function rollPersonaId(key) {
+    const { contactId, endpointId } = typeof key === "string" ? { contactId: key } : key;
+    const boundToEndpoint = endpointPersonaId(endpointId);
+    if (boundToEndpoint) return boundToEndpoint;
+    if (contactId === void 0) return null;
     try {
       const reg = loadRegistry();
       const nowMs = now();
@@ -132,8 +144,8 @@ function createPersonaResolver(options = {}) {
       if (existing && existing.expiresAt > nowMs) {
         return existing.personaId;
       }
-      for (const [key, value] of window) {
-        if (value.expiresAt <= nowMs) window.delete(key);
+      for (const [held, value] of window) {
+        if (value.expiresAt <= nowMs) window.delete(held);
       }
       const contact = reg.contacts?.[contactId];
       let personaId = null;
@@ -181,8 +193,8 @@ function createPersonaResolver(options = {}) {
       return null;
     }
   }
-  function resolvePersonaLayer(contactId) {
-    return personaLayerFor(rollPersonaId(contactId)) ?? personaLayerFor(defaultPersonaId());
+  function resolvePersonaLayer(key) {
+    return personaLayerFor(rollPersonaId(key)) ?? personaLayerFor(defaultPersonaId());
   }
   return {
     rollPersonaId,
@@ -199,7 +211,7 @@ function timeContext(zones, now = Date.now()) {
   const at = new Date(now);
   const parts = zones.flatMap((zone) => {
     try {
-      const formatted = new Intl.DateTimeFormat("en-GB", {
+      const fields = new Intl.DateTimeFormat("en-GB", {
         timeZone: zone,
         weekday: "long",
         day: "numeric",
@@ -208,7 +220,9 @@ function timeContext(zones, now = Date.now()) {
         hour: "2-digit",
         minute: "2-digit",
         hour12: false
-      }).format(at);
+      }).formatToParts(at);
+      const part = (type) => fields.find((field) => field.type === type)?.value ?? "";
+      const formatted = `${part("weekday")} ${part("day")} ${part("month")} ${part("year")} at ${part("hour")}:${part("minute")}`;
       return [`${formatted} (${zone})`];
     } catch {
       return [];

package/dist/personas/index.mjs

@@ -96,7 +96,19 @@ function createPersonaResolver(options = {}) {
       return void 0;
     }
   }
-  function rollPersonaId(contactId) {
+  function endpointPersonaId(endpointId) {
+    if (!endpointId) return null;
+    try {
+      return loadRegistry().endpoints?.[endpointId]?.persona ?? null;
+    } catch {
+      return null;
+    }
+  }
+  function rollPersonaId(key) {
+    const { contactId, endpointId } = typeof key === "string" ? { contactId: key } : key;
+    const boundToEndpoint = endpointPersonaId(endpointId);
+    if (boundToEndpoint) return boundToEndpoint;
+    if (contactId === void 0) return null;
     try {
       const reg = loadRegistry();
       const nowMs = now();
@@ -104,8 +116,8 @@ function createPersonaResolver(options = {}) {
       if (existing && existing.expiresAt > nowMs) {
         return existing.personaId;
       }
-      for (const [key, value] of window) {
-        if (value.expiresAt <= nowMs) window.delete(key);
+      for (const [held, value] of window) {
+        if (value.expiresAt <= nowMs) window.delete(held);
       }
       const contact = reg.contacts?.[contactId];
       let personaId = null;
@@ -153,8 +165,8 @@ function createPersonaResolver(options = {}) {
       return null;
     }
   }
-  function resolvePersonaLayer(contactId) {
-    return personaLayerFor(rollPersonaId(contactId)) ?? personaLayerFor(defaultPersonaId());
+  function resolvePersonaLayer(key) {
+    return personaLayerFor(rollPersonaId(key)) ?? personaLayerFor(defaultPersonaId());
   }
   return {
     rollPersonaId,
@@ -171,7 +183,7 @@ function timeContext(zones, now = Date.now()) {
   const at = new Date(now);
   const parts = zones.flatMap((zone) => {
     try {
-      const formatted = new Intl.DateTimeFormat("en-GB", {
+      const fields = new Intl.DateTimeFormat("en-GB", {
         timeZone: zone,
         weekday: "long",
         day: "numeric",
@@ -180,7 +192,9 @@ function timeContext(zones, now = Date.now()) {
         hour: "2-digit",
         minute: "2-digit",
         hour12: false
-      }).format(at);
+      }).formatToParts(at);
+      const part = (type) => fields.find((field) => field.type === type)?.value ?? "";
+      const formatted = `${part("weekday")} ${part("day")} ${part("month")} ${part("year")} at ${part("hour")}:${part("minute")}`;
       return [`${formatted} (${zone})`];
     } catch {
       return [];

package/dist/personas/resolver.d.ts

@@ -20,6 +20,14 @@ export interface PersonaContact {
     /** Overrides `personaProbability` for this contact when set. */
     probability?: number;
 }
+/**
+ * A persona bound to one of the bot's own endpoints - which of its numbers,
+ * tokens or rooms the message arrived on, rather than who sent it.
+ */
+export interface PersonaEndpoint {
+    /** Persona id this endpoint always answers as. */
+    persona: string;
+}
 export interface PersonaRegistry {
     /** Persona id used when a contact is unmapped or its roll doesn't land. */
     defaultPersona: string;
@@ -28,8 +36,23 @@ export interface PersonaRegistry {
     /** Minutes a roll is held before the next message re-rolls it. Default 10. */
     personaWindowMinutes?: number;
     contacts?: Record<string, PersonaContact>;
+    /**
+     * Personas keyed on the endpoint that received the message
+     * (`ChannelMessage.endpointId`), for a bot whose voice is decided by which
+     * of its own identities was reached rather than by who reached it.
+     */
+    endpoints?: Record<string, PersonaEndpoint>;
     personas: Record<string, PersonaDefinition>;
 }
+/**
+ * Who a persona is resolved for. A bare string is the contact id, which is
+ * every call that predates endpoint keying; the object form adds the endpoint
+ * the message arrived on, and either half may be omitted.
+ */
+export type PersonaKey = string | {
+    contactId?: string;
+    endpointId?: string;
+};
 export interface PersonaResolverOptions {
     /** Inline registry — takes priority over `registryPath` when both are set. */
     registry?: PersonaRegistry;
@@ -48,17 +71,21 @@ export interface PersonaResolverOptions {
 }
 export interface PersonaResolver {
     /**
-     * The persona id in effect for a contact right now: rolled at
-     * `personaProbability` once per window, held for `personaWindowMinutes`.
-     * `null` means "use the default persona" (unmapped contact or a lost roll).
+     * The persona id in effect right now. A key naming an endpoint that the
+     * registry binds resolves to that persona deterministically - no roll, no
+     * window - because an endpoint-bound voice is a property of the identity
+     * reached, not something that varies over a conversation. Otherwise the
+     * contact is rolled at `personaProbability` once per window and held for
+     * `personaWindowMinutes`. `null` means "use the default persona" (no key,
+     * an unmapped contact, or a lost roll).
      */
-    rollPersonaId(contactId: string): string | null;
+    rollPersonaId(key: PersonaKey): string | null;
     /**
-     * The interpolated prompt layer for the contact's currently-held persona,
-     * falling back to the default persona's layer. Feeds `prepareChat`'s
-     * `personaLayer` directly.
+     * The interpolated prompt layer for the persona {@link rollPersonaId}
+     * yields, falling back to the default persona's layer. Feeds
+     * `prepareChat`'s `personaLayer` directly.
      */
-    resolvePersonaLayer(contactId: string): string | null;
+    resolvePersonaLayer(key: PersonaKey): string | null;
     /** Deterministic layer for an explicit persona id (no dice roll), or null. */
     personaLayerFor(personaId: string | null): string | null;
     /** Registry contact record, or undefined. */

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

@@ -1 +1 @@
-{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/personas/resolver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAuB,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAElE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,cAAc,EAAE,MAAM,CAAC;IACvB,mFAAmF;IACnF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,8EAA8E;IAC9E,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0HAA0H;IAC1H,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,6FAA6F;IAC7F,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAChD;;;;OAIG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACtD,8EAA8E;IAC9E,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;IACzD,6CAA6C;IAC7C,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;IAC1D,wEAAwE;IACxE,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAAC;CACnC;AAYD,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,sBAA2B,GAAG,eAAe,CAgI3F"}
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/personas/resolver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAuB,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAElE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,cAAc,EAAE,MAAM,CAAC;IACvB,mFAAmF;IACnF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,8EAA8E;IAC9E,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC5C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC7C;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9E,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0HAA0H;IAC1H,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,6FAA6F;IAC7F,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;;;;OAQG;IACH,aAAa,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;IAC9C;;;;OAIG;IACH,mBAAmB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC;IACpD,8EAA8E;IAC9E,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;IACzD,6CAA6C;IAC7C,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;IAC1D,wEAAwE;IACxE,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAAC;CACnC;AAYD,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,sBAA2B,GAAG,eAAe,CAmJ3F"}

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

@@ -1 +1 @@
-{"version":3,"file":"timeContext.d.ts","sourceRoot":"","sources":["../../src/personas/timeContext.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,CAuB7E"}
+{"version":3,"file":"timeContext.d.ts","sourceRoot":"","sources":["../../src/personas/timeContext.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,CA6B7E"}

package/dist/routes/demo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"demo.d.ts","sourceRoot":"","sources":["../../src/routes/demo.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAa5B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AA6FnD,wBAAgB,UAAU,CAAC,IAAI,EAAE,kBAAkB,8EAmIlD"}
+{"version":3,"file":"demo.d.ts","sourceRoot":"","sources":["../../src/routes/demo.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAa5B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AA6FnD,wBAAgB,UAAU,CAAC,IAAI,EAAE,kBAAkB,8EAqIlD"}

package/dist/routes/openai.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/routes/openai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAW5B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAsDnD,wBAAgB,YAAY,CAAC,IAAI,EAAE,kBAAkB,8EAoLpD"}
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/routes/openai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAW5B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAsDnD,wBAAgB,YAAY,CAAC,IAAI,EAAE,kBAAkB,8EAsLpD"}

package/dist/routes/private.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"private.d.ts","sourceRoot":"","sources":["../../src/routes/private.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAS5B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AASnD,wBAAgB,aAAa,CAAC,IAAI,EAAE,kBAAkB,8EAuFrD"}
+{"version":3,"file":"private.d.ts","sourceRoot":"","sources":["../../src/routes/private.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAS5B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AASnD,wBAAgB,aAAa,CAAC,IAAI,EAAE,kBAAkB,8EAyFrD"}

package/dist/routes/public.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../src/routes/public.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAW5B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AASnD,wBAAgB,YAAY,CAAC,IAAI,EAAE,kBAAkB,8EAsFpD"}
+{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../src/routes/public.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAW5B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AASnD,wBAAgB,YAAY,CAAC,IAAI,EAAE,kBAAkB,8EA+FpD"}