switchroom 0.19.2 → 0.19.4

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

@@ -0,0 +1,413 @@
+"""Switchroom hindsight-leverage E1 / PR8 (#3369) — bounded transcript-grep
+fallback when the fact layer is empty pre-reconcile.
+
+Acceptance guarantees (outcomes, not code paths):
+
+  1. **Fires on all-zero + no deadline hit.** Every bank returns zero results
+     and no slot timed out → recall injects a ``<hindsight_transcript_fallback>``
+     block containing the recent session turn(s) that mention the query's
+     terms, and the recall_log row records ``transcript_fallback=True``.
+
+  2. **Does NOT fire when any bank returned memories.** A non-empty bank result
+     suppresses the fallback entirely (no fallback block, log False) — the
+     fact layer is not empty.
+
+  3. **Does NOT fire when a bank hit its deadline.** deadline_hit True (a bank
+     abandoned at the shared deadline) means the empty result set may be a
+     TIMEOUT, not a genuinely empty fact layer — the #3369 sequencing
+     constraint — so the fallback is suppressed even though results are empty.
+
+  4. **Byte bound holds.** With a small ``…MaxBytes``, only the transcript TAIL
+     is read: a query-matching line that lives only in the (discarded) HEAD is
+     never surfaced, and ``transcript_fallback_bytes_read`` never exceeds the
+     configured cap.
+
+  5. **Turn + char bounds hold.** ``…MaxTurns`` caps the number of injected
+     turns; ``…MaxChars`` caps the emitted characters and sets the
+     ``transcript_fallback_truncated`` telemetry flag.
+
+  6. **Config gate + relevance.** ``recallTranscriptFallback=False`` disables it;
+     a transcript with no term overlap with the query never fires.
+
+Stdlib-only (unittest); runs under ``python3 -m unittest discover tests/``
+from ``scripts/``.
+"""
+
+import io
+import json
+import os
+import shutil
+import sys
+import tempfile
+import threading
+import time
+import unittest
+from unittest.mock import patch
+
+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)
+
+import recall  # noqa: E402
+
+# Query terms: decide, auth, flow, week (stopwords stripped by _overlap_tokens).
+BARE = "what did we decide about the auth flow last week"
+
+
+def _memory(text, mem_id=None):
+    out = {"text": text, "type": "fact", "mentioned_at": "2026-01-01"}
+    if mem_id is not None:
+        out["id"] = mem_id
+    return out
+
+
+class _Client:
+    """Fake HindsightClient with per-bank sleep + result control."""
+
+    def __init__(self, bank_sleep=None, bank_results=None, directives=None,
+                 bank_errors=None):
+        self._bank_sleep = bank_sleep or {}
+        self._bank_results = bank_results or {}
+        self._directives = directives or []
+        # {bank_id: Exception instance} — raised (hard, non-timeout error) to
+        # simulate a connection-refused / 5xx / daemon-down outage.
+        self._bank_errors = bank_errors or {}
+        self._lock = threading.Lock()
+        self.recall_calls = []
+
+    def list_directives(self, bank_id, active_only=True, timeout=2):
+        return {"items": list(self._directives)}
+
+    def recall(self, bank_id, query, **kwargs):
+        with self._lock:
+            self.recall_calls.append(bank_id)
+        sleep_s = self._bank_sleep.get(bank_id, 0.0)
+        if sleep_s:
+            time.sleep(sleep_s)
+        err = self._bank_errors.get(bank_id)
+        if err is not None:
+            raise err
+        return {"results": list(self._bank_results.get(bank_id, []))}
+
+
+def _nested_line(role, text):
+    """One Claude Code nested-format transcript line."""
+    return json.dumps({
+        "type": role,
+        "uuid": f"u-{abs(hash((role, text))) % 10_000_000}",
+        "message": {"role": role, "content": text},
+    })
+
+
+class _Harness(unittest.TestCase):
+    def setUp(self):
+        self._tmpdir = tempfile.mkdtemp(prefix="recall-fallback-test-")
+        self._prev = os.environ.get("CLAUDE_PLUGIN_DATA")
+        os.environ["CLAUDE_PLUGIN_DATA"] = self._tmpdir
+
+    def tearDown(self):
+        shutil.rmtree(self._tmpdir, ignore_errors=True)
+        if self._prev is None:
+            os.environ.pop("CLAUDE_PLUGIN_DATA", None)
+        else:
+            os.environ["CLAUDE_PLUGIN_DATA"] = self._prev
+
+    def _write_transcript(self, lines):
+        path = os.path.join(self._tmpdir, "transcript.jsonl")
+        with open(path, "w", encoding="utf-8") as f:
+            f.write("\n".join(lines) + "\n")
+        return path
+
+    def _read_log(self):
+        path = os.path.join(self._tmpdir, "state", "recall_log.jsonl")
+        if not os.path.isfile(path):
+            return []
+        with open(path, encoding="utf-8") as f:
+            return [json.loads(line) for line in f if line.strip()]
+
+    def _run(self, client, config_extra=None, prompt=BARE, transcript_path=""):
+        hook_input = {
+            "prompt": prompt,
+            "session_id": "test-session",
+            "transcript_path": transcript_path,
+            "cwd": "/tmp",
+        }
+        config = {
+            "autoRecall": True,
+            "bankId": "own-bank",
+            "recallMaxTokens": 1024,
+            "recallBudget": "mid",
+            "recallContextTurns": 1,
+            "recallMaxQueryChars": 800,
+            "recallPromptPreamble": "",
+            # Keep the shared deadline generous unless a test overrides it.
+            "recallParallelDeadlineSeconds": 5,
+            # Fallback bounds (defaults mirror config.py; explicit for clarity).
+            "recallTranscriptFallback": True,
+            "recallTranscriptFallbackMaxBytes": 262144,
+            "recallTranscriptFallbackMaxTurns": 6,
+            "recallTranscriptFallbackMaxChars": 2000,
+            "recallTranscriptFallbackDeadlineMs": 1500,
+        }
+        if config_extra:
+            config.update(config_extra)
+        stdout = io.StringIO()
+        stderr = io.StringIO()
+        with patch.object(recall, "load_config", return_value=config), patch.object(
+            recall, "get_api_url", return_value="http://localhost:18888"
+        ), patch.object(recall, "HindsightClient", return_value=client), patch.object(
+            recall, "ensure_bank_mission", return_value=None
+        ), patch.object(recall, "write_state", return_value=None), patch(
+            "sys.stdin", new=io.StringIO(json.dumps(hook_input))
+        ), patch("sys.stdout", new=stdout), patch("sys.stderr", new=stderr):
+            recall.main()
+        raw = stdout.getvalue()
+        context = None
+        if raw.strip():
+            context = json.loads(raw)["hookSpecificOutput"]["additionalContext"]
+        return context
+
+
+class FiresOnEmptyFactLayer(_Harness):
+    def test_fires_when_all_banks_zero_and_no_deadline_hit(self):
+        transcript = self._write_transcript([
+            _nested_line("user", "hello there"),
+            _nested_line("user", "we should redo the auth flow with PKCE"),
+            _nested_line("assistant", "agreed, the auth flow now uses PKCE"),
+            _nested_line("user", "thanks"),
+        ])
+        client = _Client(bank_results={"own-bank": []})
+        context = self._run(client, transcript_path=transcript)
+
+        self.assertIsNotNone(context, "fallback should have produced context")
+        self.assertIn("<hindsight_transcript_fallback>", context)
+        self.assertIn("PKCE", context)
+        # Chronological order preserved (user turn before assistant turn).
+        self.assertLess(
+            context.index("we should redo the auth flow"),
+            context.index("the auth flow now uses PKCE"),
+        )
+
+        e = self._read_log()[0]
+        self.assertTrue(e["transcript_fallback"])
+        self.assertGreaterEqual(e["transcript_fallback_turns"], 2)
+        self.assertGreater(e["transcript_fallback_chars"], 0)
+        self.assertFalse(e["deadline_hit"])
+        self.assertEqual(e["result_count"], 0)
+
+    def test_no_match_in_transcript_does_not_fire(self):
+        # Transcript turns share NO terms with the auth-flow query.
+        transcript = self._write_transcript([
+            _nested_line("user", "what should we cook for dinner tonight"),
+            _nested_line("assistant", "maybe a pasta with roasted vegetables"),
+        ])
+        client = _Client(bank_results={"own-bank": []})
+        context = self._run(client, transcript_path=transcript)
+        self.assertIsNone(context)
+        e = self._read_log()[0]
+        self.assertFalse(e["transcript_fallback"])
+        self.assertEqual(e["transcript_fallback_turns"], 0)
+
+
+class DoesNotFireWhenFactLayerNotEmpty(_Harness):
+    def test_bank_returned_memories_suppresses_fallback(self):
+        transcript = self._write_transcript([
+            _nested_line("user", "we should redo the auth flow with PKCE"),
+        ])
+        client = _Client(bank_results={"own-bank": [_memory("auth uses PKCE", "m1")]})
+        context = self._run(client, transcript_path=transcript)
+        self.assertIsNotNone(context)
+        self.assertIn("<hindsight_memories>", context)
+        self.assertNotIn("<hindsight_transcript_fallback>", context)
+        e = self._read_log()[0]
+        self.assertFalse(e["transcript_fallback"])
+        self.assertEqual(e["result_count"], 1)
+
+
+class DoesNotFireWhenDeadlineHit(_Harness):
+    def test_timed_out_bank_suppresses_fallback(self):
+        transcript = self._write_transcript([
+            _nested_line("user", "we should redo the auth flow with PKCE"),
+        ])
+        # Own bank returns zero fast; an extra bank sleeps past the 0.5s
+        # deadline → abandoned → deadline_hit True even though results are empty.
+        client = _Client(
+            bank_sleep={"own-bank": 0.0, "slow-bank": 3.0},
+            bank_results={"own-bank": [], "slow-bank": []},
+        )
+        context = self._run(
+            client,
+            transcript_path=transcript,
+            config_extra={
+                "recallAdditionalBanks": ["slow-bank"],
+                "recallParallelDeadlineSeconds": 0.5,
+            },
+        )
+        self.assertIsNone(context, "fallback must not fire when a bank timed out")
+        e = self._read_log()[0]
+        self.assertTrue(e["deadline_hit"])
+        self.assertFalse(e["transcript_fallback"])
+
+
+class DoesNotFireWhenBankErrored(_Harness):
+    """PR8 gating-hole fix — a HARD (non-timeout) bank error contributes zero
+    results with deadline_hit False. The fallback must be suppressed: an
+    unreachable fact layer is NOT a genuinely empty one, and firing every turn
+    during an outage would flood telemetry and mislabel the cause."""
+
+    def test_errored_bank_suppresses_fallback_parallel(self):
+        transcript = self._write_transcript([
+            _nested_line("user", "we should redo the auth flow with PKCE"),
+        ])
+        # Own bank raises a hard, non-timeout error (connection refused).
+        client = _Client(
+            bank_errors={"own-bank": ConnectionRefusedError("connection refused")},
+        )
+        context = self._run(client, transcript_path=transcript)
+        self.assertIsNone(context, "fallback must not fire when a bank hard-errored")
+        e = self._read_log()[0]
+        self.assertTrue(e["bank_errored"])
+        self.assertFalse(e["deadline_hit"])
+        self.assertFalse(e["transcript_fallback"])
+        self.assertEqual(e["result_count"], 0)
+
+    def test_errored_bank_suppresses_fallback_serial(self):
+        transcript = self._write_transcript([
+            _nested_line("user", "we should redo the auth flow with PKCE"),
+        ])
+        client = _Client(
+            bank_errors={"own-bank": RuntimeError("upstream 503 service unavailable")},
+        )
+        context = self._run(
+            client,
+            transcript_path=transcript,
+            config_extra={"recallParallel": False},
+        )
+        self.assertIsNone(context, "fallback must not fire when a bank hard-errored")
+        e = self._read_log()[0]
+        self.assertEqual(e["recall_mode"], "serial")
+        self.assertTrue(e["bank_errored"])
+        self.assertFalse(e["deadline_hit"])
+        self.assertFalse(e["transcript_fallback"])
+
+
+class FiresInSerialMode(_Harness):
+    """Rollback (serial) mode gates the fallback identically to parallel mode:
+    on an all-zero, no-timeout, no-error turn it fires; the mode is only a
+    latency lever, not a behavioural one."""
+
+    def test_fires_when_all_banks_zero_serial(self):
+        transcript = self._write_transcript([
+            _nested_line("user", "we should redo the auth flow with PKCE"),
+            _nested_line("assistant", "agreed, the auth flow now uses PKCE"),
+        ])
+        client = _Client(bank_results={"own-bank": []})
+        context = self._run(
+            client,
+            transcript_path=transcript,
+            config_extra={"recallParallel": False},
+        )
+        self.assertIsNotNone(context, "fallback should fire in serial mode too")
+        self.assertIn("<hindsight_transcript_fallback>", context)
+        self.assertIn("PKCE", context)
+        e = self._read_log()[0]
+        self.assertEqual(e["recall_mode"], "serial")
+        self.assertTrue(e["transcript_fallback"])
+        self.assertFalse(e["deadline_hit"])
+        self.assertFalse(e["bank_errored"])
+
+
+class BoundsHold(_Harness):
+    def test_byte_bound_only_reads_tail(self):
+        # A query-matching line in the HEAD, padded past the byte window, must
+        # not be surfaced; a recent matching line must be.
+        pad = _nested_line("assistant", "filler noise " * 40)
+        head = _nested_line("user", "the OLD auth flow decision was OAuth1")
+        lines = [head] + [pad] * 60 + [
+            _nested_line("user", "the NEW auth flow uses PKCE tokens"),
+        ]
+        transcript = self._write_transcript(lines)
+        client = _Client(bank_results={"own-bank": []})
+        # 4 KiB tail — comfortably smaller than the head+padding above it.
+        context = self._run(
+            client,
+            transcript_path=transcript,
+            config_extra={"recallTranscriptFallbackMaxBytes": 4096},
+        )
+        self.assertIsNotNone(context)
+        self.assertIn("PKCE tokens", context)
+        self.assertNotIn("OAuth1", context)
+        e = self._read_log()[0]
+        self.assertTrue(e["transcript_fallback"])
+        self.assertLessEqual(e["transcript_fallback_bytes_read"], 4096)
+
+    def test_turn_bound_caps_matched_turns(self):
+        # Ten matching turns, but MaxTurns=3 → at most 3 injected.
+        lines = [
+            _nested_line("user", f"auth flow revision number {i}")
+            for i in range(10)
+        ]
+        transcript = self._write_transcript(lines)
+        client = _Client(bank_results={"own-bank": []})
+        context = self._run(
+            client,
+            transcript_path=transcript,
+            config_extra={"recallTranscriptFallbackMaxTurns": 3},
+        )
+        self.assertIsNotNone(context)
+        e = self._read_log()[0]
+        self.assertEqual(e["transcript_fallback_turns"], 3)
+
+    def test_char_bound_truncates(self):
+        big = "auth flow " + ("detail " * 400)  # ~2800 chars, one turn
+        transcript = self._write_transcript([_nested_line("user", big)])
+        client = _Client(bank_results={"own-bank": []})
+        context = self._run(
+            client,
+            transcript_path=transcript,
+            config_extra={"recallTranscriptFallbackMaxChars": 300},
+        )
+        self.assertIsNotNone(context)
+        e = self._read_log()[0]
+        self.assertTrue(e["transcript_fallback"])
+        self.assertTrue(e["transcript_fallback_truncated"])
+        # The injected excerpt characters are bounded by the cap. The emitted
+        # block is: the fixed wrapper tags + preamble, plus the excerpt whose
+        # length is capped at MaxChars (300). We compute the EXACT wrapper
+        # overhead so a cap breach (e.g. the off-by-one that made a truncated
+        # entry cap+1 chars) would actually fail this assertion — the previous
+        # `+ 200` slack was loose enough to swallow such a breach.
+        wrapper = len(
+            "<hindsight_transcript_fallback>\n"
+            + recall._FALLBACK_BLOCK_PREAMBLE
+            + "\n\n"
+            + "\n</hindsight_transcript_fallback>"
+        )
+        self.assertLessEqual(e["transcript_fallback_chars"], 300 + wrapper)
+
+
+class ConfigGate(_Harness):
+    def test_disabled_by_config(self):
+        transcript = self._write_transcript([
+            _nested_line("user", "we should redo the auth flow with PKCE"),
+        ])
+        client = _Client(bank_results={"own-bank": []})
+        context = self._run(
+            client,
+            transcript_path=transcript,
+            config_extra={"recallTranscriptFallback": False},
+        )
+        self.assertIsNone(context)
+        e = self._read_log()[0]
+        self.assertFalse(e["transcript_fallback"])
+
+    def test_no_transcript_path_is_safe(self):
+        client = _Client(bank_results={"own-bank": []})
+        context = self._run(client, transcript_path="")
+        self.assertIsNone(context)
+        e = self._read_log()[0]
+        self.assertFalse(e["transcript_fallback"])
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -341,6 +341,55 @@ class TestWatermark(DurabilityTestBase):
         self.assertIsNone(watermark.load("wm2"))
 
 
+class TestSidechainSkip(DurabilityTestBase):
+    """PR5 review finding 1: reconcile must NOT treat a sub-agent sidechain
+    transcript as a pseudo-session. The recursive glob matches
+    <session>/subagents/agent-<id>.jsonl; without the guard reconcile would
+    retain it at boot with an untagged, disjoint-namespace document (permanent
+    duplicate of subagent_retain.py's tagged retain, at full recall weight,
+    bypassing the volume gate)."""
+
+    def _write_sidechain(self, path, n_turns):
+        lines = []
+        for i in range(n_turns):
+            lines.append(json.dumps({
+                "type": "user", "isSidechain": True, "agentId": "af5",
+                "uuid": f"su{i}", "message": {"role": "user", "content": f"sc turn {i}"},
+            }))
+            lines.append(json.dumps({
+                "type": "assistant", "isSidechain": True, "agentId": "af5",
+                "uuid": f"sa{i}", "message": {"role": "assistant", "content": f"sc did {i}"},
+            }))
+        with open(path, "w", encoding="utf-8") as f:
+            f.write("\n".join(lines))
+
+    def test_reconcile_skips_sidechain_transcript(self):
+        session = "sessX"
+        # A real parent session with un-committed turns (must still reconcile).
+        parent = os.path.join(self.transcripts, f"{session}.jsonl")
+        _write_transcript(parent, 4, session_prefix=session)
+        # A sidechain under <session>/subagents/ that the recursive glob matches.
+        sub_dir = os.path.join(self.transcripts, session, "subagents")
+        os.makedirs(sub_dir)
+        sc = os.path.join(sub_dir, "agent-af5.jsonl")
+        self._write_sidechain(sc, 5)
+
+        hook = {"session_id": session, "transcript_path": parent, "cwd": "/x"}
+        summary = reconcile_tail.reconcile(self._config(), hook_input=hook)
+
+        # The sidechain was recognised and skipped ...
+        self.assertGreaterEqual(summary["skipped_sidechain"], 1)
+        blob = self.daemon.content_blob()
+        # ... none of its content was retained ...
+        self.assertNotIn("sc turn", blob)
+        self.assertNotIn("sc did", blob)
+        # ... and no document carries the untagged agent-<id> namespace.
+        self.assertFalse(any(did.startswith("agent-af5") for did in self.daemon.docs))
+        # ... while the genuine parent session WAS reconciled.
+        for i in range(4):
+            self.assertIn(f"user turn {i}", blob)
+
+
 def _stdin(obj):
     import io
     return io.StringIO(json.dumps(obj))