@diegoaltoworks/chatter 0.60.0 → 0.62.0

package/dist/channels/matrix/index.mjs

@@ -0,0 +1,1079 @@
+// src/channels/matrix/api.ts
+var MatrixApiError = class extends Error {
+  errcode;
+  status;
+  retryAfterMs;
+  constructor(message, options) {
+    super(message);
+    this.name = "MatrixApiError";
+    this.errcode = options?.errcode;
+    this.status = options?.status;
+    this.retryAfterMs = options?.retryAfterMs;
+  }
+};
+function redactToken(text, token) {
+  if (!token) return text;
+  return text.split(token).join("***");
+}
+var DEFAULT_MAX_MEDIA_BYTES = 25 * 1024 * 1024;
+var MEDIA_MSGTYPE = {
+  image: "m.image",
+  file: "m.file",
+  video: "m.video",
+  audio: "m.audio"
+};
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+var txnCounter = 0;
+function nextTxnId() {
+  txnCounter += 1;
+  return `chatter-${Date.now()}-${txnCounter}`;
+}
+function toMediaRequest(payload) {
+  const media = typeof payload === "string" ? { url: payload } : payload;
+  if (!media || typeof media !== "object" || typeof media.url !== "string" || !media.url) {
+    throw new TypeError(
+      `Matrix sendMedia payload must be a URL/mxc string or { url, kind?, caption?, filename? } \u2014 got: ${typeof payload}`
+    );
+  }
+  const kind = media.kind ?? "image";
+  if (!MEDIA_MSGTYPE[kind]) {
+    throw new TypeError(
+      `Matrix sendMedia kind must be one of ${Object.keys(MEDIA_MSGTYPE).join(", ")} \u2014 got "${kind}"`
+    );
+  }
+  return { kind, url: media.url, caption: media.caption, filename: media.filename };
+}
+function assertHttpsMediaUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new TypeError(
+      `Matrix sendMedia url must be an mxc:// URI or an https URL - could not parse "${url}"`
+    );
+  }
+  if (parsed.protocol !== "https:") {
+    throw new TypeError(
+      `Matrix sendMedia url must be an mxc:// URI or an https URL - got "${parsed.protocol}"`
+    );
+  }
+}
+async function readCappedBytes(response, maxBytes) {
+  const declared = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    throw new Error(`media source declares ${declared} bytes, over the ${maxBytes} byte cap`);
+  }
+  const reader = response.body?.getReader();
+  if (!reader) {
+    const bytes2 = new Uint8Array(await response.arrayBuffer());
+    if (bytes2.byteLength > maxBytes) {
+      throw new Error(`media source is ${bytes2.byteLength} bytes, over the ${maxBytes} byte cap`);
+    }
+    return bytes2;
+  }
+  const chunks = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!value) continue;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel();
+      throw new Error(`media source exceeds the ${maxBytes} byte cap`);
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+function createMatrixApi(config) {
+  const token = config.accessToken;
+  if (!token.trim()) throw new Error("Matrix accessToken is required (e.g. MATRIX_ACCESS_TOKEN)");
+  const homeserverUrl = config.homeserverUrl.trim().replace(/\/+$/, "");
+  if (!homeserverUrl)
+    throw new Error("Matrix homeserverUrl is required (e.g. https://matrix.example.org)");
+  const doFetch = config.fetch ?? globalThis.fetch;
+  const maxMediaBytes = config.maxMediaBytes ?? DEFAULT_MAX_MEDIA_BYTES;
+  async function call(method, path, options) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(options?.query ?? {})) {
+      if (value !== void 0) search.set(key, String(value));
+    }
+    const qs = search.toString();
+    const url = `${homeserverUrl}${path}${qs ? `?${qs}` : ""}`;
+    let response;
+    try {
+      response = await doFetch(url, {
+        method,
+        headers: {
+          authorization: `Bearer ${token}`,
+          ...options?.body !== void 0 ? { "content-type": "application/json" } : {}
+        },
+        body: options?.body !== void 0 ? JSON.stringify(options.body) : void 0,
+        signal: options?.signal
+      });
+    } catch (error) {
+      throw new MatrixApiError(
+        `${method} ${path} request failed: ${redactToken(errorText(error), token)}`
+      );
+    }
+    if (response.ok) {
+      if (response.status === 204) return void 0;
+      try {
+        return await response.json();
+      } catch {
+        throw new MatrixApiError(
+          `${method} ${path} returned a non-JSON response (HTTP ${response.status})`
+        );
+      }
+    }
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+    }
+    throw new MatrixApiError(
+      `${method} ${path} failed (HTTP ${response.status}): ${redactToken(body?.error ?? "unknown error", token)}`,
+      { errcode: body?.errcode, status: response.status, retryAfterMs: body?.retry_after_ms }
+    );
+  }
+  async function sendEvent(roomId, content, options) {
+    const eventType = options?.eventType ?? "m.room.message";
+    const result = await call(
+      "PUT",
+      `/_matrix/client/v3/rooms/${encodeURIComponent(roomId)}/send/${encodeURIComponent(eventType)}/${nextTxnId()}`,
+      { body: content }
+    );
+    return { eventId: result.event_id };
+  }
+  async function uploadMedia(bytes, contentType, filename) {
+    const search = new URLSearchParams();
+    if (filename) search.set("filename", filename);
+    const qs = search.toString();
+    let response;
+    try {
+      response = await doFetch(`${homeserverUrl}/_matrix/media/v3/upload${qs ? `?${qs}` : ""}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}`, "content-type": contentType },
+        // Uint8Array is a valid fetch BodyInit at runtime (Bun/Node both
+        // accept it); only the DOM lib's stricter overload set rejects it.
+        body: bytes
+      });
+    } catch (error) {
+      throw new MatrixApiError(`media upload failed: ${redactToken(errorText(error), token)}`);
+    }
+    if (!response.ok) {
+      let body;
+      try {
+        body = await response.json();
+      } catch {
+      }
+      throw new MatrixApiError(
+        `media upload failed (HTTP ${response.status}): ${redactToken(body?.error ?? "unknown error", token)}`,
+        { errcode: body?.errcode, status: response.status }
+      );
+    }
+    let result;
+    try {
+      result = await response.json();
+    } catch {
+      throw new MatrixApiError(
+        `media upload returned a non-JSON response (HTTP ${response.status})`
+      );
+    }
+    return { contentUri: result.content_uri };
+  }
+  async function sendMedia(roomId, payload) {
+    const media = toMediaRequest(payload);
+    let contentUri = media.url;
+    if (!contentUri.startsWith("mxc://")) {
+      assertHttpsMediaUrl(media.url);
+      let bytes;
+      let contentType = "application/octet-stream";
+      try {
+        const fetched = await doFetch(media.url);
+        if (!fetched.ok) throw new Error(`fetching media source returned HTTP ${fetched.status}`);
+        contentType = fetched.headers.get("content-type") ?? contentType;
+        bytes = await readCappedBytes(fetched, maxMediaBytes);
+      } catch (error) {
+        throw new MatrixApiError(`could not fetch media source for upload: ${errorText(error)}`);
+      }
+      const filename = media.filename ?? media.url.split("/").pop() ?? media.kind;
+      const uploaded = await uploadMedia(bytes, contentType, filename);
+      contentUri = uploaded.contentUri;
+    }
+    return sendEvent(roomId, {
+      msgtype: MEDIA_MSGTYPE[media.kind],
+      body: media.caption ?? media.filename ?? media.kind,
+      url: contentUri
+    });
+  }
+  return {
+    call,
+    async whoami() {
+      const result = await call("GET", "/_matrix/client/v3/account/whoami");
+      return { userId: result.user_id };
+    },
+    sync: ({ since, timeoutMs, signal }) => call("GET", "/_matrix/client/v3/sync", {
+      query: {
+        since,
+        timeout: timeoutMs,
+        // An initial sync (no `since`) returns each joined room's recent
+        // timeline by default — replaying it into the pipeline would
+        // re-answer messages that arrived before this process ever
+        // started. A bot only wants live traffic, so it asks for none:
+        // room state (needed for auto-join / m.direct bookkeeping) still
+        // comes through unaffected, only `timeline.events` is suppressed.
+        ...since ? {} : { filter: JSON.stringify({ room: { timeline: { limit: 0 } } }) }
+      },
+      signal
+    }),
+    sendEvent,
+    uploadMedia,
+    sendMedia,
+    async joinRoom(roomIdOrAlias) {
+      await call("POST", `/_matrix/client/v3/join/${encodeURIComponent(roomIdOrAlias)}`, {
+        body: {}
+      });
+    },
+    async getAccountData(userId, type) {
+      try {
+        return await call(
+          "GET",
+          `/_matrix/client/v3/user/${encodeURIComponent(userId)}/account_data/${encodeURIComponent(type)}`
+        );
+      } catch (error) {
+        if (error instanceof MatrixApiError && error.errcode === "M_NOT_FOUND") return void 0;
+        throw error;
+      }
+    },
+    async setAccountData(userId, type, content) {
+      await call(
+        "PUT",
+        `/_matrix/client/v3/user/${encodeURIComponent(userId)}/account_data/${encodeURIComponent(type)}`,
+        { body: content }
+      );
+    }
+  };
+}
+
+// src/core/logger.ts
+var LEVEL_ORDER = { debug: 0, info: 1, warn: 2, error: 3 };
+function createConsoleLogger(level = "info") {
+  const threshold = LEVEL_ORDER[level];
+  const write = (at) => (...args) => {
+    if (LEVEL_ORDER[at] < threshold) return;
+    console.error(`[${at}]`, ...args);
+  };
+  return {
+    debug: write("debug"),
+    info: write("info"),
+    warn: write("warn"),
+    error: write("error")
+  };
+}
+
+// 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, conversationId }) {
+  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 : ""),
+    usage: usage ?? noUsage()
+  };
+}
+async function answerOnce({
+  answerFn,
+  client,
+  system,
+  messages,
+  mode,
+  sender,
+  conversationId,
+  temperature,
+  model
+}) {
+  if (answerFn) {
+    return runAnswerFn(answerFn, { system, messages, mode, sender, conversationId });
+  }
+  return completeOnce({ client, system, messages, temperature, model });
+}
+async function applyTransformReply(transformReply, input, logger) {
+  if (!transformReply) return input.text;
+  try {
+    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`,
+      error
+    );
+    return input.text;
+  }
+}
+
+// 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/messages.ts
+function lastUserMessage(messages) {
+  return [...messages].reverse().find((m) => m.role === "user");
+}
+
+// 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,
+  sender,
+  rewriteQuery,
+  rerankContext,
+  fallbackFn,
+  logger
+}) {
+  const lastUserMsg = lastUserMessage(messages);
+  if (!lastUserMsg) {
+    throw new Error("no user message found in conversation");
+  }
+  const { topK, label } = MODE_SETTINGS[mode];
+  let query = lastUserMsg.content;
+  if (rewriteQuery) {
+    try {
+      const rewritten = await rewriteQuery({ query, mode, sender });
+      if (typeof rewritten === "string" && rewritten.trim()) query = rewritten;
+    } catch (error) {
+      logger?.error("rewriteQuery threw; falling back to the original query", error);
+    }
+  }
+  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] });
+      if (Array.isArray(reranked) && reranked.every((c) => typeof c === "string")) ctx = reranked;
+    } catch (error) {
+      logger?.error("rerankContext threw; falling back to the original chunks", error);
+    }
+  }
+  let fallback;
+  if (ctx.length === 0 && fallbackFn) {
+    try {
+      const guidance = await fallbackFn({
+        query,
+        mode,
+        buckets: resolvedBuckets,
+        sender,
+        retrievedChunks
+      });
+      if (typeof guidance === "string" && guidance.trim()) fallback = guidance.trim();
+    } catch (error) {
+      logger?.error("fallbackFn threw; proceeding without fallback guidance", error);
+    }
+  }
+  const persona = personaLayer?.trim() || (mode === "private" ? prompts.privatePersona : prompts.publicPersona);
+  const hint = channelHint?.trim();
+  const system = [
+    prompts.baseSystemRules,
+    persona,
+    ...hint ? [hint] : [],
+    ...fallback ? [fallback] : [],
+    `${label}:
+${ctx.join("\n\n")}`
+  ].join("\n\n");
+  return { system, messages, context: ctx };
+}
+
+// src/history/compaction.ts
+var COMPACTION_TIMEOUT_MS = 8e3;
+var LOAD_ALL = Number.MAX_SAFE_INTEGER;
+var SUMMARY_PREFIX = "Summary of earlier conversation: ";
+function defaultSummarize(client, model) {
+  return async ({ turns }) => {
+    const transcript = turns.map((turn) => `${turn.role}: ${turn.content}`).join("\n");
+    const { content } = await answerOnce({
+      client,
+      system: "Summarize the conversation turns below into a short paragraph a reader would need to continue the conversation. Preserve names, facts, and decisions; drop pleasantries. Reply with the summary only, no preamble.",
+      messages: [{ role: "user", content: transcript }],
+      // No `answerFn`: compaction is an internal chatter operation, not a
+      // chat surface, so it must not conscript a caller's brain hook, which
+      // is shaped to answer the user, not to summarize on the engine's behalf.
+      mode: "public",
+      model
+    });
+    return content;
+  };
+}
+function createHistoryCompactor(deps, options) {
+  const { threshold, keep, logger } = options;
+  if (!Number.isInteger(threshold) || threshold < 1) {
+    throw new Error(`Invalid history compaction threshold: ${threshold}`);
+  }
+  if (!Number.isInteger(keep) || keep < 0 || keep >= threshold) {
+    throw new Error(`Invalid history compaction keep: ${keep}`);
+  }
+  const summarize = options.summarize ?? defaultSummarize(deps.client, options.model);
+  const timeoutMs = options.timeoutMs ?? COMPACTION_TIMEOUT_MS;
+  return {
+    async maybeCompact(store, conversationId) {
+      const turns = await store.load(conversationId, LOAD_ALL);
+      if (turns.length < threshold) return;
+      const older = turns.slice(0, turns.length - keep);
+      let summary;
+      let timer;
+      try {
+        summary = await Promise.race([
+          summarize({ conversationId, turns: older }),
+          new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error("history compaction timed out")), timeoutMs);
+          })
+        ]);
+      } catch (error) {
+        logger?.error(
+          `history compaction summarize failed for "${conversationId}"; history left untouched`,
+          error
+        );
+        return;
+      } finally {
+        clearTimeout(timer);
+      }
+      const trimmed = summary.trim();
+      if (!trimmed) return;
+      const fresh = await store.load(conversationId, LOAD_ALL);
+      const recent = fresh.slice(older.length);
+      await store.clear(conversationId);
+      await store.append(conversationId, {
+        role: "assistant",
+        content: `${SUMMARY_PREFIX}${trimmed}`
+      });
+      for (const turn of recent) {
+        await store.append(conversationId, turn);
+      }
+    }
+  };
+}
+
+// src/channels/gates.ts
+function matches(re, text) {
+  return new RegExp(re.source, re.flags.replace(/[gy]/g, "")).test(text);
+}
+function isBlockedByAllowlist(msg, config) {
+  return !msg.fromBot && msg.text.trim().length > 0 && !msg.isDirectMessage && config.allowedChats.length > 0 && !config.allowedChats.includes(msg.chatId);
+}
+function decideChannelAction(msg, config) {
+  if (msg.fromBot || !msg.text.trim()) return "ignore";
+  if (!msg.isDirectMessage) {
+    if (isBlockedByAllowlist(msg, config)) 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();
+  let lastSweep = now();
+  function sweep(current) {
+    if (current - lastSweep < windowMs) return;
+    lastSweep = current;
+    const cutoff = current - windowMs;
+    for (const [key, entries] of log) {
+      if (!entries.some((t) => t > cutoff)) log.delete(key);
+    }
+  }
+  function allow(key) {
+    const current = now();
+    sweep(current);
+    const cutoff = current - 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(current);
+    log.set(key, entries);
+    return true;
+  }
+  allow.size = () => log.size;
+  return allow;
+}
+function underReplyRateLimit(msg, limiters) {
+  return msg.isDirectMessage ? limiters.dm(msg.chatId) : limiters.group(msg.chatId);
+}
+
+// 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 };
+async function resolvePersonaLayer(config, ctx) {
+  if (!config.personaResolver) return void 0;
+  try {
+    return await config.personaResolver(ctx);
+  } catch {
+    return void 0;
+  }
+}
+async function isHistoryEnabled(config, sender) {
+  const predicate = config.history?.historyEnabledFor;
+  if (!predicate) return true;
+  try {
+    return await predicate(sender);
+  } catch (error) {
+    config.logger?.error("historyEnabledFor threw; disabling history for this turn", error);
+    return false;
+  }
+}
+function createInboundPipeline(deps, 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);
+  const mode = "public";
+  const compactor = config.history?.compaction ? createHistoryCompactor(
+    { client: deps.client },
+    { model: config.model, ...config.history.compaction }
+  ) : void 0;
+  return async function handleInboundMessage(msg, turn) {
+    const allowedChats = config.allowedChats ?? [];
+    const action = decideChannelAction(msg, {
+      allowedChats,
+      mutedChats,
+      muteRegex: config.muteRegex,
+      unmuteRegex: config.unmuteRegex
+    });
+    if (action === "mute") {
+      mutedChats.add(msg.chatId);
+      if (config.muteReply) await turn.reply.sendGateReply(msg.chatId, config.muteReply);
+      return { action: "mute" };
+    }
+    if (action === "unmute") {
+      mutedChats.delete(msg.chatId);
+      if (config.unmuteReply) await turn.reply.sendGateReply(msg.chatId, config.unmuteReply);
+      return { action: "unmute" };
+    }
+    if (action === "ignore") {
+      return { action: "ignore" };
+    }
+    if (!underReplyRateLimit(msg, { dm: underDmRateLimit, group: underGroupRateLimit })) {
+      return { action: "rate-limited" };
+    }
+    const sender = typeof turn.sender === "function" ? await turn.sender() : turn.sender ?? msg.senderId;
+    const conversationId = turn.conversationId ?? msg.chatId;
+    if (turn.intercept && await turn.intercept(sender)) {
+      return { action: "intercepted" };
+    }
+    const personaLayer = await resolvePersonaLayer(config, { sender, text: msg.text });
+    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(
+      conversationId,
+      config.history.limit ?? DEFAULT_HISTORY_LIMIT
+    ) : [];
+    const messages = [...priorTurns, { role: "user", content: msg.text }];
+    if (historyEnabled) {
+      await config.history?.store.append(conversationId, { role: "user", content: msg.text });
+    }
+    const { system } = await prepareChat({
+      store: deps.store,
+      prompts: deps.prompts,
+      mode,
+      messages,
+      personaLayer,
+      channelHint: config.channelHint,
+      buckets,
+      sender,
+      rewriteQuery: config.rewriteQuery,
+      rerankContext: config.rerankContext,
+      fallbackFn: config.fallbackFn,
+      logger: config.logger
+    });
+    const { content: produced } = await answerOnce({
+      answerFn: config.answerFn,
+      client: deps.client,
+      system,
+      messages,
+      mode,
+      sender,
+      conversationId,
+      model: config.model
+    });
+    const content = await applyTransformReply(
+      config.transformReply,
+      { channel: config.channel ?? "channel", sender, conversationId, text: produced },
+      config.logger
+    );
+    if (!content) {
+      return { action: "ignore" };
+    }
+    if (historyEnabled) {
+      await config.history?.store.append(conversationId, { role: "assistant", content });
+    }
+    await turn.reply.sendAnswer(msg.chatId, content);
+    const history = config.history;
+    if (compactor && historyEnabled && history) {
+      try {
+        await compactor.maybeCompact(history.store, conversationId);
+      } catch (error) {
+        config.logger?.error(`history compaction failed for "${conversationId}"`, error);
+      }
+    }
+    return { action: "reply", content };
+  };
+}
+
+// src/channels/polling.ts
+function defaultSleep(ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    if (typeof timer === "object" && "unref" in timer) timer.unref();
+  });
+}
+
+// src/channels/matrix/updates.ts
+function messageText(content) {
+  return content.body ?? "";
+}
+var PILL_HREF_PATTERN = /href=["']([^"']+)["']/g;
+function pillUserId(href) {
+  const fragment = href.split("https://matrix.to/#/")[1];
+  if (!fragment) return void 0;
+  try {
+    return decodeURIComponent(fragment.split("?")[0] ?? "");
+  } catch {
+    return void 0;
+  }
+}
+function mentionsBot(content, me) {
+  if (content["m.mentions"]?.user_ids?.includes(me.userId)) return true;
+  const formatted = content.formatted_body;
+  if (!formatted) return false;
+  for (const match of formatted.matchAll(PILL_HREF_PATTERN)) {
+    if (pillUserId(match[1] ?? "") === me.userId) return true;
+  }
+  return false;
+}
+function isReplyToBot(content, sentEventIds) {
+  const replyToId = content["m.relates_to"]?.["m.in_reply_to"]?.event_id;
+  return replyToId ? sentEventIds.has(replyToId) : false;
+}
+var MAX_TRACKED_SENT_EVENTS = 500;
+function recordSentEventId(sentEventIds, eventId) {
+  sentEventIds.add(eventId);
+  if (sentEventIds.size > MAX_TRACKED_SENT_EVENTS) {
+    const oldest = sentEventIds.values().next().value;
+    if (oldest !== void 0) sentEventIds.delete(oldest);
+  }
+}
+function toDirectMapping(content) {
+  const mapping = {};
+  for (const [peer, value] of Object.entries(content ?? {})) {
+    if (!Array.isArray(value)) continue;
+    const rooms = value.filter((roomId) => typeof roomId === "string");
+    if (rooms.length > 0) mapping[peer] = rooms;
+  }
+  return mapping;
+}
+function directMappingRooms(mapping) {
+  return new Set(Object.values(mapping).flat());
+}
+function directMappingFromEvents(accountDataEvents) {
+  const direct = accountDataEvents.find((event) => event.type === "m.direct");
+  return direct ? toDirectMapping(direct.content) : void 0;
+}
+function directRoomIds(accountDataEvents) {
+  return directMappingRooms(directMappingFromEvents(accountDataEvents) ?? {});
+}
+function withDirectRoom(mapping, peer, roomId) {
+  const existing = mapping[peer] ?? [];
+  if (existing.includes(roomId)) return void 0;
+  return { ...mapping, [peer]: [...existing, roomId] };
+}
+function directInviteFrom(room, me) {
+  for (const event of room.invite_state?.events ?? []) {
+    if (event.type !== "m.room.member" || event.state_key !== me.userId) continue;
+    const content = event.content ?? {};
+    if (content.membership !== "invite") continue;
+    if (content.is_direct === true) return event.sender;
+  }
+  return void 0;
+}
+function toChannelMessage(roomId, event, me, directRooms, sentEventIds) {
+  if (event.type !== "m.room.message") return void 0;
+  const content = event.content;
+  if (!content.msgtype) return void 0;
+  if (content["m.relates_to"]?.rel_type === "m.replace") return void 0;
+  return {
+    chatId: roomId,
+    senderId: event.sender,
+    text: messageText(content),
+    isDirectMessage: directRooms.has(roomId),
+    mentionsBot: mentionsBot(content, me),
+    isReplyToBot: isReplyToBot(content, sentEventIds),
+    fromBot: event.sender === me.userId,
+    messageRef: event.event_id
+  };
+}
+function matrixSenderKey(userId) {
+  return `mx:${userId}`;
+}
+
+// src/channels/matrix/handler.ts
+async function sendText(api, roomId, text, sentEventIds, replyToEventId) {
+  const { eventId } = await api.sendEvent(roomId, {
+    msgtype: "m.text",
+    body: text,
+    ...replyToEventId ? { "m.relates_to": { "m.in_reply_to": { event_id: replyToEventId } } } : {}
+  });
+  recordSentEventId(sentEventIds, eventId);
+}
+function createMatrixSyncHandler(deps) {
+  const { api, me, pipeline, allowedChats, sentEventIds, logger, label } = deps;
+  const autoJoin = deps.autoJoin ?? true;
+  const loggedUnallowedChats = /* @__PURE__ */ new Set();
+  const loggedDeclinedInvites = /* @__PURE__ */ new Set();
+  let directMapping = { ...deps.initialDirect ?? {} };
+  let directRooms = directMappingRooms(directMapping);
+  async function rememberDirectRoom(peer, roomId) {
+    directRooms.add(roomId);
+    const merged = withDirectRoom(directMapping, peer, roomId);
+    if (!merged) return;
+    directMapping = merged;
+    try {
+      await api.setAccountData(me.userId, "m.direct", directMapping);
+    } catch (error) {
+      logger.warn(`${label}: could not record ${roomId} in m.direct:`, error);
+    }
+  }
+  return async function handleSync(response) {
+    const syncedDirect = directMappingFromEvents(response.account_data?.events ?? []);
+    if (syncedDirect) {
+      directMapping = syncedDirect;
+      directRooms = directMappingRooms(directMapping);
+    }
+    if (autoJoin) {
+      for (const [roomId, room] of Object.entries(response.rooms?.invite ?? {})) {
+        if (allowedChats.length > 0 && !allowedChats.includes(roomId)) {
+          if (!loggedDeclinedInvites.has(roomId)) {
+            loggedDeclinedInvites.add(roomId);
+            logger.warn(`${label}: left invite to ${roomId} pending - not in allowedChats`);
+          }
+          continue;
+        }
+        const directInviter = directInviteFrom(room, me);
+        try {
+          await api.joinRoom(roomId);
+          logger.info(`${label}: joined ${roomId} (accepted invite)`);
+        } catch (error) {
+          logger.warn(`${label}: failed to join ${roomId}:`, error);
+          continue;
+        }
+        if (directInviter) await rememberDirectRoom(directInviter, roomId);
+      }
+    }
+    for (const [roomId, room] of Object.entries(response.rooms?.join ?? {})) {
+      for (const event of room.timeline.events) {
+        const msg = toChannelMessage(roomId, event, me, directRooms, sentEventIds);
+        if (!msg) continue;
+        if (isBlockedByAllowlist(msg, { allowedChats })) {
+          if (!loggedUnallowedChats.has(msg.chatId)) {
+            loggedUnallowedChats.add(msg.chatId);
+            logger.warn(`${label}: skipped room ${msg.chatId} - not in allowedChats`);
+          }
+        }
+        const reply = {
+          // Threaded onto the incoming event: in a busy room an untethered
+          // answer reads as a non-sequitur.
+          sendAnswer: (chatId, text) => sendText(api, chatId, text, sentEventIds, event.event_id),
+          sendGateReply: (chatId, text) => sendText(api, chatId, text, sentEventIds)
+        };
+        try {
+          await pipeline(msg, {
+            reply,
+            conversationId: msg.chatId,
+            sender: matrixSenderKey(msg.senderId)
+          });
+        } catch (error) {
+          logger.warn(`${label}: message ${event.event_id} in ${roomId} handling failed:`, error);
+        }
+      }
+    }
+  };
+}
+function createMatrixSender(api, sentEventIds) {
+  return {
+    sendText: (chatId, text) => sendText(api, chatId, text, sentEventIds),
+    sendMedia: async (chatId, payload) => {
+      const { eventId } = await api.sendMedia(chatId, payload);
+      recordSentEventId(sentEventIds, eventId);
+    },
+    sendReaction: (chatId, messageRef, emoji) => api.sendEvent(
+      chatId,
+      {
+        "m.relates_to": { rel_type: "m.annotation", event_id: String(messageRef), key: emoji }
+      },
+      { eventType: "m.reaction" }
+    ).then(() => void 0)
+  };
+}
+
+// src/channels/backoff.ts
+function exponentialBackoffMs(baseMs, maxMs, n) {
+  return Math.min(baseMs * 2 ** Math.max(0, Math.min(n, 20)), maxMs);
+}
+
+// src/channels/matrix/sync.ts
+var BASE_DELAY_MS = 1e3;
+var MAX_DELAY_MS = 6e4;
+function syncBackoffMs(failures) {
+  return exponentialBackoffMs(BASE_DELAY_MS, MAX_DELAY_MS, failures);
+}
+function retryDelayMs(error, failures) {
+  const retryAfterMs = error instanceof MatrixApiError ? error.retryAfterMs : void 0;
+  return retryAfterMs ?? syncBackoffMs(failures);
+}
+async function runMatrixSyncLoop(deps) {
+  const logger = deps.logger ?? createConsoleLogger();
+  const label = deps.label ?? "Matrix";
+  let since = deps.initialSince;
+  let failures = 0;
+  while (!deps.isStopped()) {
+    let response;
+    try {
+      response = await deps.sync(since);
+    } catch (error) {
+      if (deps.isStopped()) break;
+      failures += 1;
+      const delay = retryDelayMs(error, failures);
+      logger.warn(`${label}: sync failed, retrying in ${Math.round(delay / 1e3)}s:`, error);
+      await deps.sleep(delay);
+      continue;
+    }
+    failures = 0;
+    if (deps.isStopped()) break;
+    since = response.next_batch;
+    deps.onSince?.(since);
+    try {
+      await deps.handleSync(response);
+    } catch (error) {
+      logger.warn(`${label}: batch ending at ${since} handling failed:`, error);
+    }
+  }
+  return since;
+}
+
+// src/channels/matrix/channel.ts
+var DEFAULT_SYNC_TIMEOUT_MS = 3e4;
+function createMatrixChannel(config) {
+  const channelName = config.name ?? "matrix";
+  const allowedChats = config.allowedChats ?? [];
+  const sleep = config.sleep ?? defaultSleep;
+  const syncTimeoutMs = config.syncTimeoutMs ?? DEFAULT_SYNC_TIMEOUT_MS;
+  let stopped = false;
+  let registered = false;
+  let abort;
+  let senders;
+  const sentEventIds = /* @__PURE__ */ new Set();
+  return {
+    name: channelName,
+    async start(deps) {
+      const log = config.logger ?? deps.logger ?? createConsoleLogger();
+      const api = config.api ?? createMatrixApi({
+        homeserverUrl: config.homeserverUrl,
+        accessToken: config.accessToken,
+        fetch: config.fetch,
+        maxMediaBytes: config.maxMediaBytes
+      });
+      const me = await api.whoami();
+      const label = `Matrix[${me.userId}]`;
+      let initialDirect;
+      try {
+        const direct = await api.getAccountData(me.userId, "m.direct");
+        if (direct) initialDirect = toDirectMapping(direct);
+      } catch (error) {
+        log.warn(`${label}: could not load m.direct account data at start:`, error);
+      }
+      deps.senders.register(channelName, createMatrixSender(api, sentEventIds));
+      senders = deps.senders;
+      registered = true;
+      const pipeline = createInboundPipeline(
+        { client: deps.client, store: deps.store, prompts: deps.prompts },
+        {
+          channel: channelName,
+          ...resolveBrainHooks(config, deps.config),
+          model: config.model,
+          channelHint: config.channelHint ?? "Channel: Matrix.",
+          personaResolver: config.personaResolver,
+          history: config.history,
+          allowedChats,
+          muteRegex: config.muteRegex,
+          unmuteRegex: config.unmuteRegex,
+          muteReply: config.muteReply,
+          unmuteReply: config.unmuteReply,
+          dmRateLimit: config.dmRateLimit,
+          groupRateLimit: config.groupRateLimit,
+          now: config.now,
+          logger: log
+        }
+      );
+      const handleSync = createMatrixSyncHandler({
+        api,
+        me,
+        pipeline,
+        allowedChats,
+        sentEventIds,
+        autoJoin: config.autoJoin,
+        initialDirect,
+        logger: log,
+        label
+      });
+      abort = new AbortController();
+      const signal = abort.signal;
+      void runMatrixSyncLoop({
+        sync: (since) => api.sync({ since, timeoutMs: syncTimeoutMs, signal }),
+        handleSync,
+        isStopped: () => stopped,
+        sleep,
+        initialSince: config.initialSince,
+        onSince: config.onSince,
+        logger: log,
+        label
+      }).catch((error) => log.error(`${label}: sync loop ended unexpectedly:`, error));
+      log.info(`${label}: syncing for events`);
+    },
+    stop() {
+      stopped = true;
+      abort?.abort();
+      if (registered) {
+        senders?.unregister(channelName);
+        registered = false;
+      }
+    }
+  };
+}
+export {
+  DEFAULT_MAX_MEDIA_BYTES,
+  MAX_TRACKED_SENT_EVENTS,
+  MatrixApiError,
+  createMatrixApi,
+  createMatrixChannel,
+  createMatrixSender,
+  createMatrixSyncHandler,
+  directInviteFrom,
+  directMappingFromEvents,
+  directMappingRooms,
+  directRoomIds,
+  isReplyToBot,
+  matrixSenderKey,
+  mentionsBot,
+  messageText,
+  recordSentEventId,
+  redactToken,
+  retryDelayMs,
+  runMatrixSyncLoop,
+  syncBackoffMs,
+  toChannelMessage,
+  toDirectMapping,
+  withDirectRoom
+};