switchroom 0.21.15 → 0.21.17

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

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""SessionStart hook: Memory v2 M5 — orientation-at-boot (Surface B).
+
+carve-M5.md §3. Injects the agent's cron-refreshed ``orientation`` mental
+model into context at SessionStart AND re-seats it after every compaction —
+"reflect once, serve from cache" (E-79), deterministically, zero tool call.
+
+DARK BY DEFAULT (red-team kill switch). Entirely gated by
+``memoryOrientationEnabled`` (default False — carve §4, same discipline as
+M4's ``memoryPrefetchEnabled``). When off this hook is a hard no-op: it reads
+config, sees the flag off, and exits BEFORE any bank resolve or network call.
+The flag is per-agent — a stripped/absent value fails to OFF (fail-safe), so
+an un-flipped agent boots exactly as pre-M5.
+
+MATCHER-LESS (load-bearing, carve §1/§3). Registered with NO matcher, so it
+fires on every SessionStart source — startup, resume, clear, fork AND compact.
+The compact firing is the free deterministic post-compaction re-seat that
+answers E-88 ("nothing re-seats orientation today"): the hook re-reads the
+model from the engine each time, so a mid-session refresh is picked up at the
+next compaction with no session restart. Do NOT add a matcher.
+
+FAIL-SAFE INVARIANTS (all asserted in tests/test_orientation_hook.py):
+  - Boot is NEVER blocked on the orientation read. Every failure path
+    (server down, no model, read error, read timeout, degraded/undated
+    model) degrades to a VISIBLE one-line cold notice + a refresh request,
+    and exits 0. Never a silently memoryless boot, never a stale briefing
+    presented as fresh.
+  - A stale (1.5×–3× cadence) model is injected WITH a visible prefix; a
+    degraded (>3×) or undated model is NOT injected — the cold notice is
+    emitted instead. Thresholds are per-tier (carve §5), not a fixed 36h.
+
+STDOUT CONTRACT. A SessionStart hook's stdout IS added to the model's context
+(unlike PreCompact); we emit ``{"hookSpecificOutput":{"hookEventName":
+"SessionStart","additionalContext": "…"}}``. Exit code is 0 ALWAYS — a
+non-zero exit BLOCKS the turn in Claude Code, and orientation must degrade to
+a notice, never a hard stop (same doctrine as rules-sentinel-hook.sh).
+"""
+
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from lib import orientation as orient
+from lib.bank import derive_bank_id
+from lib.client import HindsightClient
+from lib.config import debug_log, load_config
+from lib.daemon import get_api_url
+
+#: Generous read-timeout for the model GET (carve §3). overlord's own-bank read
+#: is ~270ms and klanker's ~4ms (m0/m5-0 probes), but the latency asymmetry is
+#: unexplained and possibly bank-size-correlated, so leave headroom — and on a
+#: timeout degrade to the cold notice, never a hung boot.
+ORIENTATION_READ_TIMEOUT_S = 3
+
+
+def _emit(additional_context: str) -> None:
+    """Print the SessionStart additionalContext envelope to stdout."""
+    print(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "SessionStart",
+                    "additionalContext": additional_context,
+                }
+            }
+        )
+    )
+
+
+def enqueue_refresh(config: dict, bank_id: str, model_name: str) -> None:
+    """Signal that ``bank_id``'s orientation model needs a background refresh.
+
+    The cold/degraded path requests a refresh so a boot that found no usable
+    briefing does not stay briefing-less indefinitely (carve §3-4). This is the
+    SEAM the M5-C out-of-session tiered scheduler consumes; the scheduler is
+    cadence-driven regardless, so this is a best-effort nudge, never a blocking
+    dependency. Kept as a thin, override-able function so the cold-path tests
+    can assert the OUTCOME ("a refresh was requested") without a live scheduler.
+
+    Best-effort and total: any failure is swallowed — a boot must never fail
+    because a refresh request could not be recorded.
+    """
+    debug_log(
+        config,
+        f"orientation cold/degraded on bank '{bank_id}' model "
+        f"'{model_name}' — refresh requested",
+    )
+    try:
+        state_dir = os.environ.get("HINDSIGHT_STATE_DIR") or os.path.join(
+            os.path.expanduser("~"), ".hindsight"
+        )
+        os.makedirs(state_dir, exist_ok=True)
+        marker = os.path.join(state_dir, "orientation-refresh-pending.jsonl")
+        with open(marker, "a") as f:
+            f.write(json.dumps({"bank_id": bank_id, "model": model_name}) + "\n")
+    except Exception as e:  # noqa: BLE001 — best-effort, never breaks boot
+        debug_log(config, f"orientation refresh-request write failed (ignored): {e}")
+
+
+def _match_model(models: dict, name: str) -> dict | None:
+    """Find the mental model whose ``name`` matches the configured orientation name."""
+    items = models.get("items") if isinstance(models, dict) else None
+    if not isinstance(items, list):
+        return None
+    for item in items:
+        if isinstance(item, dict) and item.get("name") == name:
+            return item
+    return None
+
+
+def run(hook_input: dict, config: dict) -> None:
+    """Core hook logic. Emits at most one additionalContext block; never raises."""
+    if not config.get("memoryOrientationEnabled", False):
+        debug_log(config, "memoryOrientationEnabled off — orientation no-op")
+        return
+
+    model_name = config.get("memoryOrientationModel", "orientation")
+    cadence_hours = int(config.get("memoryOrientationCadenceHours", 48) or 48)
+    bank_id = derive_bank_id(hook_input, config)
+
+    def _dbg(*a):
+        debug_log(config, *a)
+
+    # Resolve the engine REST URL WITHOUT starting the daemon (too slow for
+    # SessionStart). If the server is unreachable, degrade to the cold notice —
+    # we cannot read the model, and boot must not block.
+    try:
+        api_url = get_api_url(config, debug_fn=_dbg, allow_daemon_start=False)
+        client = HindsightClient(api_url, config.get("hindsightApiToken"))
+    except (RuntimeError, ValueError) as e:
+        debug_log(config, f"orientation: Hindsight unreachable ({e}) — cold notice")
+        enqueue_refresh(config, bank_id, model_name)
+        _emit(orient.cold_notice())
+        return
+
+    # Resolve the orientation model by NAME → id, then read its content +
+    # freshness watermark. Any read error/timeout is a cold notice, not a hang.
+    try:
+        models = client.list_mental_models(bank_id, timeout=ORIENTATION_READ_TIMEOUT_S)
+        match = _match_model(models, model_name)
+    except Exception as e:  # noqa: BLE001 — degrade to cold, never block boot
+        debug_log(config, f"orientation: list models failed ({e}) — cold notice")
+        enqueue_refresh(config, bank_id, model_name)
+        _emit(orient.cold_notice())
+        return
+
+    if not match or not match.get("id"):
+        debug_log(config, f"orientation: no model named '{model_name}' — cold notice")
+        enqueue_refresh(config, bank_id, model_name)
+        _emit(orient.cold_notice())
+        return
+
+    try:
+        full = client.get_mental_model(
+            bank_id, match["id"], detail="full", timeout=ORIENTATION_READ_TIMEOUT_S
+        )
+    except Exception as e:  # noqa: BLE001 — includes urllib timeout
+        debug_log(config, f"orientation: model read failed ({e}) — cold notice")
+        enqueue_refresh(config, bank_id, model_name)
+        _emit(orient.cold_notice())
+        return
+
+    content = (full or {}).get("content") or ""
+    last_refreshed_at = (full or {}).get("last_refreshed_at")
+    state, hours_ago = orient.classify_staleness(last_refreshed_at, cadence_hours)
+
+    if not content.strip() or state in ("degraded", "unknown"):
+        # Empty payload, or refreshed > 3× cadence ago / undated: never present
+        # stale-as-fresh. Cold notice + refresh request (carve §5).
+        debug_log(config, f"orientation: state={state}, empty={not content.strip()} — cold notice")
+        enqueue_refresh(config, bank_id, model_name)
+        _emit(orient.cold_notice())
+        return
+
+    debug_log(config, f"orientation: injecting (state={state}, {hours_ago}h ago)")
+    _emit(orient.render_orientation(content, state, hours_ago))
+
+
+def main():
+    config = load_config()
+    try:
+        hook_input = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        hook_input = {}
+    run(hook_input, config)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:  # noqa: BLE001 — a hook that exits non-zero blocks the turn
+        print(f"[Hindsight] Orientation SessionStart error: {e}", file=sys.stderr)
+    sys.exit(0)

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

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""M4 P-PRE — async Stop-hook prefetch producer.
+
+carve-M4.md: moves recall injection off the synchronous UserPromptSubmit
+path by speculatively retaining + recalling at the END of turn N (this
+script, registered as an async Stop hook), so turn N+1's UserPromptSubmit
+(`recall.py`) can join an already-warm buffer instead of paying the full
+recall latency synchronously.
+
+Entirely gated by `memoryPrefetchEnabled` (default OFF/falsy — Fix C, the
+red-team-mandated per-agent kill switch). When off this script is a no-op:
+it reads config, sees the flag off, and exits silently before touching
+`lib.retain`, `lib.recall_buffer`, or the network.
+
+Call order (test a-integration in `tests/test_prefetch_pipeline.py`):
+  1. delta retain (`retain.run_retain(hook_input, force=False, delta=True)`)
+     — persists this turn's NEW slice using the Fix-A content-derived
+     document_id, never truncating the session document.
+  2. speculative recall (best-effort query derived from the transcript's
+     last human turn — the strongest available proxy for what turn N+1
+     will ask about).
+  3. `recall_buffer.write_buffer` then `recall_buffer.write_sentinel`
+     (STRICTLY in that order — the sentinel-ordering contract `lib/
+     recall_buffer.py` and `tests/test_recall_buffer.py` prove).
+
+Silent on stdout always (an async Stop hook's stdout is not surfaced to the
+transcript); errors go to stderr and NEVER raise past `main()` — a broken
+prefetch must degrade to "recall.py's synchronous path runs as before",
+never break the turn or leave a torn buffer (a crash between steps 2 and 3a
+just means no sentinel is written this turn, which `read_if_fresh` already
+treats as "nothing fresh" — fail-closed by construction).
+
+Skips the same junk turns `recall.py` skips (`<task-notification>` prefix)
+— a synthetic follow-up turn is not a real conversation shift worth
+prefetching for.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from lib.bank import derive_bank_id
+from lib.client import HindsightClient
+from lib.config import debug_log, load_config
+from lib.content import _extract_text_content, strip_channel_envelope
+from lib.daemon import get_api_url
+from lib import recall_buffer
+import retain as retain_module
+
+
+def _last_human_prompt(transcript_path: str) -> str:
+    """Best-effort: the most recent human-authored user turn's text, used
+    as the speculative query for next turn's prefetch. Never raises —
+    returns "" on any read/parse failure (degrades to no query, which the
+    caller treats as "nothing to prefetch")."""
+    try:
+        messages = retain_module.read_transcript(transcript_path)
+    except Exception:
+        return ""
+    for msg in reversed(messages):
+        if msg.get("role") != "user":
+            continue
+        text = _extract_text_content(msg.get("content"), role="user")
+        text = strip_channel_envelope(text) if text else text
+        if text and text.strip():
+            return text.strip()
+    return ""
+
+
+def run_prefetch(hook_input: dict, config: dict) -> bool:
+    """Execute one prefetch cycle. Returns True iff a buffer+sentinel pair
+    was written. Never raises — every internal step is wrapped so a bug in
+    ANY sub-step degrades to "no buffer written this turn", never a crash
+    that could take the Stop hook (and thus the turn) down with it."""
+    session_id = hook_input.get("session_id") or "unknown"
+
+    prompt = (hook_input.get("prompt") or hook_input.get("user_prompt") or "").strip()
+    if prompt.startswith("<task-notification"):
+        debug_log(config, "Prefetch: task-notification turn, skipping")
+        return False
+
+    # Step 0 — MUTATION INVALIDATION (red-team-M3 R2, BLOCKER). This turn is
+    # about to retain (step 1) — a memory mutation. Drop any buffer left from a
+    # prior turn BEFORE recalling, so that if this turn's fresh recall fails or
+    # returns empty (steps 2-3 below bail without overwriting), the consumer
+    # cannot resurrect the pre-mutation snapshot: with no sentinel it falls to
+    # the explicitly stale-marked LAST_RECALL_STATE / degraded notice instead of
+    # serving a stale buffer as fresh. A successful recall repopulates the buffer
+    # with the post-mutation snapshot at step 3. Never raises.
+    recall_buffer.invalidate(session_id)
+
+    # Step 1 — delta retain (Fix A: content-derived document_id, never the
+    # bare {session_id} document; never truncates).
+    try:
+        retain_module.run_retain(hook_input, force=False, delta=True)
+    except Exception as exc:  # pragma: no cover - defensive
+        debug_log(config, f"Prefetch: delta retain failed, continuing without it: {exc}")
+
+    # Step 2 — speculative recall.
+    transcript_path = hook_input.get("transcript_path") or ""
+    query = _last_human_prompt(transcript_path)
+    if not query:
+        debug_log(config, "Prefetch: no usable query, nothing to prefetch")
+        return False
+
+    try:
+        bank_id = derive_bank_id(hook_input, config)
+        api_url = get_api_url(config)
+        client = HindsightClient(api_url)
+        response = client.recall(
+            bank_id,
+            query,
+            types=None,
+            timeout=config.get("memoryPrefetchTimeoutSeconds", 5),
+        )
+        results = (response or {}).get("results") or []
+    except Exception as exc:  # pragma: no cover - defensive
+        debug_log(config, f"Prefetch: recall fetch failed: {exc}")
+        return False
+
+    if not results:
+        debug_log(config, "Prefetch: no candidates, nothing to buffer")
+        return False
+
+    from lib.content import format_memories
+
+    memories_block = format_memories(results)
+    if not memories_block:
+        return False
+
+    # Step 3 — write payload THEN sentinel, strictly in that order.
+    try:
+        recall_buffer.write_buffer(session_id, memories_block, {"result_count": len(results)})
+        recall_buffer.write_sentinel(session_id)
+    except Exception as exc:  # pragma: no cover - defensive
+        debug_log(config, f"Prefetch: buffer write failed: {exc}")
+        return False
+
+    return True
+
+
+def main():
+    config = load_config()
+    if not config.get("memoryPrefetchEnabled", False):
+        # Fix C, producer side: the whole mechanism is dark by default.
+        return
+
+    try:
+        hook_input = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        print("[Hindsight] Prefetch: failed to read hook input", file=sys.stderr)
+        return
+
+    try:
+        run_prefetch(hook_input, config)
+    except Exception as exc:  # pragma: no cover - defensive, must never break the turn
+        print(f"[Hindsight] Prefetch: unexpected error: {exc}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:  # pragma: no cover - defensive
+        print(f"[Hindsight] Unexpected error in prefetch: {e}", file=sys.stderr)
+        sys.exit(0)