@inetafrica/open-claudia 3.5.1 → 3.5.7

package/channels/kazee/adapter.js

@@ -40,6 +40,68 @@ const CONTEXT_MAX_MESSAGES = 40;
 const CONTEXT_BODY_LIMIT = 280;
 const COLD_START_WINDOW = 40;
 
+// Chat threads ("reply in thread"). Button presses carry no thread, so the
+// adapter remembers which thread each message it posted went into (and that
+// it posted it at all: a thread hanging off one of the bot's own messages
+// engages it in a group). How many to remember: a busy week of replies.
+const SENT_MESSAGE_MEMORY = 5000;
+// Thread history fetches (the group gate's root lookup and the thread context
+// block) must never hold a turn up: past this the turn goes ahead without them.
+const THREAD_FETCH_TIMEOUT_MS = 4000;
+// A thread whose root someone else posted is re-checked for the bot among its
+// participants at most this often (the answer is "no" until the bot replies).
+const THREAD_NOT_IN_TTL_MS = 60 * 1000;
+// How many replies a thread's first turn carries as context.
+const THREAD_CONTEXT_LIMIT = 30;
+const THREAD_ROOT_BODY_LIMIT = 1000;
+// A new thread starts "hybrid" (Sumeet, 29 Sep 2026): besides its root and
+// replies it sees the last few main-timeline messages before the root -- what
+// the chat was talking about when the thread began -- not the whole history.
+const THREAD_SEED_MAIN_MESSAGES = 10;
+// Thread titles: how much of a thread the bot reads to name it, and how long
+// the naming call may take (it runs after the reply, never in front of it).
+const THREAD_TITLE_SOURCE_LIMIT = 10;
+const THREAD_TITLE_BODY_LIMIT = 600;
+const THREAD_TITLE_TIMEOUT_MS = 10000;
+// chat-central's refusals of a threadRootId (400 / socket code INVALID_THREAD).
+// On any of them the reply goes to the main timeline instead of being lost.
+const INVALID_THREAD_RE = /INVALID_THREAD|Invalid thread|Thread not found in this chat|This message can['’]t have a thread|That message was deleted|This chat doesn['’]t have threads/i;
+// chat-central drops a typing threadRootId that is not a Mongo ObjectId.
+const OBJECT_ID_RE = /^[0-9a-f]{24}$/i;
+
+// The thread a message belongs to: its root's id, or "" for the main timeline.
+// The field is an id today; accept a populated root doc too.
+function threadRootOf(msg) {
+  const t = msg && msg.threadRoot;
+  if (!t) return "";
+  if (typeof t === "object") return String(t._id || t.id || "");
+  return String(t);
+}
+
+function senderIdOf(m) {
+  return String(m?.sender?._id || m?.sender?.id || m?.senderId || (typeof m?.sender === "string" ? m.sender : "") || "");
+}
+
+// How a new thread starts. "hybrid" (the default): the root, the replies so
+// far and the main-timeline messages just before the root. "fresh": the root
+// and the replies only. "fork" (Claude): the runner resumes the chat's main
+// session into the thread, and the short main slice stays as well -- cheap,
+// and it is what a Codex thread falls back to.
+function threadSeedMode() {
+  let value = process.env.OC_THREAD_SEED;
+  try { value = require("../../core/config").config?.OC_THREAD_SEED ?? value; } catch (_) {}
+  const mode = String(value || "").trim().toLowerCase();
+  return mode === "fresh" || mode === "fork" ? mode : "hybrid";
+}
+
+function withTimeout(promise, ms, label) {
+  let timer;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms); }),
+  ]).finally(() => clearTimeout(timer));
+}
+
 // Kazee Media docs from mobile uploads often carry no fileName, so the saved
 // extension must come from the mimeType (or the blob URL) — otherwise every
 // video/document lands on disk as ".bin".
@@ -85,6 +147,12 @@ class KazeeAdapter {
     this._joinPending = new Map();
     // Insertion-ordered, so the oldest id is always the first key.
     this._seenMessageIds = new Set();
+    // messageId -> threadId (null = main timeline) for messages the bot posted.
+    // Insertion-ordered LRU, like _seenMessageIds.
+    this._sentMessages = new Map();
+    // rootId -> time the bot was last found NOT in that thread (short cache).
+    this._threadNotIn = new Map();
+    this._typingThreadWarned = new Set();
     this._callManager = new KazeeCallManager({ adapter: this });
   }
 
@@ -182,21 +250,47 @@ class KazeeAdapter {
     socket.on("message:new", (msg) => this._handleInboundMessage(msg));
     socket.on("message:action", (payload) => {
       const channelId = String(payload.chatId);
-      const userId = String(payload.userId);
-      this._emit("action", {
-        adapter: this,
-        channelId,
-        canonicalUserId: canonicalForChannel("kazee", userId),
-        userId,
-        type: "action",
-        messageId: payload.messageId,
-        action: {
-          buttonId: payload.buttonId,
-          payload: payload.buttonPayload ?? payload.clientPayload ?? null,
-          sourceMessageId: payload.messageId,
-        },
-        raw: payload,
-      });
+      const known = this._sentMessages.has(String(payload.messageId || ""));
+      // The press payload names no thread: the button's message does, if the
+      // bot posted it inside one. Remembered sends answer at once; a message
+      // the memory no longer has (a restart, or 5000 sends ago) is looked up
+      // on the server. A failed lookup is the main timeline.
+      if (known) return this._emitAction(payload, this._threadOfSent(payload.messageId));
+      return this._threadOfMessage(channelId, String(payload.messageId || ""))
+        .then((threadId) => this._emitAction(payload, threadId));
+    });
+  }
+
+  // The thread a message sits in, read from the server; null when it is on
+  // the main timeline or the lookup fails (never throws, never hangs).
+  async _threadOfMessage(chatId, messageId) {
+    if (!messageId) return null;
+    try {
+      const m = await withTimeout(this._messageInChat(chatId, messageId), THREAD_FETCH_TIMEOUT_MS, "Kazee message lookup");
+      return (m && threadRootOf(m)) || null;
+    } catch (e) {
+      console.error(`Kazee button message lookup failed (chat=${chatId} message=${messageId}):`, e.message);
+      return null;
+    }
+  }
+
+  _emitAction(payload, threadId) {
+    const channelId = String(payload.chatId);
+    const userId = String(payload.userId);
+    this._emit("action", {
+      adapter: this,
+      channelId,
+      canonicalUserId: canonicalForChannel("kazee", userId),
+      userId,
+      type: "action",
+      messageId: payload.messageId,
+      threadId: threadId || null,
+      action: {
+        buttonId: payload.buttonId,
+        payload: payload.buttonPayload ?? payload.clientPayload ?? null,
+        sourceMessageId: payload.messageId,
+      },
+      raw: payload,
     });
   }
 
@@ -215,6 +309,155 @@ class KazeeAdapter {
     return false;
   }
 
+  // Remember a message the bot just posted (and the thread it went into). A
+  // post into a thread also marks the thread as one the bot takes part in, so
+  // later replies there engage it in a group without an @-mention.
+  _rememberSent(messageId, threadId, chatId) {
+    const id = String(messageId || "");
+    const thread = threadId ? String(threadId) : null;
+    if (id) {
+      this._sentMessages.delete(id);
+      this._sentMessages.set(id, thread);
+      if (this._sentMessages.size > SENT_MESSAGE_MEMORY) {
+        this._sentMessages.delete(this._sentMessages.keys().next().value);
+      }
+    }
+    if (thread) kazeeState.markBotRepliedInThread(chatId, thread);
+  }
+
+  // _rememberSent after a successful post: bookkeeping must never fail the
+  // send (a caller or retry loop would post it again).
+  _rememberSentSafely(messageId, threadId, chatId) {
+    try { this._rememberSent(messageId, threadId, chatId); }
+    catch (e) { console.error("Kazee: could not record a sent message:", e.message); }
+  }
+
+  _threadOfSent(messageId) {
+    const id = String(messageId || "");
+    return (id && this._sentMessages.get(id)) || null;
+  }
+
+  // GET a thread's root and replies (oldest first). Throws on failure or
+  // after THREAD_FETCH_TIMEOUT_MS.
+  async _fetchThread(chatId, rootId, limit) {
+    const route = `/thread/${encodeURIComponent(chatId)}/${encodeURIComponent(rootId)}/${encodeURIComponent(String(this.botUserId))}?limit=${limit}`;
+    const res = await withTimeout(this._request("GET", route), THREAD_FETCH_TIMEOUT_MS, "Kazee thread fetch");
+    const data = res?.data || res || {};
+    if (res?.error || data.error || res?.success === false) throw new Error(String(res?.error || data.error || "thread fetch refused"));
+    return data;
+  }
+
+  // The main-timeline messages just before a thread's root, oldest first: the
+  // hybrid start of a new thread. chat-central's "around" read anchors on the
+  // root; threads=true keeps thread-only replies out (and they are dropped
+  // here too, in case a server ignores it). Its `after` reads 0 as "default",
+  // so 1 is asked for and anything at or after the root is dropped here.
+  async _mainBeforeRoot(chatId, rootId) {
+    const route = `/messages/${encodeURIComponent(chatId)}/${encodeURIComponent(String(this.botUserId))}/around/${encodeURIComponent(rootId)}?before=${THREAD_SEED_MAIN_MESSAGES}&after=1&threads=true`;
+    const res = await withTimeout(this._request("GET", route), THREAD_FETCH_TIMEOUT_MS, "Kazee main-timeline fetch");
+    const data = res?.data || res || {};
+    if (res?.error || data.error || res?.success === false) throw new Error(String(res?.error || data.error || "main-timeline fetch refused"));
+    const messages = Array.isArray(data.messages) ? data.messages : [];
+    const anchor = messages.find((m) => String(m._id || m.id || "") === rootId);
+    const rootMs = Date.parse(anchor?.createdAt || "") || Infinity;
+    return messages
+      .filter((m) => String(m._id || m.id || "") !== rootId && !m.isDeleted
+        && (Date.parse(m.createdAt || "") || 0) < rootMs
+        && (!threadRootOf(m) || m.alsoInChannel === true))
+      .sort((a, b) => (Date.parse(a.createdAt || "") || 0) - (Date.parse(b.createdAt || "") || 0))
+      .slice(-THREAD_SEED_MAIN_MESSAGES);
+  }
+
+  // What the bot reads to name a thread: the root's text, the first replies
+  // (the bot's own marked) and the title the thread already has, when the
+  // server sends one. Throws like _fetchThread.
+  async threadTitleSource(chatId, rootId) {
+    const data = await this._fetchThread(String(chatId), String(rootId), THREAD_TITLE_SOURCE_LIMIT);
+    const root = data.root && typeof data.root === "object" ? data.root : null;
+    const botId = String(this.botUserId);
+    const replies = (Array.isArray(data.replies) ? data.replies : [])
+      .filter((m) => !m.isDeleted)
+      .map((m) => ({ fromBot: senderIdOf(m) === botId, text: this._contextBody(m, THREAD_TITLE_BODY_LIMIT) }))
+      .filter((m) => m.text);
+    const title = [root?.threadTitle, data.threadTitle, data.title].find((t) => typeof t === "string" && t.trim());
+    return {
+      rootText: root && !root.isDeleted ? this._contextBody(root, THREAD_TITLE_BODY_LIMIT) : "",
+      replies,
+      title: title ? title.trim() : null,
+    };
+  }
+
+  // Name a thread (chat-central's shared thread titles). onlyIfUnset: only
+  // when it has no title yet, so a title a person gave is never overwritten.
+  // Never throws: { ok, changed, title } on success, else { ok: false,
+  // supported, transient, status, error }. A 404 is a server without thread
+  // titles; a network failure, timeout, 408/429 or 5xx is worth one retry.
+  async setThreadTitle(chatId, rootId, title, { onlyIfUnset = true } = {}) {
+    if (!this.botUserId) return { ok: false, supported: true, transient: false, status: null, error: "no bot user id" };
+    const route = `/thread/${encodeURIComponent(String(chatId))}/${encodeURIComponent(String(rootId))}/title`;
+    const body = { userId: String(this.botUserId), title: String(title || ""), onlyIfUnset: onlyIfUnset !== false };
+    try {
+      const res = await withTimeout(this._request("POST", route, body), THREAD_TITLE_TIMEOUT_MS, "Kazee thread title");
+      if (!res || res.success === false || res.error) {
+        return { ok: false, supported: true, transient: false, status: 200, error: String(res?.error || "thread title refused") };
+      }
+      const out = res.data && typeof res.data === "object" ? { ...res, ...res.data } : res;
+      return { ok: true, changed: out.changed === true, title: typeof out.title === "string" ? out.title : null };
+    } catch (e) {
+      const match = /→ (\d{3}):/.exec(String(e.message || ""));
+      const status = match ? Number(match[1]) : null;
+      return {
+        ok: false,
+        supported: status !== 404,
+        transient: !status || status === 408 || status === 429 || status >= 500,
+        status,
+        error: String(e.message || e),
+      };
+    }
+  }
+
+  // The thread was named (or found named) already: remembered across restarts.
+  markThreadTitled(chatId, rootId) { kazeeState.markThreadTitled(chatId, rootId); }
+  threadTitled(rootId) { return kazeeState.threadTitled(rootId); }
+
+  // Group gate for a thread reply with no @-mention: the bot is part of the
+  // thread when it posted the root or has already replied in it. Answered
+  // from memory when possible; otherwise the root is fetched ONCE and its
+  // author kept (persisted), so the next reply in the same thread costs
+  // nothing. A failed lookup stays silent (the gate fails closed).
+  async _botInThread(chatId, rootId) {
+    const botId = String(this.botUserId);
+    if (this._sentMessages.has(rootId)) return true;
+    if (kazeeState.botRepliedInThread(rootId)) return true;
+    const known = kazeeState.getThreadRootAuthor(rootId);
+    if (known === botId) return true;
+    // Someone else posted the root: the bot may still have replied there (a
+    // reply whose POST came back without an id was never recorded). Re-check
+    // the participants, at most once a minute per thread.
+    if (known && Date.now() - (this._threadNotIn.get(rootId) || 0) < THREAD_NOT_IN_TTL_MS) return false;
+    try {
+      const data = await this._fetchThread(chatId, rootId, 1);
+      const root = data.root || null;
+      const author = senderIdOf(root);
+      if (author) kazeeState.setThreadRootAuthor(chatId, rootId, author);
+      const participants = (Array.isArray(root?.threadParticipants) ? root.threadParticipants : [])
+        .map((p) => String(p?._id || p?.id || p));
+      const replied = participants.includes(botId)
+        || (Array.isArray(data.replies) ? data.replies : []).some((m) => senderIdOf(m) === botId);
+      if (replied) kazeeState.markBotRepliedInThread(chatId, rootId);
+      const inThread = author === botId || replied;
+      if (inThread) this._threadNotIn.delete(rootId);
+      else {
+        this._threadNotIn.set(rootId, Date.now());
+        if (this._threadNotIn.size > SENT_MESSAGE_MEMORY) this._threadNotIn.delete(this._threadNotIn.keys().next().value);
+      }
+      return inThread;
+    } catch (e) {
+      console.error(`Kazee thread root lookup failed (chat=${chatId} root=${rootId}):`, e.message);
+      return false;
+    }
+  }
+
   async _handleInboundMessage(msg) {
     if (!msg) return;
     if (this._isDuplicateInbound(msg)) return;
@@ -252,6 +495,10 @@ class KazeeAdapter {
       text,
       messageId: msg._id || msg.id,
       replyToId: msg.replyTo,
+      // A reply posted in a thread is a turn of that thread's own conversation.
+      // One with alsoInChannel=true shows in the timeline too, but it is the
+      // same message (deduped by id above): handled once, as a thread turn.
+      threadId: threadRootOf(msg) || null,
       from: baseFrom,
       raw: msg,
     };
@@ -312,6 +559,8 @@ class KazeeAdapter {
     // Group participation gate: in a group chat the bot engages only when
     // addressed — an @-mention of the bot user or a reply to one of its own
     // messages — unless the chat's assistantAction opts into free replies.
+    // A thread reply also engages it when the bot posted the thread's root or
+    // has already replied in that thread (it is part of that conversation).
     // Everyone is gated, owner included: a bot answering every group message
     // drowns the room. 1:1 chats are never gated. Engaged messages are marked
     // so the router can authorize the turn for non-owner speakers, who then
@@ -325,7 +574,10 @@ class KazeeAdapter {
         const mentioned = mentions.includes(botId);
         const replyToBot = String(envelope.reply?.from?.id || "") === botId;
         const freeReply = meta.assistantAction === "assistant_free_reply";
-        if (!mentioned && !replyToBot && !freeReply) {
+        const inThread = !mentioned && !replyToBot && !freeReply && envelope.threadId
+          ? await this._botInThread(channelId, envelope.threadId)
+          : false;
+        if (!mentioned && !replyToBot && !freeReply && !inThread) {
           console.log(`Kazee group gate: silent (chat=${channelId} from=${userId})`);
           return;
         }
@@ -383,8 +635,13 @@ class KazeeAdapter {
   // restart self-heals: the next engage still pulls the true set. Best-effort:
   // any failure returns null, leaves the watermark alone, and never blocks the
   // reply.
+  //
+  // A thread turn (DM or group) gets the THREAD's context instead: see
+  // _threadContext.
   async buildThreadContext(envelope) {
-    if (!envelope || envelope.surface !== "group" || !this.botUserId) return null;
+    if (!envelope || !this.botUserId) return null;
+    if (envelope.threadId) return this._threadContext(envelope);
+    if (envelope.surface !== "group") return null;
     const chatId = String(envelope.channelId || "");
     if (!chatId) return null;
     try {
@@ -439,19 +696,122 @@ class KazeeAdapter {
     }
   }
 
+  // The context a thread turn starts from: the thread's root (who posted it,
+  // when, what, any media) and the replies so far, oldest first, the bot's own
+  // marked as "You". A per-thread watermark means later turns in the same
+  // thread only add the replies posted since the last one (the thread's
+  // session already holds the rest). Replies newer than the triggering
+  // message are left for their own turns. Never blocks the turn: the fetch
+  // times out after THREAD_FETCH_TIMEOUT_MS and any failure returns null with
+  // the watermark untouched.
+  async _threadContext(envelope) {
+    const chatId = String(envelope.channelId || "");
+    const rootId = String(envelope.threadId || "");
+    if (!chatId || !rootId) return null;
+    try {
+      const since = kazeeState.getThreadWatermark(rootId);
+      // The hybrid start's main slice is read alongside the thread, on the
+      // thread's first turn only; if it fails the turn just goes without it.
+      const mainSlice = !since && threadSeedMode() !== "fresh"
+        ? this._mainBeforeRoot(chatId, rootId).catch((e) => { console.error("kazee thread seed:", e.message); return []; })
+        : Promise.resolve([]);
+      const [data, mainBefore] = await Promise.all([this._fetchThread(chatId, rootId, THREAD_CONTEXT_LIMIT), mainSlice]);
+      const root = data.root && typeof data.root === "object" ? data.root : null;
+      const replies = Array.isArray(data.replies) ? data.replies : [];
+      const sinceMs = since ? Date.parse(since) || 0 : 0;
+      const triggerId = String(envelope.messageId || "");
+      const triggerMs = Date.parse(envelope.raw?.createdAt || "") || Infinity;
+      const botId = String(this.botUserId);
+      const inWindow = replies.filter((m) => {
+        const t = Date.parse(m.createdAt || "") || 0;
+        return t <= triggerMs && (!sinceMs || t > sinceMs);
+      });
+      const fresh = inWindow.filter((m) => !m.isDeleted && String(m._id || m.id || "") !== triggerId);
+      const stamps = [...inWindow.map((m) => m.createdAt), envelope.raw?.createdAt]
+        .filter((iso) => Date.parse(iso || ""));
+      const newest = stamps.sort((a, b) => Date.parse(a) - Date.parse(b)).pop();
+      if (root) {
+        const author = senderIdOf(root);
+        if (author) kazeeState.setThreadRootAuthor(chatId, rootId, author);
+      }
+      if (fresh.some((m) => senderIdOf(m) === botId)) kazeeState.markBotRepliedInThread(chatId, rootId);
+
+      const first = !since;
+      const rendered = fresh
+        .map((m) => ({ who: senderIdOf(m) === botId ? "You" : (m.sender?.name || "Someone"), body: this._contextBody(m, CONTEXT_BODY_LIMIT), ago: this._ago(m.createdAt) }))
+        .filter((m) => m.body);
+      const media = [
+        ...(first && root && !root.isDeleted ? this._mediaRefs(root, chatId, "Thread root") : []),
+        ...fresh.filter((m) => senderIdOf(m) !== botId)
+          .flatMap((m) => this._mediaRefs(m, chatId, `${m.sender?.name || "Someone"} in this thread (${m.createdAt || "unknown time"})`)),
+      ];
+      if (newest) kazeeState.setThreadWatermark(chatId, rootId, newest);
+      if (!first && !rendered.length && !media.length) return null;
+
+      const lines = ["[Kazee thread context]"];
+      if (first) {
+        lines.push("This conversation is a thread in this chat (its own conversation: your replies go into the thread).");
+        const mainRendered = mainBefore
+          .map((m) => ({ who: senderIdOf(m) === botId ? "You" : (m.sender?.name || "Someone"), body: this._contextBody(m, CONTEXT_BODY_LIMIT), ago: this._ago(m.createdAt) }))
+          .filter((m) => m.body);
+        if (mainRendered.length) {
+          lines.push("The main chat just before this thread started (oldest→newest):");
+          for (const m of mainRendered) lines.push(`  [${m.ago}] ${m.who}: ${m.body}`);
+        }
+        if (!root || root.isDeleted) {
+          lines.push("Thread root: (deleted or unavailable)");
+        } else {
+          const who = senderIdOf(root) === botId ? "You" : (root.sender?.name || "Someone");
+          const when = root.createdAt ? `${root.createdAt}, ${this._ago(root.createdAt)}` : "unknown time";
+          lines.push(`Thread root, posted by ${who} (${when}):`);
+          lines.push(`  ${this._contextBody(root, THREAD_ROOT_BODY_LIMIT) || "(no text)"}`);
+        }
+        if (rendered.length) {
+          lines.push(data.hasMoreBefore
+            ? "Replies so far (oldest→newest; earlier replies not shown):"
+            : "Replies so far (oldest→newest):");
+        }
+      } else {
+        lines.push("New replies in this thread since your last turn (oldest→newest):");
+      }
+      for (const m of rendered) lines.push(`  [${m.ago}] ${m.who}: ${m.body}`);
+      return { contextBlock: lines.join("\n"), media };
+    } catch (e) {
+      console.error("kazee thread context:", e.message);
+      return null;
+    }
+  }
+
+  // One message rendered for a context block: its text, a [type] note for
+  // media, clipped to `limit`.
+  _contextBody(m, limit) {
+    let body = (typeof m.content === "string" ? m.content : "").trim();
+    if (m.type && m.type !== "text" && m.type !== "interactive") {
+      body = `[${m.type}]${body ? " " + body : ""}`;
+    } else if (this._mediaRefs(m).length) {
+      body = `[attachment]${body ? " " + body : ""}`;
+    }
+    if (body.length > limit) body = body.slice(0, limit).trimEnd() + " …";
+    return body;
+  }
+
   // Message delta for a chat. With a watermark: chat-central's since-sync
   // (oldest-first, server-capped at 500). Without one — the chat's first-ever
   // engage — one recent page, which the server already returns in
-  // chronological order.
+  // chronological order. threads=true keeps thread-only replies out: they
+  // belong to their thread's conversation, not the main timeline's.
   async _messagesSince(chatId, sinceIso, count = COLD_START_WINDOW) {
     const base = `/messages/${encodeURIComponent(chatId)}/${encodeURIComponent(String(this.botUserId))}`;
     const query = sinceIso
-      ? `?since=${encodeURIComponent(sinceIso)}`
-      : `?page=1&messageCount=${count}`;
+      ? `?since=${encodeURIComponent(sinceIso)}&threads=true`
+      : `?page=1&messageCount=${count}&threads=true`;
     const res = await this._request("GET", base + query);
     const data = res?.data || res || {};
     if (data.error) throw new Error(String(data.error));
-    return Array.isArray(data.messages) ? data.messages : [];
+    // A server that ignores threads=true still must not leak thread-only
+    // replies into the main timeline's context.
+    return (Array.isArray(data.messages) ? data.messages : [])
+      .filter((m) => !threadRootOf(m) || m.alsoInChannel === true);
   }
 
   _ago(iso) {
@@ -484,32 +844,27 @@ class KazeeAdapter {
     };
     if (opts.replyTo) body.replyTo = opts.replyTo;
     if (buttons) body.interactive = { buttons };
+    const threadId = opts.threadId ? String(opts.threadId) : null;
+    if (threadId) body.threadRootId = threadId;
+    // Set once the thread refused the reply and it went to the main timeline
+    // (quoting the root) instead: "quote" while that quote is still on.
+    let fallback = null;
 
     for (let attempt = 0; attempt < 3; attempt++) {
+      let res;
       try {
-        const res = await this._request("POST", `/chat/${encodeURIComponent(channelId)}/message`, body);
-        // Return the created chat message's id so callers can edit it in place.
-        // The id can arrive as `_id` (raw Mongo doc) or `id` (serialized) and
-        // may sit on `res.message` or at the top level — mirror the reply-to
-        // fetch which already handles `m._id || m.id`. Never fall back to the
-        // envelope's `messageId`: that's ActionHero's numeric request counter,
-        // not a chat message id, and using it makes later edits 500 (and, when
-        // the real id is missing, a null return double-sends the reply).
-        const m = res?.message || res || {};
-        const id = m._id || m.id;
-        if (id) return String(id);
-        // POST returned 2xx but carried no message id (server fast-ack / payload
-        // fallback path). Returning null makes the caller treat a delivered
-        // reply as a failed send and resend it — the Kazee double-send. Signal
-        // success with a truthy, non-editable sentinel so nothing sends twice.
-        console.error("Kazee send: POST ok but no message id in response keys:", Object.keys(res || {}).join(","));
-        return true;
+        res = await this._request("POST", `/chat/${encodeURIComponent(channelId)}/message`, body);
       } catch (e) {
         const errMsg = e.message || "";
         // Don't retry on client errors (4xx) — they won't self-heal.
         const statusMatch = errMsg.match(/→ (\d{3})/);
         const status = statusMatch ? parseInt(statusMatch[1], 10) : 0;
         if (status >= 400 && status < 500) {
+          // The thread refused the reply (deleted root, not a thread-able
+          // message, ...): never lose it, post it in the main timeline once,
+          // quoting the root when that can still work.
+          const next = this._threadFallback(body, threadId, fallback, errMsg, "send");
+          if (next) { fallback = next; attempt--; continue; }
           console.error("Kazee send error (not retrying):", errMsg);
           return null;
         }
@@ -522,6 +877,50 @@ class KazeeAdapter {
         console.error("Kazee send error (exhausted retries):", errMsg);
         return null;
       }
+      // Posted. Nothing below may throw back into the retry loop: that would
+      // post the reply a second time.
+      // Return the created chat message's id so callers can edit it in place.
+      // The id can arrive as `_id` (raw Mongo doc) or `id` (serialized) and
+      // may sit on `res.message` or at the top level — mirror the reply-to
+      // fetch which already handles `m._id || m.id`. Never fall back to the
+      // envelope's `messageId`: that's ActionHero's numeric request counter,
+      // not a chat message id, and using it makes later edits 500 (and, when
+      // the real id is missing, a null return double-sends the reply).
+      const m = res?.message || res || {};
+      const id = m._id || m.id;
+      // body.threadRootId is gone when the reply fell back to the main
+      // timeline, so only a post that went INTO the thread marks it.
+      this._rememberSentSafely(id, body.threadRootId || null, channelId);
+      if (id) return String(id);
+      // POST returned 2xx but carried no message id (server fast-ack / payload
+      // fallback path). Returning null makes the caller treat a delivered
+      // reply as a failed send and resend it — the Kazee double-send. Signal
+      // success with a truthy, non-editable sentinel so nothing sends twice.
+      console.error("Kazee send: POST ok but no message id in response keys:", Object.keys(res || {}).join(","));
+      return true;
+    }
+    return null;
+  }
+
+  // One step of the INVALID_THREAD fallback for a REST post body (mutated in
+  // place). First refusal of the thread: drop threadRootId and quote the root
+  // instead (unless the refusal says the root is deleted). If the quote is
+  // refused as well: drop it too. Returns the new fallback stage, or null
+  // when there is nothing left to fall back from.
+  _threadFallback(body, threadId, stage, errMsg, what) {
+    if (!threadId) return null;
+    if (!stage) {
+      if (!body.threadRootId || !INVALID_THREAD_RE.test(errMsg)) return null;
+      delete body.threadRootId;
+      const quote = !body.replyTo && !/deleted/i.test(errMsg);
+      if (quote) body.replyTo = threadId;
+      console.error(`Kazee ${what}: thread ${threadId} refused (${errMsg.slice(0, 200)}); posting in the main timeline${quote ? ", quoting the thread root" : ""}`);
+      return quote ? "quote" : "plain";
+    }
+    if (stage === "quote" && body.replyTo === threadId) {
+      delete body.replyTo;
+      console.error(`Kazee ${what}: quoting thread root ${threadId} refused too; posting in the main timeline without the quote`);
+      return "plain";
     }
     return null;
   }
@@ -574,18 +973,19 @@ class KazeeAdapter {
     catch (e) { /* ignore */ }
   }
 
-  async sendVoice(channelId, oggPath) {
-    const ok = await this.sendFile(channelId, oggPath);
+  async sendVoice(channelId, oggPath, opts = {}) {
+    const ok = await this.sendFile(channelId, oggPath, undefined, opts);
     try { fs.unlinkSync(oggPath); } catch (e) {}
     return ok;
   }
 
-  async sendPhoto(channelId, filePath, caption) {
+  async sendPhoto(channelId, filePath, caption, opts = {}) {
     // Kazee's sendFile picks the right message type by extension already.
-    return this.sendFile(channelId, filePath, caption);
+    return this.sendFile(channelId, filePath, caption, opts);
   }
 
-  async sendFile(channelId, filePath, caption) {
+  async sendFile(channelId, filePath, caption, opts = {}) {
+    const threadId = opts && opts.threadId ? String(opts.threadId) : null;
     try {
       const buffer = fs.readFileSync(filePath);
       const fileName = path.basename(filePath);
@@ -616,16 +1016,29 @@ class KazeeAdapter {
         findMeCode: `oc-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
         mediaIds: [mediaId],
       };
+      if (threadId) payload.threadRootId = threadId;
       try {
         const res = await this._socketEmit("message:send", payload, 30000);
         if (res && res.code) {
+          if (threadId && INVALID_THREAD_RE.test(`${res.code} ${res.message || ""}`)) {
+            // The thread refused it: post in the main timeline (REST, which
+            // can quote the root) rather than lose the file.
+            const refusal = `${res.code}: ${res.message || ""}`;
+            const quote = !/deleted/i.test(refusal);
+            console.error(`Kazee sendFile: thread ${threadId} refused (${refusal}); posting in the main timeline${quote ? ", quoting the thread root" : ""}`);
+            return await this._sendMediaViaRest(channelId, mediaId, type, caption, { replyTo: quote ? threadId : null, fallbackOf: threadId });
+          }
           console.error(`Kazee message:send error (${res.code}), falling back to REST:`, res.message);
-          return await this._sendMediaViaRest(channelId, mediaId, type, caption);
+          return await this._sendMediaViaRest(channelId, mediaId, type, caption, { threadId });
         }
+        // chat-central acks callback(null, {message}): the id is on .message.
+        const sent = res?.message || res?.data || res || {};
+        const sentId = typeof sent === "object" ? (sent._id || sent.id) : null;
+        this._rememberSentSafely(sentId, threadId, channelId);
         return true;
       } catch (sockErr) {
         console.error("Kazee message:send unavailable, falling back to REST:", sockErr.message);
-        return await this._sendMediaViaRest(channelId, mediaId, type, caption);
+        return await this._sendMediaViaRest(channelId, mediaId, type, caption, { threadId });
       }
     } catch (e) {
       console.error("Kazee sendFile error:", e.message);
@@ -636,20 +1049,40 @@ class KazeeAdapter {
   // REST fallback for posting an already-uploaded Media doc when the socket
   // path is unavailable. Mirrors send()'s route (POST /chat/:id/message →
   // sendMessage action) but references the saved media by id.
-  async _sendMediaViaRest(channelId, mediaId, type, caption) {
-    try {
-      await this._request("POST", `/chat/${encodeURIComponent(channelId)}/message`, {
-        chat_id: channelId,
-        sender: this.botUserId,
-        content: caption || "",
-        type,
-        media_ids: [mediaId],
-        findMeCode: `oc-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-      });
+  // opts.threadId posts into that thread (with the same once-only
+  // INVALID_THREAD fallback as send); opts.replyTo quotes a message;
+  // opts.fallbackOf names the thread a main-timeline fallback is standing in
+  // for (so a refused quote of its root is dropped too).
+  async _sendMediaViaRest(channelId, mediaId, type, caption, opts = {}) {
+    const threadId = opts.threadId ? String(opts.threadId) : null;
+    const body = {
+      chat_id: channelId,
+      sender: this.botUserId,
+      content: caption || "",
+      type,
+      media_ids: [mediaId],
+      findMeCode: `oc-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    };
+    if (threadId) body.threadRootId = threadId;
+    if (opts.replyTo) body.replyTo = String(opts.replyTo);
+    const origin = threadId || (opts.fallbackOf ? String(opts.fallbackOf) : null);
+    let stage = !threadId && opts.fallbackOf ? (opts.replyTo ? "quote" : "plain") : null;
+    for (;;) {
+      let res;
+      try {
+        res = await this._request("POST", `/chat/${encodeURIComponent(channelId)}/message`, body);
+      } catch (e) {
+        const errMsg = e.message || "";
+        const statusMatch = errMsg.match(/→ (\d{3})/);
+        const status = statusMatch ? parseInt(statusMatch[1], 10) : 0;
+        const next = status >= 400 && status < 500 ? this._threadFallback(body, origin, stage, errMsg, "media send") : null;
+        if (next) { stage = next; continue; }
+        console.error("Kazee REST media send failed:", errMsg);
+        return false;
+      }
+      const m = res?.message || res || {};
+      this._rememberSentSafely(m._id || m.id, body.threadRootId || null, channelId);
       return true;
-    } catch (e) {
-      console.error("Kazee REST media send failed:", e.message);
-      return false;
     }
   }
 
@@ -668,11 +1101,14 @@ class KazeeAdapter {
         settled = true;
         reject(new Error(`Kazee ${event} ack timeout`));
       }, timeoutMs);
-      socket.emit(event, payload, (ack) => {
+      // Errors ack as the first argument ({code, message}); successes ack
+      // Node-style, callback(null, body), so take the second when the first
+      // is empty.
+      socket.emit(event, payload, (ack, data) => {
         if (settled) return;
         settled = true;
         clearTimeout(timer);
-        resolve(ack);
+        resolve(ack == null && data !== undefined ? data : ack);
       });
     });
   }
@@ -734,11 +1170,27 @@ class KazeeAdapter {
     return attempt;
   }
 
-  async typing(channelId, state) {
+  // opts.threadId shows the indicator inside that thread. chat-central drops
+  // a threadRootId that is not an ObjectId (the indicator would then show in
+  // the channel), so a malformed one is left out and logged once.
+  _typingThreadId(opts) {
+    const threadId = opts && opts.threadId ? String(opts.threadId) : "";
+    if (!threadId) return null;
+    if (OBJECT_ID_RE.test(threadId)) return threadId;
+    if (!this._typingThreadWarned.has(threadId)) {
+      this._typingThreadWarned.add(threadId);
+      console.error(`Kazee typing: thread id "${threadId.slice(0, 40)}" is not a 24-hex id; the indicator shows in the channel instead`);
+    }
+    return null;
+  }
+
+  async typing(channelId, state, opts = {}) {
     try {
       const chatId = String(channelId);
       if (!(await this._ensureJoinedRoom(chatId))) return;
       const payload = { chatId };
+      const threadRootId = this._typingThreadId(opts);
+      if (threadRootId) payload.threadRootId = threadRootId;
       if (state) payload.state = state;
       this._socket?.emit?.("typing:start", payload);
     } catch (e) {}
@@ -747,12 +1199,15 @@ class KazeeAdapter {
   // Socket channels keep rendering "typing…" until an explicit stop. Telegram
   // has no equivalent (its chat action self-expires), so this is Kazee-only and
   // called via optional chaining from the core typing heartbeat cleanup.
-  async typingStop(channelId) {
+  async typingStop(channelId, opts = {}) {
     const chatId = String(channelId);
     // Never join just to stop: a stop from a socket that never started is a
     // no-op server-side anyway, and joining here would race the teardown.
     if (!this._joinedRooms.has(chatId)) return;
-    try { this._socket?.emit?.("typing:stop", { chatId }); } catch (e) {}
+    const payload = { chatId };
+    const threadRootId = this._typingThreadId(opts);
+    if (threadRootId) payload.threadRootId = threadRootId;
+    try { this._socket?.emit?.("typing:stop", payload); } catch (e) {}
   }
 
   async downloadMedia(media) {
@@ -775,7 +1230,7 @@ class KazeeAdapter {
     const nameSuffix = keepName && !path.extname(media.fileName) && ext !== ".bin" ? ext : "";
     const localPath = keepName
       ? path.join(baseDir, media.fileName + nameSuffix)
-      : path.join(baseDir, `kz-${Date.now()}${ext}`);
+      : path.join(baseDir, `kz-${Date.now()}-${crypto.randomBytes(4).toString("hex")}${ext}`);
     await this._downloadUrl(url, localPath);
     return localPath;
   }