switchroom 0.17.6 → 0.17.10

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

@@ -0,0 +1,77 @@
+"""Switchroom gateway inbound-envelope grammar — the ONE place this vendored
+Python knows about switchroom's ``<channel source="...">`` wire format.
+
+SWITCHROOM DIVERGENCE (not upstream Hindsight). This module isolates the
+coupling between the vendored Python hooks and the switchroom telegram-plugin
+gateway's inbound envelope. It exists so a change to the TS-side envelope
+grammar has ONE obvious Python counterpart to update — instead of the grammar
+being buried inline inside directive_verify.py where a silent TS format change
+could break a Python guard undetected (#2903 Fix 6.3).
+
+The gateway prepends a leading ``<channel source="..." ...>`` envelope to every
+SYNTHESIZED / non-human inbound it injects into the model (cron fires, reaction
+dispatches, resume synthetics, vault-grant approvals, sub-agent handbacks,
+obligation representations, …). See, on the TS side:
+
+  * telegram-plugin/gateway/*-inbound-builder.ts (and the reaction / resume /
+    vault-grant / subagent / obligation builders) — they emit
+    ``<channel source="<name>" ...>``.
+  * A genuine human message from the primary channel carries
+    ``source="telegram"``; interactive (non-gateway) sessions carry NO envelope
+    at all.
+
+Contract pinned here (keep in lockstep with the gateway):
+  * ``CHANNEL_SOURCE_RE`` — extracts the ``source`` attribute from the leading
+    envelope. Handles both open (``<channel source="telegram" ...>``) and
+    self-closing (``<channel source="reaction"/>``) forms.
+  * ``HUMAN_INBOUND_SOURCES`` — the whitelist of ``source`` values that denote a
+    GENUINE human turn. A whitelist (not a blacklist) so any NEW synthetic
+    source the gateway adds is treated as machine-authored by default rather
+    than accidentally classified human.
+
+If the gateway ever renames the envelope tag, changes the attribute name, or
+adds a new human-facing channel, update THIS module (and its test,
+tests/test_switchroom_envelope.py). Nothing else in the Python tree should hard
+-code the ``<channel source=`` grammar.
+"""
+
+import re
+
+# Genuine human inbound channels. A "user" turn whose `<channel source="...">`
+# envelope names anything else is a SYNTHESIZED / cron inbound built by the
+# gateway — a machine turn, NOT a human correction.
+HUMAN_INBOUND_SOURCES = frozenset({"telegram"})
+
+# Pulls the source attribute out of the gateway's leading `<channel ...>`
+# envelope. Handles both open (`<channel source="telegram" ...>`) and
+# self-closing (`<channel source="reaction"/>`) forms.
+CHANNEL_SOURCE_RE = re.compile(r"""<channel\b[^>]*\bsource=["']([^"']+)["']""")
+
+
+def envelope_source(text) -> "str | None":
+    """Return the lower-cased ``source`` of the leading channel envelope, or
+    None when there is no envelope (interactive session). Pure regex."""
+    if not isinstance(text, str):
+        return None
+    m = CHANNEL_SOURCE_RE.search(text)
+    if not m:
+        return None
+    return m.group(1).strip().lower()
+
+
+def is_synthetic_inbound(text) -> bool:
+    """True when this turn's opening message is a synthesized/cron inbound
+    rather than a genuine human message.
+
+    Detection is purely on the gateway-prepended ``<channel source="...">``
+    envelope: a ``source`` outside ``HUMAN_INBOUND_SOURCES`` (``cron``,
+    ``reaction``, ``resume_interrupted``, ``vault_grant_approved``,
+    ``subagent_handback``, ``obligation_represent``, …) marks a non-human turn.
+    No envelope (interactive session) → treated as human. Injected channel tags
+    in a human's own body are neutralised upstream by the channel-envelope
+    sanitiser, so the only real ``<channel source=`` is the gateway's.
+    """
+    source = envelope_source(text)
+    if source is None:
+        return False
+    return source not in HUMAN_INBOUND_SOURCES

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

@@ -597,6 +597,128 @@ def _is_trivial_stateless(ack_form, stripped):
     return False
 
 
+# Switchroom #2848 Stage B — deterministic directive-capture nudge.
+#
+# Stage A audit (issue #2848) measured a ~55% miss rate on durable
+# corrections: the model is instructed (guidance-only, in
+# profiles/default/CLAUDE.md.hbs) to persist standing rules with
+# mcp__hindsight__create_directive, but does so inconsistently — capture
+# is a per-agent lottery (the same broadcast correction was captured by
+# one agent and silently dropped by two others). This adds DETERMINISTIC
+# detection of correction / standing-rule-shaped inbound (pure regex — NO
+# model callsite; the claude-native invariant forbids a classifier call)
+# and appends a terse advisory nudge to the UserPromptSubmit
+# additionalContext. The MODEL makes the judgment IN-SESSION and calls
+# create_directive itself (visible in chat); the hook NEVER writes a
+# directive on its own — a silent hook-side write would break
+# chat-legibility and edge the no-self-escalation invariant.
+#
+# On by default (Stage A proved a real gap → defaults principle);
+# operators opt out per-agent via memory.directive_capture_nudge=false in
+# switchroom.yaml, which start.sh exports as
+# HINDSIGHT_DIRECTIVE_CAPTURE_NUDGE=false (recall.py falls back to the
+# settings.json default, which switchroom pins on).
+#
+# Detection is intentionally inclusive (the nudge is cheap + advisory, so
+# a modest false-positive rate is acceptable — the model just ignores it
+# on a one-off), but a negative guard scrubs the obvious pleasantry
+# shapes ("always happy to help", "never mind") BEFORE the positive
+# match, so those don't fire on a bare "always"/"never".
+_DIRECTIVE_NUDGE_NEGATIVE_RE = re.compile(
+    r"""(?ix)
+    (?:
+        never \s* mind
+      | nevermind
+      | always \s+ (?: happy | glad | welcome | here \s+ to \s+ help | open \s+ to )
+      | never \s+ (?: fails? | hurts? | too \s+ late | a \s+ dull )
+      | as \s+ always
+      | thanks? \s+ as \s+ always
+      | forever \s+ grateful
+    )
+    """
+)
+
+_DIRECTIVE_NUDGE_RE = re.compile(
+    r"""(?ix)
+    (?:
+      # --- explicit standing-rule framings ---
+        \b from \s+ now \s+ on \b
+      | \b going \s+ forward \b
+      | \b in \s+ (?: the \s+ )? future \b
+      | \b (?: as \s+ a \s+ )? general \s+ (?: rule | behaviou?r | policy | principle | agent \s+ behaviou?r ) \b
+      | \b as \s+ a \s+ rule \b
+      | \b i \s+ want \s+ you \s+ to \b
+      | \b you \s+ should \s+ (?: always | never ) \b
+      # --- always / never (pleasantries pre-scrubbed by the negative guard) ---
+      | \b always \b
+      | \b never \b
+      | \b no \s+ longer \b
+      | \b anymore \b
+      # --- prohibitions / behavioural corrections ---
+      | \b stop \s+ (?: doing | saying | using | calling | adding | making | being | sending | putting ) \b
+      | \b (?: do \s* n['’]? t | don['’]? t | do \s+ not ) \s+ (?: ever \s+ )?
+            (?: make | guess | assume | use | say | add | send | call | include | do | put | write | reply | respond | mention ) \b
+      | \b (?: do \s* n['’]? t | don['’]? t | do \s+ not ) \b [^.?!]{0,40} \b again \b
+      | \b (?: should \s* n['’]? t | shouldn['’]? t | should \s+ not ) \b
+      # --- preferences / identity ---
+      | \b (?: i | we ) \s+ (?: prefer | always \s+ want | never \s+ want ) \b
+      | \b i['’]? d \s+ prefer \b
+      | \b call \s+ me \b
+      # --- memory / reinforcement ---
+      | \b remember \s+ (?: to | that | this | always | never ) \b
+      | \b make \s+ sure \s+ (?: you | to | that | not | it ) \b
+      # --- explicit wrongness + restatement ---
+      | \b that['’]? s \s+ (?: wrong | not \s+ right | incorrect | not \s+ what ) \b
+      | \b (?: no ,? \s+ )? it['’]? s \s+ (?: actually | not ) \b
+      | \b (?: that['’]? s | it['’]? s ) \s+ (?: dead | deprecated | retired | closed ) \b
+      | \b we \s+ (?: now \s+ )? (?: use \s+ only | only \s+ use | no \s+ longer \s+ use ) \b
+    )
+    """
+)
+
+# Terse, advisory. The model decides IN-SESSION whether this is a durable
+# rule and, if so, calls create_directive itself (chat-legible). Kept
+# short so it costs a handful of tokens on a false positive.
+_DIRECTIVE_CAPTURE_NUDGE = (
+    "<directive_capture_check>\n"
+    "The latest user message is correction- or standing-rule-shaped "
+    '(e.g. "always/never …", "from now on …", "stop doing …", a stated '
+    'preference, or "that’s wrong, it’s …"). If it states a DURABLE rule '
+    "for how you should behave going forward — not a one-off request for "
+    "this task — persist it NOW with mcp__hindsight__create_directive "
+    "(verbatim, in the user’s own words) BEFORE you answer, so the "
+    "correction survives future sessions. UNLESS an equivalent active "
+    "directive already exists (see any <active_directives> block above) — "
+    "in that case it is already saved; do NOT create a duplicate. If it’s "
+    "only a one-off instruction, ignore this note and just answer.\n"
+    "</directive_capture_check>"
+)
+
+
+def looks_like_standing_rule(text) -> bool:
+    """Deterministic (regex-only) test for correction / standing-rule shape.
+
+    Pleasantry shapes ("always happy to help", "never mind") are scrubbed
+    BEFORE the positive match so they can't trip the bare always/never
+    signals. Returns False on empty / non-string input. No model call —
+    the model does the actual judgment in-session (issue #2848).
+    """
+    if not isinstance(text, str) or not text.strip():
+        return False
+    scrubbed = _DIRECTIVE_NUDGE_NEGATIVE_RE.sub(" ", text)
+    return bool(_DIRECTIVE_NUDGE_RE.search(scrubbed))
+
+
+def _combine_context(base, nudge) -> str:
+    """Join the recall/directives context with the directive-capture nudge,
+    skipping empties. Either may be None/empty. The nudge is kept OUT of the
+    cached / last-recall context (it's transient per-inbound) and appended
+    only at emit time, so a cache hit re-derives it from the current prompt
+    rather than replaying a stale one."""
+    parts = [p for p in (base, nudge) if p]
+    return "\n\n".join(parts)
+
+
 def main():
     config = load_config()
 
@@ -665,6 +787,22 @@ def main():
         debug_log(config, f"Prompt is trivial/stateless ({_ack_form!r}), skipping recall")
         return
 
+    # Switchroom #2848 Stage B — directive-capture nudge. Deterministic
+    # (regex) detection of correction / standing-rule-shaped inbound; when
+    # it fires we append a terse advisory to the additionalContext telling
+    # the model to persist the rule with create_directive if it IS durable.
+    # Computed on `_stripped` (the channel-envelope-stripped text) so the
+    # `<channel …>` wrapper never trips detection. Runs AFTER the ack/
+    # trivial-skip gates (those return early and genuinely need no nudge)
+    # and leaves the recall/directive path below untouched — it only adds
+    # to whatever additionalContext that path emits. On by default;
+    # HINDSIGHT_DIRECTIVE_CAPTURE_NUDGE=false (or memory.directive_capture_nudge:
+    # false) turns it off. No model callsite (claude-native invariant).
+    nudge_block = None
+    if config.get("directiveCaptureNudge", True) and looks_like_standing_rule(_stripped):
+        nudge_block = _DIRECTIVE_CAPTURE_NUDGE
+        debug_log(config, "Directive-capture nudge: inbound looks like a standing rule")
+
     session_id = hook_input.get("session_id") or ""
 
     # Switchroom #303 — push a "📚 recalling memories" status to the
@@ -771,7 +909,10 @@ def main():
             cached_context = None
         if cached_context is not None:
             debug_log(config, f"Recall cache HIT (key={cache_key[:12]}…) — skipping API call")
-            _emit_cached_context(cached_context)
+            # #2848 — append the nudge to the cached context at emit time
+            # (the cache stores nudge-free context; the nudge is re-derived
+            # from the current prompt, so a hit can't replay a stale one).
+            _emit_cached_context(_combine_context(cached_context, nudge_block))
             _write_recall_log({
                 "ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
                 "session_id": (session_id or "")[:32],
@@ -790,6 +931,7 @@ def main():
                 "active_thread_id": active_thread_id,
                 "active_topic_alias": active_topic_alias,
                 "topic_filter_mode": _topic_filter_mode(),
+                "directive_nudge": bool(nudge_block),
             })
             return
         debug_log(config, f"Recall cache MISS (key={cache_key[:12]}…)")
@@ -1025,8 +1167,12 @@ def main():
         update_placeholder(placeholder_chat_id, "💭 thinking")
 
     # If neither block has content, there's nothing to inject — exit
-    # silently to avoid emitting an empty hookSpecificOutput.
+    # silently to avoid emitting an empty hookSpecificOutput. #2848: unless
+    # the directive-capture nudge fired, in which case emit the nudge alone
+    # (a correction with no memories/directives still needs the reminder).
     if not directives_block and not memories_block:
+        if nudge_block:
+            _emit_cached_context(nudge_block)
         return
 
     # Compose final context. Directives block goes ABOVE memories so the
@@ -1092,13 +1238,16 @@ def main():
         "source_topics": source_topic_summary,
         "topic_filter_mode": topic_filter_mode,
         "topic_dropped": topic_dropped,
+        "directive_nudge": bool(nudge_block),
     })
 
-    # Output JSON for Claude Code hook system
+    # Output JSON for Claude Code hook system. #2848: append the
+    # directive-capture nudge (if it fired) at emit time — it's kept out of
+    # the cached / last-recall context above so it can't go stale.
     output = {
         "hookSpecificOutput": {
             "hookEventName": "UserPromptSubmit",
-            "additionalContext": context_message,
+            "additionalContext": _combine_context(context_message, nudge_block),
         }
     }
     json.dump(output, sys.stdout)

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

@@ -147,6 +147,23 @@ def run_retain(hook_input: dict, force: bool = False) -> dict:
 
     debug_log(config, f"Retain hook_input keys: {list(hook_input.keys())} force={force}")
 
+    # Blocked-Stop double-fire guard (switchroom #2848 Phase 3): when
+    # directive_verify.py blocks a Stop, the model continues and the Stop
+    # event fires AGAIN, this time carrying ``stop_hook_active: true``.
+    # Retaining on that second fire would (a) POST a duplicate transcript
+    # document and (b) at retainEveryNTurns>1 call increment_turn_count a
+    # second time for the SAME logical turn — drifting the cadence throttle.
+    # Skip the re-fire entirely BEFORE any store or turn-count increment.
+    # A forced SessionEnd sweep (force=True) is a distinct hook event and
+    # must always flush, so it is exempt.
+    if not force and hook_input.get("stop_hook_active"):
+        debug_log(
+            config,
+            "Stop re-fire (stop_hook_active=true) — skipping retain to avoid "
+            "duplicate document / turn-count drift",
+        )
+        return {"status": "skipped", "reason": "stop_hook_active"}
+
     session_id = hook_input.get("session_id", "unknown")
     transcript_path = hook_input.get("transcript_path", "")
 

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

@@ -44,6 +44,15 @@ def build_hooks(plugin_root: str) -> dict:
             }
         ],
         "Stop": [
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": f'python3 "{plugin_root}/scripts/directive_verify.py"',
+                        "timeout": 10,
+                    }
+                ]
+            },
             {
                 "hooks": [
                     {

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

@@ -0,0 +1,185 @@
+"""Switchroom #2848 Stage B — unit tests for the directive-capture nudge.
+
+Stage A audit measured a ~55% miss rate on durable corrections: agents are
+told (guidance-only) to persist standing rules with
+`mcp__hindsight__create_directive`, but capture is a per-agent lottery. Stage B
+adds DETERMINISTIC (regex) detection of correction / standing-rule-shaped
+inbound in recall.py's UserPromptSubmit hook and appends a terse advisory nudge
+to the turn's additionalContext — the model does the actual judgment in-session
+(no model callsite; claude-native invariant).
+
+These tests pin:
+  * True positives — the audit's real MISSES + the issue's listed shapes.
+  * True negatives — pleasantries and questions must NOT fire (guard against
+    "always happy to help" / "never mind" tripping the bare always/never).
+  * The nudge is APPENDED to context without disturbing recall output
+    (_combine_context), and the nudge string is the create_directive advisory.
+  * The trivial-stateless recall gate is unaffected — a correction is never
+    trivial-skipped, and greetings still are (no regression on recall.py:582).
+
+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
+    _DIRECTIVE_CAPTURE_NUDGE,
+    _combine_context,
+    _is_trivial_stateless,
+    looks_like_standing_rule,
+)
+
+
+# Correction / standing-rule-shaped inbound that MUST fire the nudge.
+# The first block is drawn verbatim (paraphrased) from Stage A's clear MISSES
+# — the exact corrections the guidance-only path silently dropped.
+CORRECTIONS = [
+    # --- Stage A clear misses ---
+    "you should always hyperlink linear issues when mentioning",
+    "i also want you to always provide a direct link to open the email",
+    "i want this behaviour of validate, dont assume as a general agent behaviour",
+    "don't make stuff up, investigate and validate",
+    "validate not assume, don't guess",
+    "We shouldn't publish confidential Buildkite data, so don't use names",
+    "The repo mekenthompson/switchroom is closed/dead. We use only switchroom/switchroom now",
+    # --- Stage A true captures (must also detect — the loop should fire on these) ---
+    "i never use them",
+    "We don't use streaming reply anymore",
+    "i always want you to help better format articles for readability",
+    # --- the issue's listed standing-rule shapes ---
+    "from now on, prefer British spelling",
+    "going forward, use GFM syntax",
+    "call me Ken, not Kenneth",
+    "stop doing that",
+    "stop using em-dashes",
+    "don't do that again",
+    "remember to close the loop with a summary",
+    "make sure you cite the file and line",
+    "make sure not to leak the token",
+    "no, it's actually the blue one",
+    "that's wrong",
+    "that's not what I asked for",
+    "I'd prefer you keep replies short",
+    "we prefer concise answers",
+    "in the future, ping me before deploying",
+]
+
+# Pleasantries, one-off questions, acks — must NOT fire (false positives cost
+# tokens + noise; the negative guard scrubs pleasantry shapes first).
+NON_CORRECTIONS = [
+    "always happy to help!",
+    "I'm always glad to assist",
+    "never mind, forget it",
+    "nevermind that",
+    "thanks as always",
+    "as always, appreciate it",
+    "can you check the deploy status",
+    "what time is it",
+    "how do I fix this bug",
+    "tell me about the project",
+    "the CI issue is now closed",  # 'closed' alone, not "it's/that's closed"
+    "please run the tests",
+    "what's the weather like",
+    # The <channel …> envelope wrapper on its own must never trigger.
+    '<channel user="ken" chat_id="123">',
+]
+
+
+class TestDirectiveCaptureDetection(unittest.TestCase):
+    def test_corrections_fire_the_nudge(self):
+        for p in CORRECTIONS:
+            with self.subTest(prompt=p):
+                self.assertTrue(
+                    looks_like_standing_rule(p),
+                    f"expected standing-rule detection for {p!r}",
+                )
+
+    def test_pleasantries_and_questions_do_not_fire(self):
+        for p in NON_CORRECTIONS:
+            with self.subTest(prompt=p):
+                self.assertFalse(
+                    looks_like_standing_rule(p),
+                    f"FALSE POSITIVE: nudge would fire for {p!r}",
+                )
+
+    def test_empty_and_non_string_are_false(self):
+        for bad in ("", "   ", None, 123, [], {}):
+            with self.subTest(value=bad):
+                self.assertFalse(looks_like_standing_rule(bad))
+
+    def test_pleasantry_scrub_does_not_mask_a_real_rule(self):
+        # A message that opens with a pleasantry AND states a real rule must
+        # still fire — the negative guard scrubs only the pleasantry span.
+        self.assertTrue(
+            looks_like_standing_rule(
+                "always happy to help — but from now on use British spelling"
+            )
+        )
+        self.assertTrue(
+            looks_like_standing_rule("never mind that, but always cite the file")
+        )
+
+
+class TestNudgeAppendedWithoutDisturbingRecall(unittest.TestCase):
+    def test_nudge_string_is_the_create_directive_advisory(self):
+        self.assertIn("create_directive", _DIRECTIVE_CAPTURE_NUDGE)
+        self.assertIn("directive_capture_check", _DIRECTIVE_CAPTURE_NUDGE)
+
+    def test_nudge_carries_the_dedup_caveat(self):
+        # #2903 Fix 6.2: the nudge must tell the model NOT to re-create a rule
+        # that already exists as an active directive.
+        self.assertIn("already exists", _DIRECTIVE_CAPTURE_NUDGE)
+        self.assertIn("active_directives", _DIRECTIVE_CAPTURE_NUDGE)
+
+    def test_combine_appends_nudge_after_recall_block(self):
+        base = "<hindsight_memories>\n…\n</hindsight_memories>"
+        out = _combine_context(base, _DIRECTIVE_CAPTURE_NUDGE)
+        # Recall block preserved verbatim, nudge appended after it.
+        self.assertTrue(out.startswith(base))
+        self.assertTrue(out.endswith(_DIRECTIVE_CAPTURE_NUDGE))
+        self.assertIn(base + "\n\n", out)
+
+    def test_combine_with_no_nudge_leaves_recall_output_untouched(self):
+        base = "<hindsight_memories>\n…\n</hindsight_memories>"
+        self.assertEqual(_combine_context(base, None), base)
+
+    def test_combine_with_only_nudge_emits_nudge_alone(self):
+        self.assertEqual(
+            _combine_context("", _DIRECTIVE_CAPTURE_NUDGE), _DIRECTIVE_CAPTURE_NUDGE
+        )
+        self.assertEqual(
+            _combine_context(None, _DIRECTIVE_CAPTURE_NUDGE), _DIRECTIVE_CAPTURE_NUDGE
+        )
+
+    def test_combine_empty_is_empty(self):
+        self.assertEqual(_combine_context(None, None), "")
+        self.assertEqual(_combine_context("", ""), "")
+
+
+class TestTrivialSkipUnaffected(unittest.TestCase):
+    """The nudge must not perturb the trivial-stateless recall gate
+    (recall.py:582). Corrections carry standing-rule signals and are never
+    stateless, so they must NOT be trivial-skipped; greetings still are."""
+
+    def test_corrections_are_never_trivial_skipped(self):
+        for p in CORRECTIONS:
+            with self.subTest(prompt=p):
+                self.assertFalse(
+                    _is_trivial_stateless("", p),
+                    f"correction {p!r} was trivial-skipped — recall gate regressed",
+                )
+
+    def test_greetings_still_trivial_skip(self):
+        for p in ("hi", "hello", "what time is it", "good morning"):
+            with self.subTest(prompt=p):
+                self.assertTrue(_is_trivial_stateless("", p))
+
+
+if __name__ == "__main__":
+    unittest.main()