switchroom 0.21.16 → 0.21.18

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

@@ -0,0 +1,176 @@
+"""Memory v2 M5 — Surface B: orientation-at-boot (pure logic).
+
+Unit tests for lib/orientation.py — the network-free half of the orientation
+SessionStart hook. These pin the DETERMINISTIC mechanism (carve-M5 §0c/§5/§8):
+every branch that decides inject / prefix-as-stale / degrade-to-cold / truncate
+is asserted by OUTCOME, so reverting the corresponding rule turns a test RED.
+
+Coverage:
+  T1  render stays within the 2048-token TOTAL cap, even with a stale prefix,
+      and emits a VISIBLE truncation marker when content is dropped.
+  T3  staleness is PER-TIER (1.5×/3× of the resolved cadence), not a fixed 36h —
+      parametrized over cadence 24 AND 48 so a hardcoded threshold fails.
+  Truncation is rule-aware (whole markdown sections; hard-cut only when the
+      first section alone overflows) and never exceeds the budget.
+  Cold notice + stale prefix are visible one-liners (never stale-as-fresh).
+
+Stdlib-only.
+"""
+
+import os
+import sys
+import unittest
+from datetime import datetime, timedelta, timezone
+
+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 lib import orientation as orient  # noqa: E402
+
+
+class TestEstimateTokens(unittest.TestCase):
+    def test_empty_is_zero(self):
+        self.assertEqual(orient.estimate_tokens(""), 0)
+
+    def test_ceils_chars_over_four(self):
+        # 7 chars / 4 = 1.75 -> ceil 2. A floor would under-count and let the
+        # budget math overflow the cap.
+        self.assertEqual(orient.estimate_tokens("abcdefg"), 2)
+
+
+class TestClassifyStalenessPerTier(unittest.TestCase):
+    """T3 — thresholds must scale with the agent's cadence tier, not a fixed 36h."""
+
+    NOW = datetime(2026, 8, 17, 12, 0, 0, tzinfo=timezone.utc)
+
+    def _at(self, hours_ago):
+        return (self.NOW - timedelta(hours=hours_ago)).isoformat()
+
+    def test_fresh_stale_degraded_boundaries_cadence_24(self):
+        # cadence 24: stale at 36h (1.5x), degrade at 72h (3x).
+        for hours, expected in [(0, "fresh"), (35, "fresh"), (36, "stale"),
+                                (71, "stale"), (72, "degraded"), (999, "degraded")]:
+            state, _ = orient.classify_staleness(self._at(hours), 24, now=self.NOW)
+            self.assertEqual(state, expected, f"cadence24 @ {hours}h")
+
+    def test_fresh_stale_degraded_boundaries_cadence_48(self):
+        # cadence 48: stale at 72h (1.5x), degrade at 144h (3x). A FIXED 36h
+        # threshold would wrongly call 40h "stale" here — this is the R4 guard.
+        for hours, expected in [(0, "fresh"), (40, "fresh"), (71, "fresh"),
+                                (72, "stale"), (143, "stale"), (144, "degraded")]:
+            state, _ = orient.classify_staleness(self._at(hours), 48, now=self.NOW)
+            self.assertEqual(state, expected, f"cadence48 @ {hours}h")
+
+    def test_a_48h_tier_model_at_40h_is_NOT_stale(self):
+        # Direct restatement of red-team R4: the staleness guard biting a day
+        # early. 40h < 1.5*48 = 72h, so it is fresh.
+        state, hours_ago = orient.classify_staleness(self._at(40), 48, now=self.NOW)
+        self.assertEqual(state, "fresh")
+        self.assertAlmostEqual(hours_ago, 40.0, places=1)
+
+    def test_missing_timestamp_is_unknown(self):
+        state, hours_ago = orient.classify_staleness(None, 48, now=self.NOW)
+        self.assertEqual(state, "unknown")
+        self.assertIsNone(hours_ago)
+
+    def test_unparseable_timestamp_is_unknown(self):
+        state, hours_ago = orient.classify_staleness("not-a-date", 48, now=self.NOW)
+        self.assertEqual(state, "unknown")
+        self.assertIsNone(hours_ago)
+
+    def test_trailing_Z_is_parsed(self):
+        state, _ = orient.classify_staleness(
+            self._at(1).replace("+00:00", "Z"), 48, now=self.NOW
+        )
+        self.assertEqual(state, "fresh")
+
+    def test_future_timestamp_clock_skew_is_fresh_not_negative(self):
+        future = (self.NOW + timedelta(hours=5)).isoformat()
+        state, hours_ago = orient.classify_staleness(future, 48, now=self.NOW)
+        self.assertEqual(state, "fresh")
+        self.assertEqual(hours_ago, 0.0)
+
+
+class TestTruncateToBudget(unittest.TestCase):
+    def test_under_budget_is_untouched(self):
+        content = "# A\nshort body"
+        body, truncated = orient.truncate_to_budget(content, 1000)
+        self.assertEqual(body, content)
+        self.assertFalse(truncated)
+
+    def test_empty_returns_empty_not_truncated(self):
+        self.assertEqual(orient.truncate_to_budget("   ", 1000), ("", False))
+
+    def test_drops_whole_trailing_sections(self):
+        # Two ~120-token sections, budget only fits one. The kept text must be a
+        # WHOLE section (starts with its header), and truncated=True.
+        sec_a = "# Keep\n" + ("alpha " * 120)
+        sec_b = "# Drop\n" + ("bravo " * 120)
+        body, truncated = orient.truncate_to_budget(sec_a + "\n" + sec_b, 150)
+        self.assertTrue(truncated)
+        self.assertIn("# Keep", body)
+        self.assertNotIn("# Drop", body)
+        self.assertLessEqual(orient.estimate_tokens(body), 150)
+
+    def test_first_section_overflow_hard_cuts_on_word_boundary(self):
+        # A single header-less blob bigger than budget must still yield content
+        # (never empty), cut at whitespace (no mid-word slice), within budget.
+        blob = "wordword " * 400
+        body, truncated = orient.truncate_to_budget(blob, 50)
+        self.assertTrue(truncated)
+        self.assertTrue(body)
+        self.assertLessEqual(orient.estimate_tokens(body), 50)
+        self.assertFalse(body.endswith("wordwor"))  # not sliced mid-word
+
+
+class TestRenderOrientation(unittest.TestCase):
+    """T1 — rendered additionalContext obeys the 2048 TOTAL cap and is visible."""
+
+    def _big_content(self):
+        # ~2,400 tokens of content — larger than the 1800 content budget AND the
+        # 2048 total cap, forcing truncation.
+        return "# Section\n" + ("token " * 2400)
+
+    def test_fresh_render_within_total_cap(self):
+        rendered = orient.render_orientation(self._big_content(), "fresh", 3.0)
+        self.assertLessEqual(
+            orient.estimate_tokens(rendered), orient.ORIENTATION_TOTAL_TOKEN_CAP
+        )
+        self.assertIn(orient.TRUNCATION_MARKER, rendered)
+        self.assertIn('<orientation source="memory">', rendered)
+        self.assertIn("</orientation>", rendered)
+
+    def test_stale_render_includes_prefix_and_still_within_cap(self):
+        rendered = orient.render_orientation(self._big_content(), "stale", 90.0)
+        self.assertLessEqual(
+            orient.estimate_tokens(rendered), orient.ORIENTATION_TOTAL_TOKEN_CAP
+        )
+        # The stale prefix must be present AND the cap still held — the prefix
+        # eats into the content budget, it does not blow the ceiling.
+        self.assertIn("may be stale", rendered)
+        self.assertIn("90h ago", rendered)
+
+    def test_fresh_render_has_no_stale_prefix(self):
+        rendered = orient.render_orientation("# S\nsmall body", "fresh", 1.0)
+        self.assertNotIn("may be stale", rendered)
+
+    def test_small_fresh_content_not_marked_truncated(self):
+        rendered = orient.render_orientation("# S\nsmall body", "fresh", 1.0)
+        self.assertNotIn(orient.TRUNCATION_MARKER, rendered)
+        self.assertIn("small body", rendered)
+
+
+class TestNotices(unittest.TestCase):
+    def test_cold_notice_is_framed_and_mentions_refresh(self):
+        notice = orient.cold_notice()
+        self.assertIn('<orientation source="memory">', notice)
+        self.assertIn("</orientation>", notice)
+        self.assertIn("refresh", notice.lower())
+
+    def test_stale_prefix_unknown_hours(self):
+        self.assertIn("unknown", orient.stale_prefix(None))
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,329 @@
+"""M4 prefetch-buffer MUTATION INVALIDATION — red-team-M3 R2 (BLOCKER).
+
+The M4 prefetch buffer holds a RECALLED memories block captured at a prior
+turn's Stop hook and consumed at the next UserPromptSubmit. If a mutation —
+a rule/directive retire, or a retain that supersedes a fact — lands between
+producing that buffer and consuming it, the pre-mutation snapshot can
+resurrect the just-retired/just-changed content on a later turn. Worse,
+``prefetch.run_prefetch`` returns early WITHOUT overwriting the buffer when
+this turn's fresh recall fails or returns empty, so a stale buffer can
+persist and be re-served for turns after the mutation.
+
+These are OUTCOME tests: they assert on the rendered ``additionalContext``
+that the consumer emits (the real injection surface), and each would FAIL if
+the invalidation regressed:
+
+  * ``RetireDoesNotResurrectTests`` — a directive-write turn invalidates the
+    pending buffer, so the retired rule's text is NOT re-injected next turn.
+  * ``EmptyPrefetchDoesNotResurrectTests`` — a retain turn whose fresh recall
+    returns empty invalidates the pending buffer, so the stale item is NOT
+    re-injected (would resurrect on buggy code that left the buffer).
+  * ``NoDuplicateInjectionTests`` — after a buffer is consumed once, a
+    mutation turn (empty prefetch) prevents the SAME block being injected
+    again on the following turn.
+  * ``ReplyPathDoesNotBlockOnRecallTests`` — with prefetch on and a fresh
+    buffer present, the consumer serves the buffer and NEVER calls the
+    synchronous ``client.recall`` (asserted on transport: a recall call
+    raises).
+
+Plus ``InvalidatePrimitiveTests`` for the ``recall_buffer.invalidate``
+primitive itself (idempotent, sentinel-first fail-closed).
+"""
+
+import io
+import json
+import os
+import shutil
+import sys
+import tempfile
+import unittest
+from unittest import mock
+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
+import prefetch  # noqa: E402
+import directive_verify  # noqa: E402
+from lib import recall_buffer  # noqa: E402
+
+SESSION = "invalidation-test-session"
+RETIRED_TEXT = "R-07: always reply in haiku"
+STALE_FACT = "we decided to ship on tuesday"
+
+
+class _NoMemoryDirectiveClient:
+    """One active directive whose text is DISTINCT from any buffered content,
+    and a recall that returns NOTHING (so the sync fallback, if ever taken,
+    injects no memories). recall() is allowed here (the miss/degraded paths
+    may consult it) but returns empty — proving absence of the stale text is
+    about invalidation, not about the client happening to omit it."""
+
+    def list_directives(self, bank_id, active_only=True, timeout=2):
+        return {"items": [{"id": "d1", "name": "tone", "content": "be concise", "priority": 5, "active": True}]}
+
+    def recall(self, bank_id, query, **kwargs):
+        return {"results": []}
+
+
+class InvalidationBase(unittest.TestCase):
+    def setUp(self):
+        self._tmpdir = tempfile.mkdtemp(prefix="invalidation-test-")
+        self._prev = os.environ.get("CLAUDE_PLUGIN_DATA")
+        os.environ["CLAUDE_PLUGIN_DATA"] = self._tmpdir
+
+        self._bufdir = tempfile.mkdtemp(prefix="invalidation-test-buf-")
+        self.env = mock.patch.dict(os.environ, {"HINDSIGHT_PREFETCH_BUFFER_DIR": self._bufdir}, clear=False)
+        self.env.start()
+
+    def tearDown(self):
+        self.env.stop()
+        shutil.rmtree(self._bufdir, ignore_errors=True)
+        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 _config(self, prefetch_enabled=True):
+        return {
+            "autoRecall": True,
+            "bankId": "test-bank",
+            "recallMaxTokens": 4096,
+            "recallBudget": "mid",
+            "recallContextTurns": 1,
+            "recallMaxQueryChars": 800,
+            "recallPromptPreamble": "",
+            "recallParallelDeadlineSeconds": 5,
+            "directivesCacheTtlSeconds": 0,
+            "memoryPrefetchEnabled": prefetch_enabled,
+            "memoryPrefetchPollCapMs": 100,
+        }
+
+    def _consume(self, config, client, prompt="what did we decide"):
+        """Drive the recall.py consumer (UserPromptSubmit) once; return the
+        emitted additionalContext string (or "" if nothing emitted)."""
+        hook_input = {"prompt": prompt, "session_id": SESSION, "transcript_path": "", "cwd": "/tmp"}
+        stdout = io.StringIO()
+        with patch("recall.load_config", return_value=config), \
+                patch("recall.get_api_url", return_value="http://fake"), \
+                patch("recall.HindsightClient", return_value=client), \
+                patch("recall.ensure_bank_mission"), \
+                patch("sys.stdin", io.StringIO(json.dumps(hook_input))), \
+                patch("sys.stdout", stdout):
+            recall.main()
+        out = stdout.getvalue()
+        if not out:
+            return ""
+        return json.loads(out)["hookSpecificOutput"]["additionalContext"]
+
+
+class InvalidatePrimitiveTests(InvalidationBase):
+    def test_invalidate_removes_buffer_and_sentinel(self):
+        recall_buffer.write_buffer(SESSION, RETIRED_TEXT, {})
+        recall_buffer.write_sentinel(SESSION)
+        self.assertTrue(os.path.isfile(recall_buffer._buffer_path(SESSION)))
+        self.assertTrue(os.path.isfile(recall_buffer._sentinel_path(SESSION)))
+
+        recall_buffer.invalidate(SESSION)
+
+        self.assertFalse(os.path.isfile(recall_buffer._buffer_path(SESSION)))
+        self.assertFalse(os.path.isfile(recall_buffer._sentinel_path(SESSION)))
+        # read_if_fresh must now report nothing fresh (fail-closed).
+        payload, _ = recall_buffer.read_if_fresh(SESSION, last_consumed_token=None)
+        self.assertIsNone(payload)
+
+    def test_invalidate_is_idempotent_on_absent_files(self):
+        # No buffer written — must not raise.
+        recall_buffer.invalidate(SESSION)
+        recall_buffer.invalidate(SESSION)
+
+    def test_orphaned_payload_after_sentinel_first_delete_fails_closed(self):
+        # Simulate a partial invalidation where only the sentinel unlink
+        # landed (sentinel is deleted FIRST by design): an orphaned payload
+        # must never read as fresh.
+        recall_buffer.write_buffer(SESSION, RETIRED_TEXT, {})
+        recall_buffer.write_sentinel(SESSION)
+        os.remove(recall_buffer._sentinel_path(SESSION))
+        payload, _ = recall_buffer.read_if_fresh(SESSION, last_consumed_token=None)
+        self.assertIsNone(payload)
+
+
+class RetireDoesNotResurrectTests(InvalidationBase):
+    """Assertion (1): a directive retire invalidates the pending buffer so the
+    retired item is NOT re-injected on the next turn."""
+
+    def _retire_turn_messages(self):
+        # A real turn transcript: the user retires a rule, the assistant issues
+        # a delete_directive tool_use. This is what directive_verify inspects.
+        return [
+            {"role": "user", "content": "Retire the haiku rule R-07, it no longer applies."},
+            {
+                "role": "assistant",
+                "content": [
+                    {"type": "tool_use", "id": "t1", "name": "delete_directive", "input": {"id": "d-r07"}}
+                ],
+            },
+        ]
+
+    def test_directive_write_turn_invalidates_buffer_and_blocks_resurrection(self):
+        config = self._config(prefetch_enabled=True)
+
+        # Turn N Stop: prefetch buffered the rule text while it was still active.
+        recall_buffer.write_buffer(SESSION, RETIRED_TEXT, {})
+        recall_buffer.write_sentinel(SESSION)
+
+        # Turn N+1: the retire lands. directive_verify's Stop-hook invalidation
+        # detects the delete_directive write and drops the pending buffer.
+        directive_verify.invalidate_prefetch_buffer_on_directive_write(
+            self._retire_turn_messages(), config, SESSION
+        )
+        self.assertFalse(
+            os.path.isfile(recall_buffer._sentinel_path(SESSION)),
+            "directive-write turn must invalidate the pending prefetch buffer",
+        )
+
+        # Turn N+2 UserPromptSubmit: the consumer must NOT re-inject the retired
+        # rule text. (With no fresh buffer it takes the sync/degraded path, which
+        # here surfaces only the fresh directive block, not the retired text.)
+        ctx = self._consume(config, _NoMemoryDirectiveClient())
+        self.assertNotIn(
+            "R-07", ctx,
+            "retired rule text must not resurrect from a pre-retire prefetch buffer",
+        )
+        self.assertNotIn("haiku", ctx)
+
+    def test_non_directive_turn_leaves_buffer_intact(self):
+        # Guard against over-invalidation: an ordinary turn (no directive write)
+        # must NOT drop the buffer, or every turn would lose the prefetch.
+        config = self._config(prefetch_enabled=True)
+        recall_buffer.write_buffer(SESSION, "- a normal prefetched memory", {})
+        recall_buffer.write_sentinel(SESSION)
+        directive_verify.invalidate_prefetch_buffer_on_directive_write(
+            [
+                {"role": "user", "content": "what's the weather"},
+                {"role": "assistant", "content": "Sunny."},
+            ],
+            config,
+            SESSION,
+        )
+        self.assertTrue(os.path.isfile(recall_buffer._sentinel_path(SESSION)))
+
+    def test_flag_off_is_a_noop(self):
+        # Kill switch: with prefetch off, the directive-write invalidation must
+        # not touch the buffer module at all.
+        config = self._config(prefetch_enabled=False)
+        recall_buffer.write_buffer(SESSION, RETIRED_TEXT, {})
+        recall_buffer.write_sentinel(SESSION)
+        with patch("directive_verify.recall_buffer.invalidate",
+                   side_effect=AssertionError("must not invalidate when prefetch is off")):
+            directive_verify.invalidate_prefetch_buffer_on_directive_write(
+                self._retire_turn_messages(), config, SESSION
+            )
+        self.assertTrue(os.path.isfile(recall_buffer._sentinel_path(SESSION)))
+
+
+class EmptyPrefetchDoesNotResurrectTests(InvalidationBase):
+    """Assertion (1) via the RETAIN mutation path: a retain turn whose fresh
+    recall returns empty must invalidate the pending buffer so the stale item
+    is NOT re-served. This FAILS on buggy code that returns early leaving the
+    old buffer in place."""
+
+    def test_retain_turn_with_empty_recall_invalidates_stale_buffer(self):
+        config = self._config(prefetch_enabled=True)
+
+        # Turn N Stop: a stale fact was buffered.
+        recall_buffer.write_buffer(SESSION, STALE_FACT, {})
+        recall_buffer.write_sentinel(SESSION)
+
+        # Turn N+1 Stop: prefetch runs (a retain mutation), but this turn's
+        # fresh recall returns NOTHING. run_prefetch must have already
+        # invalidated the old buffer up front — so no stale buffer survives.
+        empty_client = mock.Mock()
+        empty_client.recall.return_value = {"results": []}
+        hook_input = {
+            "prompt": "and another thing",
+            "session_id": SESSION,
+            "transcript_path": "",  # _last_human_prompt degrades to "" -> we inject a query below
+            "cwd": "/tmp",
+        }
+        with patch("prefetch.retain_module.run_retain", return_value={"status": "ok"}), \
+                patch("prefetch.HindsightClient", return_value=empty_client), \
+                patch("prefetch.get_api_url", return_value="http://fake"), \
+                patch("prefetch._last_human_prompt", return_value="and another thing"):
+            wrote = prefetch.run_prefetch(hook_input, config)
+
+        self.assertFalse(wrote, "empty recall must not write a fresh buffer")
+        self.assertFalse(
+            os.path.isfile(recall_buffer._sentinel_path(SESSION)),
+            "a mutation (retain) turn must invalidate the stale buffer even when the fresh recall is empty",
+        )
+
+        # Turn N+2 UserPromptSubmit: the stale fact must NOT re-inject.
+        ctx = self._consume(config, _NoMemoryDirectiveClient())
+        self.assertNotIn(
+            STALE_FACT, ctx,
+            "stale buffered fact must not resurrect after a mutation turn with an empty recall",
+        )
+
+
+class NoDuplicateInjectionTests(InvalidationBase):
+    """Assertion (2): the same buffered block is not injected twice. After a
+    turn consumes a buffer, a mutation turn (empty prefetch) prevents the SAME
+    block from being re-served on the following turn."""
+
+    def test_consumed_buffer_not_reinjected_after_mutation_turn(self):
+        config = self._config(prefetch_enabled=True)
+        marker = "- unique-fact-abc123 decided at standup"
+
+        recall_buffer.write_buffer(SESSION, marker, {})
+        recall_buffer.write_sentinel(SESSION)
+
+        # Turn N+1: consumer injects the buffered block once.
+        first = self._consume(config, _NoMemoryDirectiveClient())
+        self.assertIn("unique-fact-abc123", first)
+
+        # Turn N+1 Stop: a mutation turn whose recall returns empty -> the old
+        # buffer is invalidated, nothing fresh written.
+        empty_client = mock.Mock()
+        empty_client.recall.return_value = {"results": []}
+        hook_input = {"prompt": "next", "session_id": SESSION, "transcript_path": "", "cwd": "/tmp"}
+        with patch("prefetch.retain_module.run_retain", return_value={"status": "ok"}), \
+                patch("prefetch.HindsightClient", return_value=empty_client), \
+                patch("prefetch.get_api_url", return_value="http://fake"), \
+                patch("prefetch._last_human_prompt", return_value="next"):
+            prefetch.run_prefetch(hook_input, config)
+
+        # Turn N+2: the same block must NOT be injected a second time.
+        second = self._consume(config, _NoMemoryDirectiveClient())
+        self.assertNotIn(
+            "unique-fact-abc123", second,
+            "a consumed buffer must not be re-injected after a mutation invalidated it",
+        )
+
+
+class ReplyPathDoesNotBlockOnRecallTests(InvalidationBase):
+    """Assertion (3): with prefetch on and a fresh buffer present, the reply
+    path (UserPromptSubmit consumer) joins the buffer and NEVER blocks on a
+    synchronous recall. Asserted on transport: client.recall raises if called."""
+
+    def test_fresh_buffer_served_without_calling_recall(self):
+        config = self._config(prefetch_enabled=True)
+        recall_buffer.write_buffer(SESSION, "- a prefetched memory xyz", {})
+        recall_buffer.write_sentinel(SESSION)
+
+        class _ExplodingRecallClient:
+            def list_directives(self, bank_id, active_only=True, timeout=2):
+                return {"items": []}
+
+            def recall(self, bank_id, query, **kwargs):
+                raise AssertionError("reply path must not block on synchronous recall when a fresh buffer exists")
+
+        ctx = self._consume(config, _ExplodingRecallClient())
+        self.assertIn("a prefetched memory xyz", ctx)
+
+
+if __name__ == "__main__":
+    unittest.main()