switchroom 0.13.52 → 0.13.54

package/telegram-plugin/typing-wrap.ts

@@ -1,26 +1,43 @@
 // Auto-wrap tool dispatch with a Telegram typing-indicator loop so the user
 // sees a live "agent is working" signal during the 3–30s gap where the
 // progress card is deliberately suppressed (its initialDelayMs is 3s).
-// The first tool call on a given chat fires the typing loop immediately so
-// there's no silent dead window before the progress card appears. Subsequent
-// calls on the same chat honour the debounce to avoid churn.
-// Surface tools own their own loop — see isSurfaceTool.
+// The first tool call on a given (chat, thread) fires the typing loop
+// immediately so there's no silent dead window before the progress card
+// appears. Subsequent calls on the same lane honour the debounce to avoid
+// churn. Surface tools own their own loop — see isSurfaceTool.
+//
+// Keying changed from `chatId` to `(chatId, threadId)` in PR3 of the
+// supergroup-mode rollout. In supergroup mode one agent owns many topics
+// in one chat; chatId-only keying made topic A's typing indicator die when
+// topic B's tool-call ended (last-stop-wins on a shared key). Per-thread
+// keying preserves independent typing loops across topics — matches the
+// per-(chat,thread) state model the rest of the gateway already uses.
+// Callers that don't yet carry a thread context pass `undefined` and
+// behave exactly as before (null thread collapses to `_` per chatKey()).
+
+import { chatKey } from './gateway/chat-key.js'
 
 export interface TypingWrapperDeps {
-  startTypingLoop: (chatId: string) => void
-  stopTypingLoop: (chatId: string) => void
+  startTypingLoop: (chatId: string, threadId?: number | null) => void
+  stopTypingLoop: (chatId: string, threadId?: number | null) => void
   isSurfaceTool: (toolName: string) => boolean
   debounceMs?: number
 }
 
 export interface TypingWrapper {
-  onToolUse: (toolUseId: string, chatId: string, toolName: string) => void
+  onToolUse: (
+    toolUseId: string,
+    chatId: string,
+    toolName: string,
+    threadId?: number | null,
+  ) => void
   onToolResult: (toolUseId: string) => void
   drainAll: () => void
 }
 
 interface Entry {
   chatId: string
+  threadId: number | null
   timer: ReturnType<typeof setTimeout>
   started: boolean
 }
@@ -28,29 +45,33 @@ interface Entry {
 export function createTypingWrapper(deps: TypingWrapperDeps): TypingWrapper {
   const debounceMs = deps.debounceMs ?? 500
   const pending = new Map<string, Entry>()
-  // Track chats that already have an active typing loop so the first
-  // tool call fires immediately while subsequent calls use the debounce.
-  const activeChats = new Set<string>()
+  // Track per-(chat,thread) lanes that already have an active typing loop
+  // so the first tool call on a lane fires immediately while subsequent
+  // calls on the same lane use the debounce.
+  const activeLanes = new Set<string>()
 
   return {
-    onToolUse(toolUseId, chatId, toolName) {
+    onToolUse(toolUseId, chatId, toolName, threadId) {
       if (!toolUseId) return
       if (deps.isSurfaceTool(toolName)) return
+      const tid = threadId ?? null
+      const lane = chatKey(chatId, tid) as string
       // Replace any pre-existing entry for the same id defensively.
       const prior = pending.get(toolUseId)
       if (prior) {
         clearTimeout(prior.timer)
-        if (prior.started) deps.stopTypingLoop(prior.chatId)
+        if (prior.started) deps.stopTypingLoop(prior.chatId, prior.threadId)
         pending.delete(toolUseId)
       }
-      // First tool on this chat: fire immediately rather than waiting for
+      // First tool on this lane: fire immediately rather than waiting for
       // the debounce — this closes the silent dead window before the first
       // progress card appears.
-      if (!activeChats.has(chatId)) {
-        deps.startTypingLoop(chatId)
-        activeChats.add(chatId)
+      if (!activeLanes.has(lane)) {
+        deps.startTypingLoop(chatId, tid)
+        activeLanes.add(lane)
         const entry: Entry = {
           chatId,
+          threadId: tid,
           started: true,
           timer: setTimeout(() => {}, 0), // no-op sentinel
         }
@@ -59,9 +80,10 @@ export function createTypingWrapper(deps: TypingWrapperDeps): TypingWrapper {
       }
       const entry: Entry = {
         chatId,
+        threadId: tid,
         started: false,
         timer: setTimeout(() => {
-          deps.startTypingLoop(chatId)
+          deps.startTypingLoop(chatId, tid)
           entry.started = true
         }, debounceMs),
       }
@@ -74,8 +96,8 @@ export function createTypingWrapper(deps: TypingWrapperDeps): TypingWrapper {
       if (!entry) return
       clearTimeout(entry.timer)
       if (entry.started) {
-        deps.stopTypingLoop(entry.chatId)
-        activeChats.delete(entry.chatId)
+        deps.stopTypingLoop(entry.chatId, entry.threadId)
+        activeLanes.delete(chatKey(entry.chatId, entry.threadId) as string)
       }
       pending.delete(toolUseId)
     },
@@ -83,10 +105,10 @@ export function createTypingWrapper(deps: TypingWrapperDeps): TypingWrapper {
     drainAll() {
       for (const entry of pending.values()) {
         clearTimeout(entry.timer)
-        if (entry.started) deps.stopTypingLoop(entry.chatId)
+        if (entry.started) deps.stopTypingLoop(entry.chatId, entry.threadId)
       }
       pending.clear()
-      activeChats.clear()
+      activeLanes.clear()
     },
   }
 }

package/vendor/hindsight-memory/scripts/lib/gateway_ipc.py

@@ -54,6 +54,41 @@ def extract_chat_id_from_prompt(prompt: str) -> Optional[str]:
     return chat_id or None
 
 
+# Switchroom PR6a — extract topic context (chat_id + message_thread_id)
+# from the `<channel ...>` envelope. message_thread_id is present only
+# when the inbound came from a forum topic in a supergroup; for DMs and
+# fleet-shared groups it's absent. Topic alias resolution is the
+# caller's responsibility (env-injected JSON map of thread_id → alias).
+_THREAD_ID_RE = re.compile(
+    r"<channel\b[^>]*\bmessage_thread_id=[\"']([^\"']+)[\"']",
+    re.IGNORECASE,
+)
+
+
+def extract_topic_from_prompt(
+    prompt: str,
+) -> tuple[Optional[str], Optional[str]]:
+    """Pull (chat_id, message_thread_id) out of the channel envelope.
+
+    Returns ``(None, None)`` when the prompt isn't channel-wrapped.
+    Returns ``(chat_id, None)`` for DMs / non-forum chats where
+    `message_thread_id` is absent.
+
+    Both values are strings (mirroring the wire format — Telegram
+    thread_ids are numeric but we keep them as strings for cache-key
+    stability and config-map lookups).
+    """
+    chat_id = extract_chat_id_from_prompt(prompt)
+    if chat_id is None:
+        return None, None
+    head = prompt[:1024] if isinstance(prompt, str) else ""
+    tmatch = _THREAD_ID_RE.search(head)
+    thread_id = tmatch.group(1).strip() if tmatch else None
+    if thread_id == "":
+        thread_id = None
+    return chat_id, thread_id
+
+
 def gateway_socket_path() -> Optional[str]:
     """Resolve the gateway socket path for the current agent.
 

package/vendor/hindsight-memory/scripts/recall.py

@@ -58,7 +58,7 @@ from lib.content import (
 )
 from lib.daemon import get_api_url
 from lib.directives import fetch_active_directives, format_active_directives_block
-from lib.gateway_ipc import extract_chat_id_from_prompt, update_placeholder
+from lib.gateway_ipc import extract_chat_id_from_prompt, extract_topic_from_prompt, update_placeholder
 from lib.state import read_state, write_state
 
 LAST_RECALL_STATE = "last_recall.json"
@@ -99,6 +99,70 @@ DEMOTE_TAG_VARIANTS = (
     "no-recall",
 )
 
+# Switchroom PR6 — supergroup-mode topic filter mode.
+#
+# Controls how memories from OTHER topics are surfaced to the model
+# during recall. Default is "soft-preamble": all topic-tagged memories
+# are returned (the model decides relevance via the preamble that names
+# the active topic). "hard-filter" drops any memory whose stored
+# `metadata.thread_id` doesn't match the active prompt's thread_id —
+# the escape hatch if instrumentation shows binding failures (model
+# applying the right memory to the wrong topic).
+#
+# The mode is process-wide via env var. Memories with no thread_id
+# tag (legacy retains pre-PR6, or fleet-shared/DM agents) are NEVER
+# dropped — they pass through both modes regardless of active topic.
+TOPIC_FILTER_MODE_ENV = "HINDSIGHT_TOPIC_FILTER_MODE"
+TOPIC_FILTER_MODES = ("soft-preamble", "hard-filter")
+
+
+def _topic_filter_mode() -> str:
+    raw = os.environ.get(TOPIC_FILTER_MODE_ENV, "").strip().lower()
+    if raw in TOPIC_FILTER_MODES:
+        return raw
+    return "soft-preamble"
+
+
+def _filter_by_active_topic(results: list, active_thread_id: str | None) -> tuple[list, int]:
+    """When hard-filter mode is on AND we know the active thread, drop
+    any memory whose stored metadata.thread_id is set to a different
+    value. Untagged memories pass through unconditionally.
+
+    Returns (filtered_results, dropped_count).
+    """
+    if active_thread_id is None:
+        return results, 0
+    kept: list = []
+    dropped = 0
+    for m in results:
+        meta = m.get("metadata") if isinstance(m, dict) else None
+        if not isinstance(meta, dict):
+            kept.append(m)
+            continue
+        source_thread = meta.get("thread_id")
+        if source_thread is None or str(source_thread) == str(active_thread_id):
+            kept.append(m)
+        else:
+            dropped += 1
+    return kept, dropped
+
+
+def _summarise_source_topics(results: list) -> dict:
+    """Build a {thread_id: count} summary of recalled memories'
+    source topics. Used for instrumented binding-failure analysis
+    in the recall log.
+    """
+    summary: dict = {}
+    for m in results:
+        meta = m.get("metadata") if isinstance(m, dict) else None
+        if not isinstance(meta, dict):
+            summary["__untagged__"] = summary.get("__untagged__", 0) + 1
+            continue
+        tid = meta.get("thread_id")
+        key = str(tid) if tid is not None else "__no_thread__"
+        summary[key] = summary.get(key, 0) + 1
+    return summary
+
 # Switchroom #432 phase 4.3 — recall telemetry log.
 #
 # Every recall (cache hit or miss) appends a JSONL record to
@@ -123,15 +187,29 @@ def _cache_ttl_secs() -> int:
         return 0
 
 
-def _cache_key(session_id: str, prompt: str, bank_id: str, extra_banks: list) -> str:
+def _cache_key(
+    session_id: str,
+    prompt: str,
+    bank_id: str,
+    extra_banks: list,
+    active_thread_id: str | None = None,
+) -> str:
     """Stable hash for cache keying. Session_id is included so a new
     session always misses, regardless of the TTL setting. Extra banks
-    are sorted so list-order doesn't change the key."""
+    are sorted so list-order doesn't change the key.
+
+    PR6a: `active_thread_id` is included so cross-topic prompts in
+    supergroup mode (same session, same model, same prompt verbatim
+    but different topic) don't collide on the cache. Empty/None
+    collapses to the empty string — backward-compatible for
+    fleet-shared / DM agents where no thread_id is present.
+    """
     parts = [
         session_id or "",
         prompt or "",
         bank_id or "",
         ",".join(sorted(extra_banks or [])),
+        active_thread_id or "",
     ]
     payload = "\x1f".join(parts)
     return hashlib.sha256(payload.encode("utf-8")).hexdigest()
@@ -458,6 +536,25 @@ def main():
     if placeholder_chat_id:
         update_placeholder(placeholder_chat_id, "📚 recalling memories")
 
+    # PR6a — supergroup-mode topic context for the current turn.
+    # active_thread_id is the message_thread_id from the inbound
+    # envelope, used to (a) key the cache so cross-topic prompts
+    # don't collide, (b) optionally hard-filter memories by source
+    # topic, and (c) log source-vs-active distribution for
+    # binding-failure instrumentation.
+    active_chat_id, active_thread_id = extract_topic_from_prompt(prompt)
+    active_topic_alias = None
+    if active_thread_id is not None:
+        aliases_json = os.environ.get("HINDSIGHT_TOPIC_ALIASES_JSON", "")
+        if aliases_json:
+            try:
+                aliases = json.loads(aliases_json)
+                if isinstance(aliases, dict):
+                    inverse = {str(v): k for k, v in aliases.items()}
+                    active_topic_alias = inverse.get(str(active_thread_id))
+            except (json.JSONDecodeError, ValueError, TypeError):
+                pass
+
     # Resolve API URL (handles all three connection modes)
     def _dbg(*a):
         debug_log(config, *a)
@@ -483,7 +580,7 @@ def main():
     # Whole-session-scoped, opt-in via HINDSIGHT_RECALL_CACHE_TTL_SECS.
     cache_ttl = _cache_ttl_secs()
     cache_key = (
-        _cache_key(session_id, prompt, bank_id, additional_banks)
+        _cache_key(session_id, prompt, bank_id, additional_banks, active_thread_id)
         if cache_ttl > 0
         else ""
     )
@@ -507,6 +604,13 @@ def main():
                 "demoted_count": 0,
                 "capped": False,
                 "cache_hit": True,
+                # PR6 — record the active topic on cache hits too so the
+                # log is uniformly queryable (cache_key now includes
+                # active_thread_id, so a hit means the prior recall was
+                # for the same topic — no source_topics inferable here).
+                "active_thread_id": active_thread_id,
+                "active_topic_alias": active_topic_alias,
+                "topic_filter_mode": _topic_filter_mode(),
             })
             return
         debug_log(config, f"Recall cache MISS (key={cache_key[:12]}…)")
@@ -612,6 +716,28 @@ def main():
     if demoted_count > 0:
         debug_log(config, f"Filtered {demoted_count} demote-from-recall memories")
 
+    # PR6 — capture source-topic distribution BEFORE optional
+    # hard-filter so we can log the would-have-leaked count for
+    # binding-failure analysis. Computed unconditionally so the
+    # log row carries this for soft-preamble mode too (the
+    # whole point is to instrument binding rate over time).
+    source_topic_summary = _summarise_source_topics(results)
+
+    # PR6b — optional hard topic filter. Default soft-preamble (no-op);
+    # operator flips HINDSIGHT_TOPIC_FILTER_MODE=hard-filter when
+    # binding failures are observed. See _filter_by_active_topic and
+    # the TOPIC_FILTER_MODE_ENV comment block above for design notes.
+    topic_filter_mode = _topic_filter_mode()
+    topic_dropped = 0
+    if topic_filter_mode == "hard-filter":
+        results, topic_dropped = _filter_by_active_topic(results, active_thread_id)
+        if topic_dropped > 0:
+            debug_log(
+                config,
+                f"Topic hard-filter dropped {topic_dropped} cross-topic "
+                f"memories (active_thread_id={active_thread_id})",
+            )
+
     # Switchroom #475 — lexical-overlap relevance gate. Drops memories
     # whose Jaccard overlap with the query is below
     # `recallMinOverlap` (default 0.0 = disabled). Runs after the
@@ -660,9 +786,29 @@ def main():
         memories_formatted = format_memories(results)
         preamble = config.get("recallPromptPreamble", "")
         current_time = format_current_time()
+
+        # PR6 — supergroup-mode topic preamble (neutral tone per
+        # 2026-05-27 product decision). Only added when we know the
+        # active topic AND any of the recalled memories carries a
+        # thread_id tag — i.e. we have something for the model to
+        # be "topic-aware" about. Fleet-shared / DM agents never
+        # see this line.
+        topic_line = ""
+        if active_thread_id is not None and any(
+            isinstance(m.get("metadata"), dict)
+            and m["metadata"].get("thread_id") is not None
+            for m in results
+        ):
+            topic_label = active_topic_alias or f"thread {active_thread_id}"
+            topic_line = (
+                f"Current topic: {topic_label}. Recalled memories are "
+                f"tagged with their source topic.\n"
+            )
+
         memories_block = (
             f"<hindsight_memories>\n"
             f"{preamble}\n"
+            f"{topic_line}"
             f"Current time - {current_time}\n\n"
             f"{memories_formatted}\n"
             f"</hindsight_memories>"
@@ -732,6 +878,20 @@ def main():
             if isinstance(m, dict) and m.get("id")
         ],
         "cache_hit": False,
+        # PR6 — instrumentation for binding-failure analysis.
+        # `active_thread_id`: the current prompt's topic (null on
+        # DM / fleet-shared). `source_topics`: distribution of
+        # source thread_ids in the recall set (before optional
+        # hard-filter). `topic_filter_mode`: "soft-preamble" or
+        # "hard-filter". `topic_dropped`: count dropped by hard
+        # filter. From these fields we can derive the cross-topic
+        # recall rate over time and decide whether to flip to
+        # hard-filter mode based on real data.
+        "active_thread_id": active_thread_id,
+        "active_topic_alias": active_topic_alias,
+        "source_topics": source_topic_summary,
+        "topic_filter_mode": topic_filter_mode,
+        "topic_dropped": topic_dropped,
     })
 
     # Output JSON for Claude Code hook system

package/vendor/hindsight-memory/scripts/retain.py

@@ -225,6 +225,58 @@ def run_retain(hook_input: dict, force: bool = False) -> dict:
     for k, v in config.get("retainMetadata", {}).items():
         metadata[k] = _resolve_template(str(v))
 
+    # Switchroom PR6a — topic tagging for supergroup-mode agents.
+    # Scan the messages we're retaining for the latest `<channel
+    # chat_id=... message_thread_id=...>` envelope and stamp the
+    # tuple into metadata. Downstream (recall.py) uses this to log
+    # active-vs-source topic for binding-failure analysis and to
+    # support hard-filter mode when an operator opts in.
+    #
+    # No-op for fleet-shared / DM topology where every inbound from
+    # this agent carries the same chat_id (or no chat envelope at all
+    # for interactive / cron-only sessions) — the metadata is added
+    # but doesn't change behaviour.
+    try:
+        from lib.gateway_ipc import extract_topic_from_prompt
+        topic_chat_id = None
+        topic_thread_id = None
+        # Walk in reverse — most recent user message is the authoritative
+        # "active topic" at retain time.
+        for m in reversed(messages_to_retain):
+            if not isinstance(m, dict) or m.get("role") != "user":
+                continue
+            content = m.get("content")
+            text = content if isinstance(content, str) else (
+                # Claude Code list-content shape: [{type:"text", text:"..."}, ...]
+                next((p.get("text", "") for p in content if isinstance(p, dict) and p.get("type") == "text"), "")
+                if isinstance(content, list) else ""
+            )
+            c_id, t_id = extract_topic_from_prompt(text)
+            if c_id is not None:
+                topic_chat_id, topic_thread_id = c_id, t_id
+                break
+        if topic_chat_id is not None:
+            metadata["chat_id"] = topic_chat_id
+            if topic_thread_id is not None:
+                metadata["thread_id"] = topic_thread_id
+                # Resolve alias from operator-injected env map.
+                aliases_json = os.environ.get("HINDSIGHT_TOPIC_ALIASES_JSON", "")
+                if aliases_json:
+                    try:
+                        aliases = json.loads(aliases_json)
+                        # aliases is {alias_name: thread_id_int_or_str}; build
+                        # the inverse lookup once.
+                        if isinstance(aliases, dict):
+                            inverse = {str(v): k for k, v in aliases.items()}
+                            alias = inverse.get(str(topic_thread_id))
+                            if alias:
+                                metadata["topic_alias"] = alias
+                    except (json.JSONDecodeError, ValueError, TypeError):
+                        pass  # malformed env is non-fatal
+    except Exception as e:
+        # Topic tagging is best-effort — never fail a retain over it.
+        debug_log(config, f"Topic tagging skipped: {e}")
+
     debug_log(
         config, f"Retaining to bank '{bank_id}', doc '{document_id}', {message_count} messages, {len(transcript)} chars"
     )

package/vendor/hindsight-memory/scripts/tests/test_gateway_ipc.py

@@ -25,11 +25,53 @@ if SCRIPTS_DIR not in sys.path:
 
 from lib.gateway_ipc import (  # noqa: E402
     extract_chat_id_from_prompt,
+    extract_topic_from_prompt,
     gateway_socket_path,
     update_placeholder,
 )
 
 
+class ExtractTopicTests(unittest.TestCase):
+    """PR6a — (chat_id, message_thread_id) extraction for supergroup mode."""
+
+    def test_dm_returns_chat_id_thread_none(self):
+        # DM and fleet-shared envelopes carry chat_id only.
+        prompt = '<channel source="switchroom-telegram" chat_id="12345">hi</channel>'
+        self.assertEqual(extract_topic_from_prompt(prompt), ("12345", None))
+
+    def test_supergroup_topic_returns_both(self):
+        prompt = (
+            '<channel source="switchroom-telegram" '
+            'chat_id="-1001234" message_thread_id="17">hi</channel>'
+        )
+        self.assertEqual(extract_topic_from_prompt(prompt), ("-1001234", "17"))
+
+    def test_attribute_order_independent(self):
+        prompt = (
+            '<channel message_thread_id="42" chat_id="999" '
+            'source="x">hi</channel>'
+        )
+        self.assertEqual(extract_topic_from_prompt(prompt), ("999", "42"))
+
+    def test_single_quoted_thread_id(self):
+        prompt = "<channel chat_id='1' message_thread_id='7'>hi</channel>"
+        self.assertEqual(extract_topic_from_prompt(prompt), ("1", "7"))
+
+    def test_no_channel_envelope_returns_none_pair(self):
+        self.assertEqual(extract_topic_from_prompt("plain prompt"), (None, None))
+
+    def test_empty_thread_id_collapses_to_none(self):
+        # Defensive against malformed envelopes that include the attribute
+        # but with no value.
+        prompt = '<channel chat_id="1" message_thread_id="">hi</channel>'
+        self.assertEqual(extract_topic_from_prompt(prompt), ("1", None))
+
+    def test_only_inspects_first_kb(self):
+        # Pad BEFORE the envelope; both chat_id AND thread_id should be lost.
+        prompt = ("x" * 2000) + '<channel chat_id="1" message_thread_id="7">hi</channel>'
+        self.assertEqual(extract_topic_from_prompt(prompt), (None, None))
+
+
 class ExtractChatIdTests(unittest.TestCase):
     def test_double_quoted_attribute(self):
         prompt = '<channel source="switchroom-telegram" chat_id="12345" thread_id="-">\nhi\n</channel>'

package/vendor/hindsight-memory/scripts/tests/test_recall_topic_filter.py

@@ -0,0 +1,139 @@
+"""PR6 — unit tests for recall.py's topic-aware helpers.
+
+Covers:
+  - _filter_by_active_topic — drops memories whose metadata.thread_id
+    differs from the active prompt's thread_id; passes through untagged
+    legacy memories.
+  - _summarise_source_topics — distribution counts used in the recall
+    log for binding-failure instrumentation.
+  - _topic_filter_mode — env-var parsing with safe default.
+  - _cache_key — active_thread_id participates in hash (cross-topic
+    prompts in supergroup mode mustn't collide on the cache).
+
+Stdlib-only.
+"""
+
+import os
+import sys
+import unittest
+
+SCRIPTS_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+if SCRIPTS_DIR not in sys.path:
+    sys.path.insert(0, SCRIPTS_DIR)
+
+from recall import (  # noqa: E402
+    _cache_key,
+    _filter_by_active_topic,
+    _summarise_source_topics,
+    _topic_filter_mode,
+)
+
+
+def _mem(thread_id):
+    """Fake memory record with the metadata shape recall sees."""
+    return {"id": f"m{thread_id}", "metadata": {"thread_id": thread_id}}
+
+
+def _untagged_mem(suffix=""):
+    return {"id": f"u{suffix}", "metadata": {"retained_at": "2026-01-01"}}
+
+
+class FilterByActiveTopicTests(unittest.TestCase):
+    def test_drops_cross_topic_when_active_set(self):
+        results = [_mem("17"), _mem("31"), _mem("17")]
+        kept, dropped = _filter_by_active_topic(results, "17")
+        self.assertEqual(len(kept), 2)
+        self.assertEqual(dropped, 1)
+        self.assertTrue(all(m["metadata"]["thread_id"] == "17" for m in kept))
+
+    def test_passes_through_untagged_memories(self):
+        # Legacy memories (pre-PR6 retain) have no thread_id — must
+        # never be dropped, regardless of active topic.
+        results = [_mem("17"), _untagged_mem(), _mem("31"), _untagged_mem("b")]
+        kept, dropped = _filter_by_active_topic(results, "17")
+        # Kept: the 17 tagged + both untagged.
+        self.assertEqual(len(kept), 3)
+        self.assertEqual(dropped, 1)
+
+    def test_no_active_thread_is_passthrough(self):
+        # DM / fleet-shared agents have no active_thread_id; the
+        # filter is a no-op regardless of mode.
+        results = [_mem("17"), _mem("31"), _untagged_mem()]
+        kept, dropped = _filter_by_active_topic(results, None)
+        self.assertEqual(len(kept), 3)
+        self.assertEqual(dropped, 0)
+
+    def test_str_int_equivalence(self):
+        # Metadata can carry thread_ids as either string or int
+        # depending on how retain serialized them. The active_thread_id
+        # is always string (envelope is parsed as text). Compare as
+        # strings.
+        results = [{"id": "m", "metadata": {"thread_id": 17}}]  # numeric
+        kept, dropped = _filter_by_active_topic(results, "17")
+        self.assertEqual(len(kept), 1)
+        self.assertEqual(dropped, 0)
+
+
+class SummariseSourceTopicsTests(unittest.TestCase):
+    def test_counts_by_thread(self):
+        results = [_mem("17"), _mem("17"), _mem("31")]
+        self.assertEqual(_summarise_source_topics(results), {"17": 2, "31": 1})
+
+    def test_untagged_bucket(self):
+        results = [_mem("17"), _untagged_mem(), _untagged_mem()]
+        summary = _summarise_source_topics(results)
+        self.assertEqual(summary["17"], 1)
+        self.assertEqual(summary["__no_thread__"], 2)
+
+    def test_missing_metadata_bucket(self):
+        results = [{"id": "x"}]  # no metadata key at all
+        self.assertEqual(_summarise_source_topics(results), {"__untagged__": 1})
+
+
+class TopicFilterModeTests(unittest.TestCase):
+    def setUp(self):
+        self._saved = os.environ.get("HINDSIGHT_TOPIC_FILTER_MODE")
+        os.environ.pop("HINDSIGHT_TOPIC_FILTER_MODE", None)
+
+    def tearDown(self):
+        if self._saved is None:
+            os.environ.pop("HINDSIGHT_TOPIC_FILTER_MODE", None)
+        else:
+            os.environ["HINDSIGHT_TOPIC_FILTER_MODE"] = self._saved
+
+    def test_default_is_soft_preamble(self):
+        self.assertEqual(_topic_filter_mode(), "soft-preamble")
+
+    def test_hard_filter_env(self):
+        os.environ["HINDSIGHT_TOPIC_FILTER_MODE"] = "hard-filter"
+        self.assertEqual(_topic_filter_mode(), "hard-filter")
+
+    def test_unknown_value_falls_back_to_default(self):
+        # Operator typos shouldn't silently enable a strict mode.
+        os.environ["HINDSIGHT_TOPIC_FILTER_MODE"] = "strict"
+        self.assertEqual(_topic_filter_mode(), "soft-preamble")
+
+    def test_case_insensitive(self):
+        os.environ["HINDSIGHT_TOPIC_FILTER_MODE"] = "Hard-Filter"
+        self.assertEqual(_topic_filter_mode(), "hard-filter")
+
+
+class CacheKeyIncludesActiveTopicTests(unittest.TestCase):
+    def test_same_prompt_different_topic_misses(self):
+        k1 = _cache_key("sess", "what's up?", "bank", [], "17")
+        k2 = _cache_key("sess", "what's up?", "bank", [], "31")
+        self.assertNotEqual(k1, k2)
+
+    def test_backward_compat_no_topic(self):
+        # Pre-PR6 callers (none after this PR, but the param is
+        # optional so they couldn't break) get a stable key.
+        k1 = _cache_key("sess", "p", "bank", [])
+        k2 = _cache_key("sess", "p", "bank", [], None)
+        k3 = _cache_key("sess", "p", "bank", [], "")
+        # All three collapse to the empty-thread case → same hash.
+        self.assertEqual(k1, k2)
+        self.assertEqual(k1, k3)
+
+
+if __name__ == "__main__":
+    unittest.main()