switchroom 0.19.2 → 0.19.4

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

@@ -33,11 +33,17 @@ def strip_channel_envelope(content: str) -> str:
     This is the Claude Code equivalent of Openclaw's stripMetadataEnvelopes().
     Extracts the inner text, preserving the actual user message while removing
     transport metadata that Hindsight doesn't need.
+
+    A single prompt may carry MORE THAN ONE envelope (e.g. a coalesced
+    burst where several inbound messages were concatenated). Since this now
+    sits on the live recall-query path (hindsight-leverage PR 1, review
+    finding 6), coalesce EVERY envelope's inner text rather than keeping only
+    the first and silently dropping everything after the first ``</channel>``.
     """
-    # Match <channel ...>content</channel> — extract inner text
-    match = re.search(r"<channel\b[^>]*>([\s\S]*?)</channel>", content)
-    if match:
-        return match.group(1).strip()
+    # Match every <channel ...>content</channel> — extract & join inner texts.
+    matches = re.findall(r"<channel\b[^>]*>([\s\S]*?)</channel>", content)
+    if matches:
+        return "\n".join(m.strip() for m in matches if m.strip()).strip()
     return content
 
 
@@ -79,7 +85,14 @@ def compose_recall_query(
 
         <latest query>
     """
-    latest = latest_query.strip()
+    # Switchroom A1 (hindsight-leverage PR 1) — strip the <channel> envelope
+    # from the latest query INSIDE the helper as well, so any caller (present
+    # or future) gets an envelope-free composed query. The recall.py caller
+    # already strips before calling, but keeping the strip here is defence in
+    # depth: it guarantees the trailing latest-query segment appended below
+    # (and returned on the turns<=1 short-circuit) never carries the raw
+    # chat_id/ts/user XML noise into the embedding or the char cap.
+    latest = strip_channel_envelope(latest_query).strip()
     if recall_context_turns <= 1 or not isinstance(messages, list) or not messages:
         return latest
 
@@ -236,6 +249,43 @@ def slice_last_turns_by_user_boundary(messages: list, turns: int) -> list:
     return messages[start_index:]
 
 
+# ---------------------------------------------------------------------------
+# Sidechain (sub-agent transcript) detection
+# ---------------------------------------------------------------------------
+
+
+def transcript_first_line_is_sidechain(path: str) -> bool:
+    """True when the first JSON line of ``path`` carries ``isSidechain: true``.
+
+    Switchroom hindsight-leverage PR5. Claude Code writes sub-agent (Task-tool)
+    transcripts as separate ``.jsonl`` files under
+    ``<project>/<session>/subagents/agent-<agent_id>.jsonl`` whose every line
+    carries ``isSidechain: true``. This shared predicate lets BOTH the
+    SubagentStop retain (which resolves + retains these deliberately, tagged
+    ``sidechain`` + volume-gated) AND the boot reconciler / any transcript
+    sweeper (which must NOT treat a sidechain as a pseudo-session and re-retain
+    it untagged, at full recall weight, bypassing the volume gate) recognise a
+    sidechain file from its first line alone — a cheap single-line read. Any
+    read/parse error is treated as "not a sidechain" (fail-open: a
+    genuinely-unreadable file is skipped elsewhere by its empty transcript).
+    """
+    import json
+
+    try:
+        with open(path, encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    return json.loads(line).get("isSidechain") is True
+                except json.JSONDecodeError:
+                    return False
+    except OSError:
+        return False
+    return False
+
+
 # ---------------------------------------------------------------------------
 # Memory formatting (recall results → context string)
 # ---------------------------------------------------------------------------

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

@@ -18,8 +18,11 @@ recall path; a directive-fetch failure must not kill the recall block.
 
 import re
 import sys
+import time
 from typing import Optional
 
+from .state import list_state_names, read_state, remove_state, write_state
+
 # Sanity cap on how many directives we ever inject into the prompt. Banks
 # with more active directives than this are pathological; truncate with a
 # footer so the agent knows there are more.
@@ -29,25 +32,56 @@ MAX_DIRECTIVES = 15
 # UserPromptSubmit critical path — we cannot block it for long.
 DIRECTIVES_TIMEOUT_SECONDS = 2
 
+# --- Directives-list cache (switchroom hindsight-leverage A4) -----------------
+#
+# `list_directives` runs on the recall (UserPromptSubmit) critical path every
+# non-skipped turn — a fresh 2s-timeout HTTP round-trip whose result changes
+# only when a directive is created/updated/deleted (rare). We cache the fetched
+# list in the plugin state dir with a short TTL so the common no-write turn
+# skips the round-trip, while bounding staleness:
+#   * In-session writes: directive_verify.py (Stop hook) deletes the cache when
+#     the just-ended turn contains a create/update/delete_directive tool_use, so
+#     the very next recall re-fetches — the new state is visible in turn N+1.
+#   * Cross-process writes (another session, operator CLI) have no invalidation
+#     channel and rely on TTL alone → at most TTL seconds stale.
+#
+# Invalidation blind spots (both fall back to TTL, ≤ TTL stale — acceptable):
+#   * Sub-agent / sidechain directive writes: the create_directive tool_use is
+#     in the SIDECHAIN transcript, not the parent's, so the parent's Stop hook
+#     (which reads the parent transcript) never sees it. PR 5 (SubagentStop)
+#     is where sidechain awareness lands.
+#   * Bash / operator-CLI directive writes (`switchroom` or a curl) produce no
+#     tool_use in any transcript, so there is nothing for the Stop hook to
+#     detect.
+#
+# Rollback: set the TTL to 0 (HINDSIGHT_DIRECTIVES_CACHE_TTL_SECONDS=0) to
+# disable the cache entirely — every turn fetches live, as before A4.
+DIRECTIVES_CACHE_TTL_SECONDS = 120
 
-def fetch_active_directives(client, bank_id: str, timeout: int = DIRECTIVES_TIMEOUT_SECONDS) -> list:
-    """Fetch active directives for a bank, sorted by priority (highest first).
+# All directive cache files share this basename prefix so they can be
+# enumerated for bulk (bank-agnostic) invalidation.
+_CACHE_PREFIX = "directives_cache."
 
-    Args:
-        client: A HindsightClient instance with a list_directives method.
-        bank_id: The bank to fetch directives from.
-        timeout: HTTP timeout in seconds.
 
-    Returns:
-        A list of directive dicts (each with id, name, content, priority,
-        tags, ...), sorted by priority descending. On any failure returns
-        an empty list and logs a single warn line to stderr — never raises.
+def _cache_name(bank_id: str) -> str:
+    """State-file name for a bank's cached directive list."""
+    return f"{_CACHE_PREFIX}{bank_id}.json"
+
+
+def _fetch_directives_with_status(client, bank_id: str, timeout: int) -> tuple:
+    """Fetch + normalize active directives, reporting fetch success.
+
+    Returns ``(ok, directives)``. ``ok`` is False only on a genuine fetch
+    FAILURE (HTTP error, non-dict response) — a bank that simply has no
+    directives returns ``(True, [])``. Callers use ``ok`` to avoid caching a
+    transient failure's empty result (which would mask real directives for a
+    whole TTL window). Never raises; logs a single warn line on failure.
     """
     try:
         response = client.list_directives(bank_id=bank_id, active_only=True, timeout=timeout)
     except Exception as e:
         print(f"[Hindsight] list_directives failed for bank '{bank_id}': {e}", file=sys.stderr)
-        return []
+        return False, []
 
     if not isinstance(response, dict):
         print(
@@ -55,20 +89,123 @@ def fetch_active_directives(client, bank_id: str, timeout: int = DIRECTIVES_TIME
             f"{type(response).__name__}",
             file=sys.stderr,
         )
-        return []
+        return False, []
 
     items = response.get("items")
     if not isinstance(items, list):
         # Empty / malformed response — quiet success, no warn (banks with
-        # no directives are normal).
-        return []
+        # no directives are normal). Cacheable.
+        return True, []
 
     # Filter to dicts only, then sort by priority descending. Treat missing
     # priority as 0 so malformed entries sink to the bottom rather than
     # crashing.
     valid = [d for d in items if isinstance(d, dict)]
     valid.sort(key=lambda d: d.get("priority", 0), reverse=True)
-    return valid
+    return True, valid
+
+
+def fetch_active_directives(client, bank_id: str, timeout: int = DIRECTIVES_TIMEOUT_SECONDS) -> list:
+    """Fetch active directives for a bank, sorted by priority (highest first).
+
+    Args:
+        client: A HindsightClient instance with a list_directives method.
+        bank_id: The bank to fetch directives from.
+        timeout: HTTP timeout in seconds.
+
+    Returns:
+        A list of directive dicts (each with id, name, content, priority,
+        tags, ...), sorted by priority descending. On any failure returns
+        an empty list and logs a single warn line to stderr — never raises.
+    """
+    _ok, directives = _fetch_directives_with_status(client, bank_id, timeout)
+    return directives
+
+
+def _read_cache(bank_id: str) -> Optional[dict]:
+    """Read + validate a bank's cache envelope. Returns None on miss/corruption.
+
+    A corrupted or wrong-shaped cache (bad JSON handled by read_state; here we
+    additionally reject a non-dict envelope, a non-numeric timestamp, or a
+    non-list directive payload) is treated as a MISS so the caller falls back to
+    a live fetch rather than injecting garbage.
+
+    Also rejects an envelope whose stored ``bank_id`` does not match the
+    requested one: ``_safe_filename`` can collapse two distinct bank ids onto a
+    single cache file, and serving bank A's directives for bank B would leak
+    rules across banks. The embedded ``bank_id`` is the authoritative key.
+    """
+    raw = read_state(_cache_name(bank_id), None)
+    if not isinstance(raw, dict):
+        return None
+    if raw.get("bank_id") != bank_id:
+        return None
+    ts = raw.get("ts")
+    directives = raw.get("directives")
+    if not isinstance(ts, (int, float)) or isinstance(ts, bool):
+        return None
+    if not isinstance(directives, list):
+        return None
+    return raw
+
+
+def fetch_active_directives_cached(
+    client,
+    bank_id: str,
+    ttl_seconds: int = DIRECTIVES_CACHE_TTL_SECONDS,
+    timeout: int = DIRECTIVES_TIMEOUT_SECONDS,
+    now: Optional[float] = None,
+) -> list:
+    """Cached wrapper around :func:`fetch_active_directives`.
+
+    On a fresh cache hit (age < ``ttl_seconds``) returns the cached list WITHOUT
+    an HTTP call. On a miss / expiry / corrupted cache, fetches live and, when
+    the fetch SUCCEEDED, writes the cache. A failed fetch is never cached, so a
+    transient error can't mask real directives for a TTL window.
+
+    ``ttl_seconds <= 0`` disables the cache (always live-fetch, never write) —
+    the A4 rollback lever.
+
+    Args:
+        now: Injectable current epoch seconds, for deterministic tests.
+    """
+    if now is None:
+        now = time.time()
+
+    caching = isinstance(ttl_seconds, (int, float)) and ttl_seconds > 0
+
+    if caching:
+        cached = _read_cache(bank_id)
+        if cached is not None:
+            age = now - cached["ts"]
+            # A negative age means the stored timestamp is in the FUTURE
+            # (wall-clock step-back / a doctored envelope) — treat it as
+            # expired rather than "fresh forever", so a clock correction can't
+            # pin a stale cache.
+            if 0 <= age < ttl_seconds:
+                return cached["directives"]
+
+    ok, directives = _fetch_directives_with_status(client, bank_id, timeout)
+
+    if caching and ok:
+        write_state(_cache_name(bank_id), {"ts": now, "bank_id": bank_id, "directives": directives})
+
+    return directives
+
+
+def invalidate_directives_cache(bank_id: Optional[str] = None) -> None:
+    """Delete the directives cache so the next recall re-fetches live.
+
+    With ``bank_id`` set, removes just that bank's cache file. With no argument
+    (the Stop-hook invalidation path, which does not resolve the bank), removes
+    EVERY directive cache file — directive writes are rare, so a bank-agnostic
+    sweep is cheap and robust. Best-effort; never raises.
+    """
+    if bank_id is not None:
+        remove_state(_cache_name(bank_id))
+        return
+    for name in list_state_names(_CACHE_PREFIX):
+        remove_state(name)
 
 
 def format_active_directives_block(directives: list, max_directives: int = MAX_DIRECTIVES) -> Optional[str]:

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

@@ -0,0 +1,142 @@
+"""Deadline-bounded parallel fan-out for the recall critical path.
+
+Switchroom hindsight-leverage A3 (parallel multi-bank recall). The recall
+hook (``recall.py``) queries the agent's own bank, every additional bank
+(profile / shared / sender), and the active-directives list. Serially, the
+critical-path latency is the SUM of those round-trips — a heavy agent with two
+extra banks plus directives can serialise four 2-8s calls and breach the 12s
+UserPromptSubmit hook ceiling, which drops recall entirely for that turn.
+
+This runs each labelled task in its OWN daemon thread and waits only until a
+single SHARED deadline (the hook ceiling minus a headroom margin). Key
+properties, all enforced by mechanism rather than convention:
+
+  * **Daemon threads.** Every worker is a daemon, so a thread still blocked on
+    a socket read when the deadline elapses can NEVER keep the interpreter (and
+    therefore the hook) alive past the ceiling — the process exits and the
+    kernel reaps the socket. ``recall.py``'s ``__main__`` additionally calls
+    ``os._exit(0)`` after flushing stdout as a belt-and-suspenders against any
+    non-daemon thread a client library might spawn.
+
+  * **One shared deadline.** Total wait is bounded by ``deadline_seconds`` from
+    the moment ``run_parallel`` is entered — not per-task — so N slow banks
+    cost the deadline ONCE, not N times.
+
+  * **Completion is observed, not assumed.** Each slot records whether its
+    thread finished before we stopped waiting (``completed``), its return value
+    or exception, and its wall-clock ``elapsed_ms``. A slot still running at the
+    deadline is ``completed=False`` with ``elapsed_ms`` pinned to the deadline —
+    the caller maps that to ``timed_out`` for telemetry.
+
+Stdlib-only (threading + time); no third-party deps, importable under the
+plugin's ``python3 -m unittest`` harness.
+"""
+
+import threading
+import time
+
+
+class SlotResult:
+    """Outcome of one labelled task run under the shared deadline.
+
+    Attributes:
+        label:      the task's key in the ``tasks`` mapping.
+        value:      the callable's return value, or None if it raised / did not
+                    finish before the deadline.
+        error:      the exception the callable raised, or None. A slot that hit
+                    the deadline mid-flight has ``error=None`` and
+                    ``completed=False`` (it never got to raise or return).
+        completed:  True iff the worker thread finished (returned or raised)
+                    before ``run_parallel`` stopped waiting on it. False means
+                    the shared deadline elapsed first.
+        elapsed_ms: wall-clock ms the slot took. For a completed slot this is
+                    its real duration; for a deadline-abandoned slot it is the
+                    time from fan-out start to the deadline.
+    """
+
+    __slots__ = ("label", "value", "error", "completed", "elapsed_ms")
+
+    def __init__(self, label):
+        self.label = label
+        self.value = None
+        self.error = None
+        self.completed = False
+        self.elapsed_ms = None
+
+
+def _runner(slot, fn, start):
+    """Worker body: run the task, capturing value/exception and duration.
+
+    Catches ``BaseException`` deliberately for slot isolation: a slot runs in
+    its own daemon thread, and a task failure of ANY kind — including
+    non-``Exception`` subclasses like ``KeyboardInterrupt`` /
+    ``SystemExit`` — must be captured into ``slot.error`` rather than escaping
+    the thread. An escaped exception would let the slot die silently and the
+    deadline join would then see no value AND no recorded error. (``socket.timeout``
+    is itself just an ``OSError`` subclass, i.e. an ordinary ``Exception``; the
+    broad catch is about never letting any slot failure leak out of the thread.)
+    """
+    try:
+        slot.value = fn()
+    except BaseException as e:  # noqa: BLE001 - deliberate: isolate the slot
+        slot.error = e
+    finally:
+        slot.elapsed_ms = int((time.monotonic() - start) * 1000)
+
+
+def run_parallel(tasks, deadline_seconds):
+    """Run ``{label: callable}`` concurrently under one shared deadline.
+
+    Args:
+        tasks: mapping of label -> zero-arg callable. Each is invoked once in
+            its own daemon thread. Insertion order is preserved in the returned
+            mapping (Python dicts are ordered) so the caller can emit per-slot
+            telemetry deterministically regardless of completion order.
+        deadline_seconds: total wall-clock budget for ALL tasks combined,
+            measured from entry. Non-positive values run every task with a
+            zero join (each slot is recorded as not-completed unless it was
+            already instantaneous) — a degenerate "give up immediately" mode.
+
+    Returns:
+        ``dict[label] -> SlotResult`` in the same order as ``tasks``. Never
+        raises for a task failure — a raising task surfaces via
+        ``SlotResult.error``.
+    """
+    start = time.monotonic()
+    pairs = []  # (SlotResult, Thread) in task order
+    for label, fn in tasks.items():
+        slot = SlotResult(label)
+        thread = threading.Thread(
+            target=_runner,
+            args=(slot, fn, start),
+            daemon=True,
+            name=f"recall-slot-{label}",
+        )
+        pairs.append((slot, thread))
+
+    for _slot, thread in pairs:
+        thread.start()
+
+    # Join each thread, but never wait past the SHARED deadline. Because the
+    # remaining budget is recomputed from ``start`` on every iteration, the
+    # total time spent here is bounded by ``deadline_seconds`` even with many
+    # slow slots — a fast early slot leaves more budget for later ones, and
+    # once the budget is exhausted every subsequent join is a non-blocking
+    # ``is_alive`` check.
+    for _slot, thread in pairs:
+        remaining = deadline_seconds - (time.monotonic() - start)
+        if remaining > 0:
+            thread.join(remaining)
+
+    # Classify each slot as completed (thread finished) or deadline-abandoned.
+    now = time.monotonic()
+    results = {}
+    for slot, thread in pairs:
+        if thread.is_alive():
+            slot.completed = False
+            if slot.elapsed_ms is None:
+                slot.elapsed_ms = int((now - start) * 1000)
+        else:
+            slot.completed = True
+        results[slot.label] = slot
+    return results

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

@@ -82,6 +82,37 @@ def write_state(name: str, data):
             pass
 
 
+def remove_state(name: str) -> None:
+    """Delete a state file if it exists. Best-effort; never raises.
+
+    Name is sanitized through the same path-traversal guard as read/write, so
+    callers cannot escape the state directory.
+    """
+    try:
+        path = _state_file(name)
+    except ValueError:
+        return
+    try:
+        os.remove(path)
+    except OSError:
+        pass
+
+
+def list_state_names(prefix: str = "") -> list:
+    """List state-file basenames in the state dir, optionally by prefix.
+
+    Returns [] on any error. Used to enumerate a family of cache files (e.g.
+    per-bank directive caches) for bulk invalidation.
+    """
+    try:
+        names = os.listdir(_state_dir())
+    except OSError:
+        return []
+    if prefix:
+        return [n for n in names if n.startswith(prefix)]
+    return names
+
+
 def get_turn_count(session_id: str) -> int:
     """Get the current turn count for a session."""
     turns = read_state("turns.json", {})