switchroom 0.20.11 → 0.20.13

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

@@ -1037,6 +1037,116 @@ def _write_recall_log(entry: dict) -> None:
         pass
 
 
+# Switchroom recall-latency instrumentation — full-hook wall-time.
+#
+# recall.py is the UserPromptSubmit hook that sits in front of EVERY reply
+# (pre-first-token), yet it was the one hook with no wall-time record: it is a
+# DIRECT Claude Code plugin hook (hooks/hooks.json), NOT wrapped by
+# bin/run-hook.sh, so it never emitted a `hook-timings-<Ddd>.log` row the way
+# every wrapped hook does, and `recall_log.jsonl` measured only the recall
+# critical path (`total_elapsed_ms`, from `recall_start_monotonic`) — never the
+# hook's own import + stdin + cache-check + gate overhead.
+#
+# Routing it through run-hook.sh was rejected as the mechanism: the vendored
+# hooks.json is re-copied verbatim into every agent's plugin dir on `switchroom
+# apply`, and run-hook.sh lives in the switchroom repo's bin/, not under
+# CLAUDE_PLUGIN_ROOT — coupling the vendor snapshot to switchroom's bin layout is
+# fragile, and the os._exit(0) fast-path (which skips atexit / thread-join to
+# return control the instant stdout is flushed) would have to be reconciled with
+# the wrapper. Instead the hook emits the SAME JSON line, into the SAME weekday-
+# ring file, honouring the SAME env knobs, from inside the process at exit — so
+# `grep duration_ms hook-timings-*.log` sees this hook next to every other one.
+HOOK_TIMING_SOURCE = "hook:hindsight-recall"
+HOOK_TIMING_CODE = "recall.py"
+
+
+def _hook_duration_ms() -> int:
+    """Milliseconds since this hook process began doing work.
+
+    Anchored at import start (`_IMPORT_START_MONOTONIC`, taken before any of this
+    hook's own imports ran — recall.py line ~48), so the number spans the WHOLE
+    hook: dependency import, the stdin read, the cache check, the gate
+    short-circuits, and — when it got that far — the recall round-trips. That is
+    deliberately WIDER than `total_elapsed_ms` (the recall critical path only,
+    measured from `recall_start_monotonic`): `duration_ms - total_elapsed_ms` is
+    therefore the pre-recall LOCAL overhead, and the per-bank
+    `bank_timings[].elapsed_ms` remain the Hindsight server round-trips — so the
+    log already separates server time from local overhead without a new field.
+    """
+    return int((time.monotonic() - _IMPORT_START_MONOTONIC) * 1000)
+
+
+def _emit_hook_timing_log(duration_ms: int, status: int) -> None:
+    """Append one timing line to `hook-timings-<Ddd>.log`, matching run-hook.sh.
+
+    STDOUT-SAFE by construction: writes only to a log file, NEVER to the hook's
+    stdout contract that Claude Code consumes. Failure-tolerant — any error is
+    swallowed so instrumentation can never take the hook down. Honours the same
+    env knobs as bin/run-hook.sh (`SWITCHROOM_HOOK_TIMING`,
+    `SWITCHROOM_HOOK_TIMING_DIR`, `SWITCHROOM_HOOK_TIMING_MIN_MS`) and reproduces
+    its 7-day self-truncating weekday ring and JSON line shape exactly, so a
+    consumer cannot tell this row apart from a wrapped hook's.
+
+    NOTE on the 12s ceiling: if Claude Code kills this hook at the
+    UserPromptSubmit timeout, the process is terminated before any exit path runs
+    and NO timing line (nor recall_log row) is written — the MISSING line is the
+    breach signal, consistent with the two-signal baseline documented at the
+    recall_log write. This records every invocation that returns under budget,
+    including a fully-degraded/timed-out recall that still exits cleanly.
+    """
+    try:
+        if os.environ.get("SWITCHROOM_HOOK_TIMING", "1") == "0":
+            return
+        timing_dir = os.environ.get("SWITCHROOM_HOOK_TIMING_DIR") or os.environ.get(
+            "TELEGRAM_STATE_DIR", ""
+        )
+        if not timing_dir or not os.path.isdir(timing_dir):
+            return
+        try:
+            duration_ms = int(duration_ms)
+        except (TypeError, ValueError):
+            return
+        if duration_ms < 0:
+            duration_ms = 0
+        try:
+            min_ms = int(os.environ.get("SWITCHROOM_HOOK_TIMING_MIN_MS", "0"))
+        except (TypeError, ValueError):
+            min_ms = 0
+        if duration_ms < min_ms:
+            return
+        # Local wall clock, matching run-hook.sh's builtin `%(...)T` formatting so
+        # both writers agree on which weekday-ring file today lands in.
+        now = time.localtime()
+        today = time.strftime("%Y-%m-%d", now)
+        dow = time.strftime("%a", now)
+        ts = time.strftime("%Y-%m-%dT%H:%M:%S%z", now)
+        logfile = os.path.join(timing_dir, f"hook-timings-{dow}.log")
+        # 7-day self-truncating ring: the weekday-named file is either today's or
+        # exactly a week stale. If its first line does not carry today's date,
+        # reset it before appending (same rule as run-hook.sh).
+        try:
+            if os.path.getsize(logfile) > 0:
+                with open(logfile, encoding="utf-8") as f:
+                    first = f.readline()
+                if f'"date":"{today}"' not in first:
+                    open(logfile, "w", encoding="utf-8").close()
+        except OSError:
+            pass
+        # HOOK_TIMING_SOURCE / HOOK_TIMING_CODE are fixed constants with no JSON
+        # metacharacters, so no escape pass is needed (unlike run-hook.sh, whose
+        # source/code are caller-supplied).
+        line = (
+            '{"ts":"%s","date":"%s","source":"%s","code":"%s",'
+            '"duration_ms":%d,"status":%d}\n'
+            % (ts, today, HOOK_TIMING_SOURCE, HOOK_TIMING_CODE, duration_ms, status)
+        )
+        with open(logfile, "a", encoding="utf-8") as f:
+            f.write(line)
+    except Exception:
+        # Instrumentation is never load-bearing — swallow everything.
+        pass
+
+
 def _read_transcript_lines(transcript_path: str, tail_bytes: int):
     """Yield the transcript's trailing lines, byte-bounded.
 
@@ -1824,6 +1934,12 @@ def main():
                 # timed out"; `deadline_hit is None` means "no banks ran"
                 # (review finding 3).
                 "total_elapsed_ms": None,
+                # Switchroom recall-latency instrumentation — full-hook wall time
+                # (import + stdin + cache check), measured to this log write. A
+                # cache hit issues no bank HTTP, so `total_elapsed_ms` is None and
+                # this is pure local overhead — the cheap path this cache exists
+                # to create, now visible per-row.
+                "duration_ms": _hook_duration_ms(),
                 "directives_elapsed_ms": None,
                 "bank_timings": [],
                 "deadline_hit": None,
@@ -2542,6 +2658,16 @@ def main():
         # parallelism change measures against; the 17-26% figure it replaces is
         # the stale 2026-05-24 pre-fix audit.
         "total_elapsed_ms": int((time.monotonic() - recall_start_monotonic) * 1000),
+        # Switchroom recall-latency instrumentation — FULL-HOOK wall time to this
+        # log write: dependency import + stdin read + cache check + the gate
+        # short-circuits + the whole recall critical path. `total_elapsed_ms`
+        # above is the recall critical path ONLY, so `duration_ms -
+        # total_elapsed_ms` is the pre-recall LOCAL overhead this row could not
+        # see before, while `bank_timings[].elapsed_ms` stay the server round-
+        # trips — the log now separates server time from local overhead. Written
+        # here (with the rest of the row, before the empty-block return) so even a
+        # fully-timed-out / degraded recall that reaches this line gets a duration.
+        "duration_ms": _hook_duration_ms(),
         "directives_elapsed_ms": directives_elapsed_ms,
         "bank_timings": bank_timings,
         # Switchroom hindsight-leverage A3 — FINALIZED `deadline_hit` semantics
@@ -2795,6 +2921,12 @@ if __name__ == "__main__":
             sys.stdout.flush()
         except Exception:
             pass
+        # Switchroom recall-latency instrumentation — emit the full-hook timing
+        # line AFTER stdout is flushed (Claude Code already has the bytes) and
+        # BEFORE os._exit, which skips atexit and would otherwise drop it. Adds
+        # ~0.5ms (one file append) before the process exits — the same budget
+        # run-hook.sh spends per wrapped hook. Stdout is untouched.
+        _emit_hook_timing_log(_hook_duration_ms(), 0)
         os._exit(0)
     except Exception as e:
         # Switchroom #1070 (redo per #1085 review).
@@ -2844,6 +2976,10 @@ if __name__ == "__main__":
             import traceback
 
             traceback.print_exc(file=sys.stderr)
+            # Instrumentation: record the failed invocation's wall time too
+            # (status 2, the debug-mode block behaviour) so a crash-looping
+            # hook is visible in the timing log, not just a silent gap.
+            _emit_hook_timing_log(_hook_duration_ms(), 2)
             # Debug-mode exit 2 is intentional and unchanged —
             # operators with HINDSIGHT_DEBUG=1 are chasing a broken
             # recall and want the hook to surface its failure.
@@ -2853,4 +2989,8 @@ if __name__ == "__main__":
         # 0 with no stdout (agent's prompt assembly treats absent
         # additionalContext as "no recall this turn").
         _record_issue_safely(_detail, _class)
+        # Instrumentation: the non-debug exit code is 0 (the safe-empty stdout
+        # posture), so log status 0 — the accompanying issue-sink record is where
+        # the failure detail lives; this row just makes the latency observable.
+        _emit_hook_timing_log(_hook_duration_ms(), 0)
         sys.exit(0)

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

@@ -0,0 +1,277 @@
+"""Switchroom recall-latency instrumentation tests.
+
+recall.py is the UserPromptSubmit hook in front of every reply, and until now
+its wall time was UNMEASURED: it is a direct plugin hook (not wrapped by
+bin/run-hook.sh, so no hook-timings row) and recall_log.jsonl carried no
+duration field. These tests lock in the two things this PR added:
+
+  1. Every recall_log row (cache hit AND cache miss) carries a numeric
+     `duration_ms` — including a degraded/failed recall.
+  2. The hook emits a `hook-timings-<Ddd>.log` line matching bin/run-hook.sh's
+     schema, into the same weekday ring, honouring the same env knobs.
+  3. The instrumentation NEVER pollutes the hook's stdout contract (the
+     recall-context JSON Claude Code consumes is byte-identical).
+
+Stdlib-only (unittest + mock). Reuses the integration harness's fakes.
+"""
+
+import io
+import json
+import os
+import sys
+import tempfile
+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)
+TESTS_DIR = os.path.abspath(os.path.dirname(__file__))
+if TESTS_DIR not in sys.path:
+    sys.path.insert(0, TESTS_DIR)
+
+import recall  # noqa: E402
+from test_recall_integration import _FakeClient, _memory, _run_main_with  # noqa: E402
+
+
+class DurationMsInRecallLogTests(unittest.TestCase):
+    """recall_log.jsonl rows must carry a numeric `duration_ms`."""
+
+    def setUp(self):
+        self._tmpdir = tempfile.mkdtemp(prefix="recall-latency-test-")
+        self._prev = os.environ.get("CLAUDE_PLUGIN_DATA")
+        os.environ["CLAUDE_PLUGIN_DATA"] = self._tmpdir
+
+    def tearDown(self):
+        import shutil
+
+        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 _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 test_cache_miss_row_has_numeric_duration_ms(self):
+        client = _FakeClient(directives=[], memories=[_memory("x", mem_id="x1")])
+        _run_main_with(client)
+        e = self._read_log()[0]
+        self.assertFalse(e["cache_hit"])
+        self.assertIn("duration_ms", e)
+        self.assertIsInstance(e["duration_ms"], int)
+        self.assertGreaterEqual(e["duration_ms"], 0)
+        # duration_ms (full hook) must be >= total_elapsed_ms (recall path only):
+        # it strictly contains it, so the derived local overhead is never negative.
+        self.assertGreaterEqual(e["duration_ms"], e["total_elapsed_ms"])
+
+    def test_degraded_recall_still_records_a_duration(self):
+        # The common case right now: the own bank is unreachable. The row must
+        # still carry a numeric duration so a slow/failed recall is attributable.
+        client = _FakeClient(
+            directives=[],
+            memories=[],
+            recall_exc=RuntimeError("HTTP 503 from http://localhost:18888"),
+        )
+        _run_main_with(client)
+        e = self._read_log()[0]
+        self.assertTrue(e["bank_errored"])
+        self.assertEqual(e["result_count"], 0)
+        self.assertIsInstance(e["duration_ms"], int)
+        self.assertGreaterEqual(e["duration_ms"], 0)
+
+    def _run_with_real_state(self, client, prompt):
+        """Invoke recall.main WITHOUT stubbing write_state/read_state, so the
+        per-session recall cache actually persists to CLAUDE_PLUGIN_DATA and a
+        second identical prompt takes the cache-hit path. (The shared
+        _run_main_with harness stubs write_state, which disables the cache.)"""
+        hook_input = {
+            "prompt": prompt,
+            "session_id": "cache-session",
+            "transcript_path": "",
+            "cwd": "/tmp",
+        }
+        config = {
+            "autoRecall": True,
+            "bankId": "test-bank",
+            "recallMaxTokens": 1024,
+            "recallBudget": "mid",
+            "recallContextTurns": 1,
+            "recallMaxQueryChars": 800,
+            "recallPromptPreamble": "",
+            "directivesCacheTtlSeconds": 0,
+        }
+        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("sys.stdin", new=io.StringIO(json.dumps(hook_input))), patch(
+            "sys.stdout", new=io.StringIO()
+        ), patch("sys.stderr", new=io.StringIO()):
+            recall.main()
+
+    def test_cache_hit_row_has_numeric_duration_ms(self):
+        # Populate the cache, then hit it on a second identical prompt. The
+        # cache-hit row must also carry duration_ms (total_elapsed_ms is None
+        # there, so duration_ms is the only latency number on a cache hit).
+        client = _FakeClient(directives=[], memories=[_memory("x", mem_id="x1")])
+        with patch.dict(os.environ, {"HINDSIGHT_RECALL_CACHE_TTL_SECS": "60"}):
+            self._run_with_real_state(client, "What did we decide about auth?")
+            self._run_with_real_state(client, "What did we decide about auth?")
+        rows = self._read_log()
+        hit_rows = [r for r in rows if r["cache_hit"]]
+        self.assertTrue(hit_rows, "expected at least one cache-hit row")
+        e = hit_rows[0]
+        self.assertIsNone(e["total_elapsed_ms"])
+        self.assertIsInstance(e["duration_ms"], int)
+        self.assertGreaterEqual(e["duration_ms"], 0)
+
+
+class StdoutUnchangedTests(unittest.TestCase):
+    """The instrumentation writes only to log files — the hook's stdout
+    (the recall-context JSON Claude Code consumes) must be byte-identical."""
+
+    def test_stdout_is_exact_and_carries_no_instrumentation(self):
+        client = _FakeClient(directives=[], memories=[_memory("a stored fact")])
+        # Pin the clock-derived preamble so the emitted block is deterministic,
+        # letting us assert the stdout bytes EXACTLY.
+        with patch.object(recall, "format_current_time", return_value="FIXED-TIME"):
+            ctx, raw = _run_main_with(client)
+
+        expected_context = (
+            "<hindsight_memories>\n"
+            "\n"  # empty recallPromptPreamble
+            "Current time - FIXED-TIME\n\n"
+            + recall.format_memories([_memory("a stored fact")])
+            + "\n</hindsight_memories>"
+        )
+        expected_raw = json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "UserPromptSubmit",
+                    "additionalContext": expected_context,
+                }
+            }
+        )
+        self.assertEqual(raw, expected_raw)
+        # Belt-and-braces: no instrumentation artifact leaked into the contract.
+        self.assertNotIn("duration_ms", raw)
+        self.assertNotIn("hook-timings", raw)
+        self.assertNotIn("total_elapsed_ms", raw)
+
+    def test_empty_recall_emits_empty_stdout(self):
+        # A no-directive, no-memory turn still emits nothing on stdout — the
+        # timing line lands in a log file, never here.
+        client = _FakeClient(directives=[], memories=[])
+        _ctx, raw = _run_main_with(client)
+        self.assertEqual(raw.strip(), "")
+
+
+class HookTimingLogEmissionTests(unittest.TestCase):
+    """_emit_hook_timing_log must reproduce bin/run-hook.sh's line schema,
+    weekday ring, and env-knob behaviour — the hook-timings row that lets this
+    UserPromptSubmit hook show up alongside every wrapped hook."""
+
+    def setUp(self):
+        self._tmpdir = tempfile.mkdtemp(prefix="hook-timings-test-")
+
+    def tearDown(self):
+        import shutil
+
+        shutil.rmtree(self._tmpdir, ignore_errors=True)
+
+    def _logfile(self):
+        dow = time.strftime("%a", time.localtime())
+        return os.path.join(self._tmpdir, f"hook-timings-{dow}.log")
+
+    def test_emits_line_with_run_hook_schema(self):
+        with patch.dict(os.environ, {"SWITCHROOM_HOOK_TIMING_DIR": self._tmpdir}):
+            recall._emit_hook_timing_log(142, 0)
+        path = self._logfile()
+        self.assertTrue(os.path.isfile(path))
+        with open(path, encoding="utf-8") as f:
+            lines = f.read().splitlines()
+        self.assertEqual(len(lines), 1)
+        row = json.loads(lines[0])
+        # Exact key set + types run-hook.sh writes.
+        self.assertEqual(
+            set(row.keys()), {"ts", "date", "source", "code", "duration_ms", "status"}
+        )
+        self.assertEqual(row["source"], "hook:hindsight-recall")
+        self.assertEqual(row["code"], "recall.py")
+        self.assertEqual(row["duration_ms"], 142)
+        self.assertEqual(row["status"], 0)
+        self.assertEqual(row["date"], time.strftime("%Y-%m-%d", time.localtime()))
+
+    def test_falls_back_to_telegram_state_dir(self):
+        with patch.dict(
+            os.environ,
+            {"TELEGRAM_STATE_DIR": self._tmpdir},
+            clear=False,
+        ), patch.dict(os.environ, {}, clear=False):
+            os.environ.pop("SWITCHROOM_HOOK_TIMING_DIR", None)
+            recall._emit_hook_timing_log(5, 0)
+        self.assertTrue(os.path.isfile(self._logfile()))
+
+    def test_disabled_by_env(self):
+        with patch.dict(
+            os.environ,
+            {
+                "SWITCHROOM_HOOK_TIMING": "0",
+                "SWITCHROOM_HOOK_TIMING_DIR": self._tmpdir,
+            },
+        ):
+            recall._emit_hook_timing_log(999, 0)
+        self.assertFalse(os.path.isfile(self._logfile()))
+
+    def test_min_ms_filters_fast_invocations(self):
+        with patch.dict(
+            os.environ,
+            {
+                "SWITCHROOM_HOOK_TIMING_DIR": self._tmpdir,
+                "SWITCHROOM_HOOK_TIMING_MIN_MS": "100",
+            },
+        ):
+            recall._emit_hook_timing_log(50, 0)  # below floor → dropped
+            recall._emit_hook_timing_log(150, 0)  # at/above → kept
+        with open(self._logfile(), encoding="utf-8") as f:
+            rows = [json.loads(x) for x in f if x.strip()]
+        self.assertEqual([r["duration_ms"] for r in rows], [150])
+
+    def test_no_dir_is_silent_noop(self):
+        # No timing dir and no TELEGRAM_STATE_DIR → nothing written, no raise.
+        with patch.dict(os.environ, {}, clear=False):
+            os.environ.pop("SWITCHROOM_HOOK_TIMING_DIR", None)
+            os.environ.pop("TELEGRAM_STATE_DIR", None)
+            recall._emit_hook_timing_log(10, 0)  # must not raise
+        self.assertFalse(os.path.isfile(self._logfile()))
+
+    def test_stale_weekday_file_is_reset(self):
+        path = self._logfile()
+        # Seed the ring file with a line dated a week ago (different date, same
+        # weekday) — the emitter must truncate it before appending today's row.
+        stale = (
+            '{"ts":"2000-01-01T00:00:00+0000","date":"2000-01-01",'
+            '"source":"hook:hindsight-recall","code":"recall.py",'
+            '"duration_ms":1,"status":0}\n'
+        )
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(stale)
+        with patch.dict(os.environ, {"SWITCHROOM_HOOK_TIMING_DIR": self._tmpdir}):
+            recall._emit_hook_timing_log(7, 0)
+        with open(path, encoding="utf-8") as f:
+            rows = [json.loads(x) for x in f if x.strip()]
+        # Stale line gone; exactly today's row remains.
+        self.assertEqual(len(rows), 1)
+        self.assertEqual(rows[0]["duration_ms"], 7)
+        self.assertEqual(rows[0]["date"], time.strftime("%Y-%m-%d", time.localtime()))
+
+
+if __name__ == "__main__":
+    unittest.main()