switchroom 0.21.16 → 0.21.18

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

@@ -0,0 +1,248 @@
+"""Memory v2 M5 — Surface B: orientation-at-boot (pure logic).
+
+carve-M5.md §3/§5/§0c. This module holds the network-free, deterministically
+testable half of the orientation SessionStart hook: staleness classification
+(per-tier thresholds, NOT a fixed 36h), rule-aware truncation to the content
+token budget, and the `additionalContext` rendering. The hook entry
+(`orientation.py`) does the I/O — resolve own bank, list mental models, match
+the orientation model by name, GET its content — and calls into here so the
+budget/staleness/render logic can be unit-tested without a live engine.
+
+Why the split mirrors the fleet's other deterministic memory surfaces
+(recall.py's nudge regexes, prefetch.py's buffer contract): the value is a
+DETERMINISTIC mechanism, not model discretion, so every branch that decides
+"inject / prefix-as-stale / degrade-to-cold / truncate" must be pinned by a
+test that fails on the bug it guards (carve §8 tautology-guard discipline).
+
+TOKEN BUDGET (carve §0c). The epic caps the injected briefing at 2048 tokens,
+but M0 measured real mental models at ~1,766–1,962 tokens of CONTENT alone —
+so a naive "cap at 2048" overflows the moment a stale prefix or framing is
+prepended. The real number to design to is a CONTENT budget below the cap,
+leaving headroom for the prefix + framing. Truncation is rule-aware: whole
+markdown sections are kept, trailing sections dropped, and a visible marker is
+emitted so the loss is never silent.
+"""
+
+from __future__ import annotations
+
+import math
+from datetime import datetime, timezone
+
+#: Hard ceiling on the total injected `additionalContext` (epic line 143).
+ORIENTATION_TOTAL_TOKEN_CAP = 2048
+#: Budget for the model CONTENT alone, below the cap so the stale prefix +
+#: framing tags fit inside 2048 (carve §0c: ~1,800, reserving ~250).
+ORIENTATION_CONTENT_TOKEN_BUDGET = 1800
+#: Chars-per-token estimate M0 used to convert measured char sizes to tokens
+#: (7,063 chars ≈ 1,766 tokens). Deterministic proxy — no tokenizer dependency
+#: on the boot critical path.
+CHARS_PER_TOKEN = 4
+
+#: Emitted (once) when trailing sections were dropped to fit the budget, so the
+#: loss is visible to the model rather than a silent mid-sentence byte-cut.
+TRUNCATION_MARKER = "(orientation truncated to fit context budget)"
+
+# Framing tags. Kept intentionally tiny — they count against the 2048 cap.
+_OPEN_TAG = "<orientation source=\"memory\">"
+_CLOSE_TAG = "</orientation>"
+
+
+def estimate_tokens(text: str) -> int:
+    """Deterministic token estimate (ceil of chars / CHARS_PER_TOKEN).
+
+    A proxy, not a real tokenizer — but the SAME proxy M0 measured content
+    sizes with, so the budget math is internally consistent, and it needs no
+    model/tokenizer on the boot path. Empty string is 0 tokens.
+    """
+    if not text:
+        return 0
+    return math.ceil(len(text) / CHARS_PER_TOKEN)
+
+
+def classify_staleness(
+    last_refreshed_at: str | None,
+    cadence_hours: int,
+    now: datetime | None = None,
+) -> tuple[str, float | None]:
+    """Classify an orientation model's freshness against its agent's TIER.
+
+    Returns ``(state, hours_ago)`` where state is one of:
+      - ``"fresh"``    — refreshed < 1.5× cadence ago: inject plainly.
+      - ``"stale"``    — 1.5×–3× cadence ago: inject WITH a visible prefix.
+      - ``"degraded"`` — > 3× cadence ago: do NOT inject stale-as-fresh; the
+                          hook emits the cold notice + enqueues a refresh.
+      - ``"unknown"``  — no/unparseable ``last_refreshed_at``: treat as cold
+                          (fail closed — never present an un-dated model as
+                          fresh). ``hours_ago`` is None.
+
+    The thresholds are PER-TIER (carve §5): a fixed 36h would mislabel every
+    48h-cadence agent as stale a full day early. 1.5× / 3× of the resolved
+    cadence is the tier-correct boundary — 36h/72h at cadence 24, 72h/144h at
+    cadence 48. Keyed on ``last_refreshed_at`` (the freshness watermark the
+    persisting refresh advances — m5-0-probe Q3), NOT ``updated_at`` (returned
+    null on the single-model read) and NOT the engine's own ``is_stale`` (its
+    threshold is engine-defined, not the agent's tier).
+    """
+    if now is None:
+        now = datetime.now(timezone.utc)
+    if not last_refreshed_at:
+        return ("unknown", None)
+    ts = _parse_iso(last_refreshed_at)
+    if ts is None:
+        return ("unknown", None)
+    # A naive timestamp is assumed UTC (the engine stores tz-aware UTC; this is
+    # belt-and-braces so an aware/naive mismatch can never raise on subtract).
+    if ts.tzinfo is None:
+        ts = ts.replace(tzinfo=timezone.utc)
+    hours_ago = (now - ts).total_seconds() / 3600.0
+    # Guard a clock-skew future timestamp: treat as fresh, never negative-stale.
+    if hours_ago < 0:
+        hours_ago = 0.0
+    stale_at = 1.5 * cadence_hours
+    degrade_at = 3.0 * cadence_hours
+    if hours_ago < stale_at:
+        return ("fresh", hours_ago)
+    if hours_ago < degrade_at:
+        return ("stale", hours_ago)
+    return ("degraded", hours_ago)
+
+
+def _parse_iso(value: str) -> datetime | None:
+    """Parse an engine ISO-8601 timestamp, tolerating a trailing ``Z``."""
+    try:
+        # datetime.fromisoformat handles "+00:00" and fractional seconds; map a
+        # trailing Z (some engine surfaces emit it) to the offset form first.
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except (ValueError, AttributeError):
+        return None
+
+
+def truncate_to_budget(content: str, token_budget: int) -> tuple[str, bool]:
+    """Rule-aware truncation to ``token_budget`` tokens.
+
+    Returns ``(text, truncated)``. Prefers WHOLE markdown sections (a section
+    starts at a line beginning with ``#``): accumulates sections while they fit,
+    drops trailing sections that don't, and signals ``truncated=True`` so the
+    caller can append :data:`TRUNCATION_MARKER`. If the very first section
+    already exceeds the budget, hard-cuts at a whitespace boundary (never
+    mid-word) rather than emitting nothing.
+
+    Never returns more than the budget; an empty/whitespace input returns
+    ``("", False)``.
+    """
+    content = (content or "").strip()
+    if not content:
+        return ("", False)
+    if estimate_tokens(content) <= token_budget:
+        return (content, False)
+
+    sections = _split_sections(content)
+    kept: list[str] = []
+    used = 0
+    for sec in sections:
+        sec_tokens = estimate_tokens(sec)
+        # +1 token slack for the join newline between kept sections.
+        if kept and used + sec_tokens + 1 > token_budget:
+            break
+        if not kept and sec_tokens > token_budget:
+            # First section alone overflows — hard-cut on a word boundary.
+            return (_hard_cut(sec, token_budget), True)
+        kept.append(sec)
+        used += sec_tokens + (1 if len(kept) > 1 else 0)
+
+    if not kept:
+        return (_hard_cut(sections[0], token_budget), True)
+    return ("\n".join(kept).strip(), True)
+
+
+def _split_sections(content: str) -> list[str]:
+    """Split markdown into whole sections at lines beginning with ``#``.
+
+    Leading preamble before the first header is its own section. A document
+    with no headers is a single section (the hard-cut path handles overflow).
+    """
+    lines = content.split("\n")
+    sections: list[str] = []
+    cur: list[str] = []
+    for line in lines:
+        if line.startswith("#") and cur:
+            sections.append("\n".join(cur))
+            cur = [line]
+        else:
+            cur.append(line)
+    if cur:
+        sections.append("\n".join(cur))
+    return sections
+
+
+def _hard_cut(text: str, token_budget: int) -> str:
+    """Cut ``text`` to fit ``token_budget`` at a whitespace boundary."""
+    char_budget = max(0, token_budget * CHARS_PER_TOKEN)
+    if len(text) <= char_budget:
+        return text.strip()
+    cut = text[:char_budget]
+    # Back up to the last whitespace so we never slice a word in half.
+    ws = cut.rfind(" ")
+    nl = cut.rfind("\n")
+    boundary = max(ws, nl)
+    if boundary > 0:
+        cut = cut[:boundary]
+    return cut.strip()
+
+
+def stale_prefix(hours_ago: float | None) -> str:
+    """One-line visible staleness prefix (carve §5). Never presents stale as fresh."""
+    if hours_ago is None:
+        return "(orientation staleness unknown — may be stale)"
+    return f"(orientation last refreshed {int(round(hours_ago))}h ago — may be stale)"
+
+
+def cold_notice() -> str:
+    """One-line cold notice (carve §3-4): no usable model, boot un-blocked.
+
+    Visible by design — a missing/degraded briefing degrades to a NOTICE the
+    model can see, never a silently memoryless boot.
+    """
+    return (
+        f"{_OPEN_TAG}\n"
+        "orientation model not yet built or refreshed — booting without a "
+        "briefing (a background refresh has been requested)\n"
+        f"{_CLOSE_TAG}"
+    )
+
+
+def render_orientation(
+    content: str,
+    staleness: str,
+    hours_ago: float | None,
+) -> str:
+    """Render the injected `additionalContext` for a usable model.
+
+    Applies the stale prefix when warranted, truncates the CONTENT to
+    :data:`ORIENTATION_CONTENT_TOKEN_BUDGET` (rule-aware), wraps in the tiny
+    framing tags, and guarantees the WHOLE rendered block (prefix + framing +
+    content) stays within :data:`ORIENTATION_TOTAL_TOKEN_CAP` — if the prefix
+    pushes it over, the content budget is trimmed further so the cap holds.
+
+    Callers pass only ``fresh`` or ``stale`` here; ``degraded``/``unknown`` go
+    to :func:`cold_notice` in the hook (never rendered as fresh).
+    """
+    prefix = stale_prefix(hours_ago) if staleness == "stale" else ""
+    # Reserve budget for the framing tags + prefix so the TOTAL stays under the
+    # hard cap, not just the content.
+    framing_tokens = estimate_tokens(_OPEN_TAG) + estimate_tokens(_CLOSE_TAG) + 2
+    prefix_tokens = estimate_tokens(prefix) + (1 if prefix else 0)
+    content_budget = min(
+        ORIENTATION_CONTENT_TOKEN_BUDGET,
+        ORIENTATION_TOTAL_TOKEN_CAP - framing_tokens - prefix_tokens,
+    )
+    body, truncated = truncate_to_budget(content, content_budget)
+    if truncated:
+        body = f"{body}\n\n{TRUNCATION_MARKER}"
+
+    parts = [_OPEN_TAG]
+    if prefix:
+        parts.append(prefix)
+    parts.append(body)
+    parts.append(_CLOSE_TAG)
+    return "\n".join(parts)

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

@@ -210,6 +210,35 @@ def read_if_fresh(session_id: str, last_consumed_token: Optional[int]) -> tuple:
     return {"context": payload.get("context", ""), "telemetry": payload.get("telemetry", {})}, token
 
 
+def invalidate(session_id: str) -> None:
+    """Drop any pending prefetch buffer + sentinel for ``session_id``.
+
+    Called at MUTATION sites — a rule/directive retire (``directive_verify``)
+    or a retain (``prefetch.run_prefetch`` before it re-recalls) — so a buffer
+    captured BEFORE the mutation can never be consumed AFTER it. This closes
+    the resurrection class the M3 red-team (R2, BLOCKER) flagged at the
+    M3/M4 intersection: a rule retired mid-session must not re-inject from a
+    buffer prefetched while the rule was still active. It is the read-after-
+    write ordering the producer already builds for the happy path, extended
+    to the mutation path — NOT a reliance on the buffer's TTL (timing, not
+    correctness).
+
+    The SENTINEL is removed FIRST so a partial invalidation still fails
+    closed: ``read_if_fresh`` checks the sentinel before the payload, so once
+    the sentinel is gone the reader returns ``None`` regardless of whether the
+    payload unlink also succeeded — an orphaned payload is never served as
+    fresh. Best-effort and idempotent: a missing file is a no-op, and the
+    function NEVER raises (a failed unlink must not break the turn).
+    """
+    for path in (_sentinel_path(session_id), _buffer_path(session_id)):
+        try:
+            os.remove(path)
+        except FileNotFoundError:
+            pass
+        except OSError:
+            pass
+
+
 def poll_for_sentinel(session_id: str, last_consumed_token: Optional[int], cap_ms: int) -> bool:
     """Clock-bounded poll for a fresh sentinel. Never busy-spins.
 

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

@@ -80,6 +80,16 @@ def run_prefetch(hook_input: dict, config: dict) -> bool:
         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: