superlocalmemory 3.4.18 → 3.4.21

package/src/superlocalmemory/hooks/post_tool_outcome_hook.py

@@ -0,0 +1,223 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — Track A.2 (LLD-09 / LLD-00)
+
+"""PostToolUse hook — detect fact usage + write engagement signal.
+
+Flow (hot path, <10 ms typical, <20 ms hard):
+  1. Read Claude Code JSON from stdin.
+  2. Resolve session_id via ``safe_resolve_identifier`` (LLD-00 §4).
+  3. Cap tool_response to 100 KB (bounded scan, LLD-09 §7 failure-mode #4).
+  4. Extract HMAC markers (``slm:fact:<id>:<hmac8>``) — validate each
+     (LLD-00 §3). Bare substring scans are **banned** by the Stage-5b
+     CI gate.
+  5. For each validated fact_id, find a pending_outcomes row where
+     ``session_id`` matches AND ``fact_ids_json`` includes the fact_id
+     AND ``status='pending'`` — call ``register_signal(outcome_id,
+     signal_name, True)``. ``signal_name`` is ``'edit'`` for
+     mutating tools (Edit/Write/NotebookEdit), else ``'dwell_ms'`` with
+     a nominal 3000 ms value.
+  6. Always emit ``{}`` on stdout and return 0. NEVER raise.
+
+Crash-safety (LLD-09 §6):
+  - Outer try/except around every code path. stderr breadcrumb (no
+    stack trace, no payload echo). Always exit 0.
+  - SQLite ``busy_timeout=50`` → fast-fail on DB contention.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+import time
+from pathlib import Path
+
+from superlocalmemory.hooks._outcome_common import (
+    emit_empty_json,
+    log_perf,
+    memory_db_path as _memory_db_path_fn,
+    now_ms,
+    open_memory_db,
+    read_stdin_json,
+    session_state_file,
+    summarize_response,
+)
+
+
+_HOOK_NAME = "post_tool_outcome"
+
+# Monkey-patchable indirection for tests.
+def _memory_db_path() -> Path:
+    return _memory_db_path_fn()
+
+
+# Tools that imply an "edit" signal (the agent acted on the fact).
+_EDIT_TOOLS = frozenset({"Edit", "Write", "NotebookEdit"})
+
+# Nominal dwell value for non-edit tool uses that hit a marker.
+# The label formula clamps 2s..10s → 0.05..0.15 reward bonus.
+_DEFAULT_DWELL_MS = 3000
+
+# Marker regex — mirrors recall_pipeline._emit_marker but scoped locally
+# so this module has no hot-path import of the full recall pipeline.
+#
+# S-L04 — ``fact_id`` is constrained to a conservative alphabet
+# (alphanumerics, ``-`` and ``_``). The previous ``[^:\s]+`` allowed
+# colons and let a malicious tool response emit markers like
+# ``slm:fact:evil:deadbeef:abcdef01`` that the regex grouped wrong and
+# still handed off to the validator. Defence-in-depth: the HMAC
+# validator already rejects these, but disallowing colons keeps garbage
+# from reaching it in the first place. The HMAC suffix stays lowercase
+# hex (matches ``recall_pipeline._emit_marker``).
+_MARKER_RE = re.compile(r"slm:fact:([A-Za-z0-9_\-]+):([0-9a-f]{8})")
+
+
+def _validate(marker: str) -> str | None:
+    """Delegate to the canonical validator (LLD-00 §3)."""
+    try:
+        from superlocalmemory.core.recall_pipeline import _validate_marker
+    except Exception:
+        return None
+    try:
+        return _validate_marker(marker)
+    except Exception:
+        return None
+
+
+def _inner_main() -> str:
+    """Return an ``outcome`` string (for perf log); never raises."""
+    payload = read_stdin_json()
+    if payload is None:
+        return "invalid_payload"
+
+    session_id = payload.get("session_id")
+    tool_name = payload.get("tool_name") or ""
+    if not isinstance(session_id, str) or not session_id:
+        return "no_session"
+
+    # S9-DASH-10: keep registry fresh on every PostToolUse so the MCP
+    # server can pick up the current session even mid-turn.
+    try:
+        from superlocalmemory.hooks.session_registry import mark_active
+        mark_active(session_id, agent_type="claude")
+    except Exception:
+        pass
+
+    # Path-escape defence (SEC-C-02) — any unsafe session_id means we
+    # must not touch the filesystem for this invocation. We still want
+    # to safely query the DB (it uses parameterised SQL), so we only
+    # gate the filesystem branch.
+    _ = session_state_file(session_id)  # None → caller skips FS writes
+    # Note: for post_tool_outcome we do NOT need to write session state.
+    # Rehash / stop hooks are the writers/readers.
+
+    # Response scan — capped BEFORE regex (bound O(cap)).
+    response_text = summarize_response(payload.get("tool_response"))
+    if not response_text:
+        return "no_response"
+
+    # Fast pre-check: if the HMAC prefix is absent, no marker can exist.
+    if "slm:fact:" not in response_text:
+        return "no_marker"
+
+    # S9-W2 M-SEC-03: cap marker iteration to prevent adversarial
+    # response_text floods. 5,000 crafted markers × ~5 μs HMAC = 25 ms
+    # of CPU inside a 20 ms hook budget — enough to cascade budget
+    # misses. LLD-09 says ≤10 facts per recall; 100 is ample headroom.
+    _MAX_MARKERS = 100
+    hits: list[str] = []
+    for m in _MARKER_RE.finditer(response_text):
+        if len(hits) >= _MAX_MARKERS:
+            break
+        marker = m.group(0)
+        fact_id = _validate(marker)
+        if fact_id:
+            hits.append(fact_id)
+    if not hits:
+        return "no_validated_marker"
+
+    # Persist signals via the canonical reward model — the DB write is
+    # behind ``register_signal`` which enforces the schema contract and
+    # the pending→settled state machine.
+    try:
+        from superlocalmemory.learning.reward import EngagementRewardModel
+    except Exception:
+        return "import_fail"
+
+    signal_name = "edit" if tool_name in _EDIT_TOOLS else "dwell_ms"
+    signal_value: object = True if signal_name == "edit" else _DEFAULT_DWELL_MS
+
+    # S9-W3 C6: single connection for BOTH the pending-row match AND
+    # the signal writes. Previously the hook opened ``open_memory_db()``
+    # for the SELECT, closed it, then constructed EngagementRewardModel
+    # which cached its own writer — two connects per invocation × 1-4 ms
+    # each × FileVault contention = blown 20 ms hook budget.
+    #
+    # H-SKEP-03 / H-ARC-H4: pending-row window raised back to 50
+    # (SEC-M2 had tightened it to 5 which silently dropped signals on
+    # heavy Claude Code sessions). Outer cap on returned outcome_ids
+    # caps UPDATE amplification at PENDING_WRITE_CAP × 10 by default.
+    try:
+        model = EngagementRewardModel(_memory_db_path())
+    except Exception:
+        return "model_init_fail"
+
+    try:
+        target_outcome_ids = model.match_pending_for_fact_ids(
+            session_id=session_id, fact_ids=hits,
+        )
+        if not target_outcome_ids:
+            # Distinguish "no pending rows exist" from "rows exist but
+            # none matched" for perf-log observability.
+            with model._lock:
+                conn = model._get_conn()
+                has_pending = conn.execute(
+                    "SELECT 1 FROM pending_outcomes "
+                    "WHERE session_id = ? AND status = 'pending' "
+                    "LIMIT 1",
+                    (session_id,),
+                ).fetchone()
+            return "no_match" if has_pending else "no_pending"
+
+        wrote = 0
+        for oid in target_outcome_ids:
+            ok = model.register_signal(
+                outcome_id=oid,
+                signal_name=signal_name,
+                signal_value=signal_value,
+            )
+            if ok:
+                wrote += 1
+        return f"signal_{signal_name}_x{wrote}"
+    finally:
+        try:
+            model.close()
+        except Exception:
+            pass
+
+
+def main() -> int:
+    """Hook entry point — stdin JSON → signals_json update. Always exits 0."""
+    t0 = time.perf_counter()
+    outcome = "exception"
+    try:
+        outcome = _inner_main()
+    except Exception as exc:  # pragma: no cover — defensive
+        try:
+            sys.stderr.write(
+                f"slm-hook {_HOOK_NAME}: {type(exc).__name__}\n"
+            )
+        except Exception:
+            pass
+    finally:
+        duration_ms = (time.perf_counter() - t0) * 1000.0
+        emit_empty_json()
+        try:
+            log_perf(_HOOK_NAME, duration_ms, outcome)
+        except Exception:
+            pass
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover — CLI entry only
+    sys.exit(main())

package/src/superlocalmemory/hooks/prewarm_auth.py

@@ -0,0 +1,170 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — LLD-01 §4.5
+
+"""Authentication primitives for the /internal/prewarm daemon route.
+
+LLD reference: `.backup/active-brain/lld/LLD-01-context-cache-and-hot-path-hooks.md`
+Section 4.5.
+
+Four gates, applied in order, BEFORE any engine work:
+  1. Loopback-only — client address must be 127.0.0.1 / ::1.
+  2. Origin-header CSRF guard — browsers always send Origin on CORS
+     requests; hooks using stdlib urllib do not. Present Origin ⇒ reject.
+  3. Install-token match — X-SLM-Hook-Token constant-time compared to
+     the bytes stored at ``~/.superlocalmemory/.install_token``.
+  4. Body-size cap — requests > ``MAX_BODY_BYTES`` rejected upfront.
+
+Framework-agnostic. The FastAPI route composes these primitives; tests
+exercise them without starting an HTTP server.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Mapping
+
+from superlocalmemory.core.security_primitives import verify_install_token
+
+# Headers we consider equivalent for the install-token lookup. Covers the
+# common normalizations (exact, lowercase, title-case).
+_TOKEN_HEADER_VARIANTS: tuple[str, ...] = (
+    "X-SLM-Hook-Token",
+    "x-slm-hook-token",
+    "X-Slm-Hook-Token",
+)
+
+_ORIGIN_HEADER_VARIANTS: tuple[str, ...] = ("Origin", "origin")
+
+# Loopback addresses accepted by LLD-01. ``localhost`` is NOT included per
+# SEC-01-02 — we want literal IPs only to avoid DNS-based bypass tricks.
+_LOOPBACK_ADDRS: frozenset[str] = frozenset({"127.0.0.1", "::1"})
+
+# Body-size cap: LLD-01 §4.5 step 4 → 8 KB.
+MAX_BODY_BYTES: int = 8 * 1024
+
+
+@dataclass(frozen=True, slots=True)
+class AuthDecision:
+    """Outcome of ``authorize``.
+
+    - ``allowed`` — True when the request passes every gate.
+    - ``status`` — suggested HTTP status when ``allowed`` is False
+      (``200`` otherwise).
+    - ``reason`` — short machine-readable tag. Never echoes secrets.
+    """
+
+    allowed: bool
+    status: int
+    reason: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Gate 1: Loopback-only
+# ---------------------------------------------------------------------------
+
+
+def is_loopback(client_host: str) -> bool:
+    """Return True iff ``client_host`` is an accepted loopback literal."""
+    if not isinstance(client_host, str) or not client_host:
+        return False
+    return client_host in _LOOPBACK_ADDRS
+
+
+# ---------------------------------------------------------------------------
+# Gate 2: Origin CSRF guard
+# ---------------------------------------------------------------------------
+
+
+def is_browser_originated(headers: Mapping[str, str]) -> bool:
+    """True if the request carries a non-empty ``Origin`` header.
+
+    Defensive against accidental case variants. We treat an explicit empty
+    Origin as non-browser per LLD-01 §4.5 — real browsers always send a
+    non-empty origin on cross-origin requests.
+    """
+    if not headers:
+        return False
+    for name in _ORIGIN_HEADER_VARIANTS:
+        val = headers.get(name)
+        if val:
+            return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Gate 3: Install-token
+# ---------------------------------------------------------------------------
+
+
+def _extract_token(headers: Mapping[str, str]) -> str:
+    """Return the presented X-SLM-Hook-Token across casing variants."""
+    if not headers:
+        return ""
+    for name in _TOKEN_HEADER_VARIANTS:
+        val = headers.get(name)
+        if val:
+            return val
+    return ""
+
+
+# ---------------------------------------------------------------------------
+# Gate 4: Body size
+# ---------------------------------------------------------------------------
+
+
+def check_body_size(body: bytes) -> tuple[bool, str]:
+    """Verify request body is within ``MAX_BODY_BYTES``.
+
+    Returns ``(True, "")`` on pass and ``(False, reason)`` on fail.
+    """
+    if not isinstance(body, (bytes, bytearray)):
+        return False, "body must be bytes"
+    if len(body) > MAX_BODY_BYTES:
+        return False, f"body size {len(body)} exceeds {MAX_BODY_BYTES}"
+    return True, ""
+
+
+# ---------------------------------------------------------------------------
+# Composite authorize()
+# ---------------------------------------------------------------------------
+
+
+def authorize(
+    *,
+    client_host: str,
+    headers: Mapping[str, str],
+) -> AuthDecision:
+    """Run gates 1 → 2 → 3 in order and return the first failure.
+
+    Order rationale:
+      - Loopback check runs first so we reject off-host traffic with 403
+        before touching any user-supplied header material.
+      - Origin check runs second to neutralize browser-driven CSRF even
+        when the attacker somehow obtained the install token.
+      - Token check runs last; constant-time compared via
+        ``verify_install_token``.
+    """
+    if not is_loopback(client_host):
+        return AuthDecision(False, 403, "loopback only")
+
+    if is_browser_originated(headers):
+        return AuthDecision(False, 403, "origin header not allowed")
+
+    token = _extract_token(headers)
+    if not token:
+        return AuthDecision(False, 401, "unauthorized: missing token")
+    if not verify_install_token(token):
+        return AuthDecision(False, 401, "unauthorized: token mismatch")
+
+    return AuthDecision(True, 200, "")
+
+
+__all__ = (
+    "AuthDecision",
+    "MAX_BODY_BYTES",
+    "authorize",
+    "check_body_size",
+    "is_browser_originated",
+    "is_loopback",
+)

package/src/superlocalmemory/hooks/session_registry.py

@@ -0,0 +1,186 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — S9-DASH-10
+
+"""Lightweight session registry for cross-process session_id handoff.
+
+**Problem.** Claude Code (and Cursor/Antigravity) invoke two separate
+SLM surfaces per user turn:
+
+1. ``user_prompt_hook`` — receives ``session_id`` via stdin JSON
+   (Claude Code's hook payload). This is the real session id.
+2. MCP ``recall`` tool — invoked by the AI mid-turn. The MCP protocol
+   does NOT thread ``CLAUDE_SESSION_ID`` into tool arguments by
+   default, so the MCP tool cannot see what session it is serving.
+
+Result: ``record_recall`` writes ``pending_outcomes`` with
+``session_id='mcp:mcp_client'`` while the Stop hook queries by the
+real session id — they never match, so cite/edit/dwell signals are
+lost (reaper finalizes everything at neutral 0.5).
+
+**Fix (this module).** A simple file-based registry:
+
+* ``mark_active(session_id, agent_type)`` — called by hooks on every
+  prompt/tool event. Writes ``(session_id, agent_type, ts_ns, pid)``
+  to ``~/.superlocalmemory/.active_sessions.json``.
+* ``most_recent_active(agent_type, within_seconds=60)`` — queries the
+  registry for the most recently seen session of the named agent.
+  MCP uses this as the default when the tool caller omits
+  ``session_id``.
+
+Concurrency: one reader/writer lock (``fcntl.flock``) serialises
+updates. Rollover: entries older than 1 hour are pruned on every
+write. Fail-soft: every error path returns empty or the passed
+default — the learning loop must never crash the hot path.
+
+This is not a perfect correlation channel; two Claude sessions
+typing in the same second can race. For single-user workstations
+(the overwhelming SLM case) it is 99%+ accurate.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+_REGISTRY_FILE = Path.home() / ".superlocalmemory" / ".active_sessions.json"
+_PRUNE_AFTER_SEC = 3600  # 1h — anything older is dead
+
+
+def _now_ns() -> int:
+    return time.time_ns()
+
+
+def _load() -> dict:
+    try:
+        if not _REGISTRY_FILE.exists():
+            return {}
+        return json.loads(_REGISTRY_FILE.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def _save(data: dict) -> None:
+    try:
+        _REGISTRY_FILE.parent.mkdir(parents=True, exist_ok=True)
+        tmp = _REGISTRY_FILE.with_suffix(
+            f".{os.getpid()}.{time.time_ns()}.tmp",
+        )
+        tmp.write_text(json.dumps(data), encoding="utf-8")
+        os.replace(tmp, _REGISTRY_FILE)
+        try:
+            os.chmod(_REGISTRY_FILE, 0o600)
+        except OSError:
+            pass
+    except Exception as exc:  # pragma: no cover — defensive
+        logger.debug("session_registry save failed: %s", exc)
+
+
+def _prune(data: dict) -> dict:
+    cutoff_ns = _now_ns() - (_PRUNE_AFTER_SEC * 1_000_000_000)
+    return {
+        sid: row for sid, row in data.items()
+        if isinstance(row, dict) and int(row.get("ts_ns", 0)) >= cutoff_ns
+    }
+
+
+def mark_active(
+    session_id: str,
+    agent_type: str = "claude",
+) -> None:
+    """Record ``session_id`` keyed by the CALLING process PID.
+
+    Called from UserPromptSubmit + PostToolUse hooks — those hooks run
+    INSIDE the Claude Code / IDE process. So ``os.getpid()`` is the
+    IDE's PID. The MCP server spawned BY that same IDE process has
+    ``os.getppid() == IDE_PID``. Keying by PID means two parallel
+    Claude Code windows never collide — each MCP server reads only
+    its own parent's entry.
+
+    Hot-path safe — returns within <2 ms on a warm cache. Never raises.
+    """
+    if not session_id or not isinstance(session_id, str):
+        return
+    try:
+        data = _load()
+        key = str(os.getpid())  # the IDE / hook process PID
+        data[key] = {
+            "session_id": session_id,
+            "agent_type": agent_type or "unknown",
+            "ts_ns": _now_ns(),
+        }
+        data = _prune(data)
+        _save(data)
+    except Exception as exc:  # pragma: no cover — defensive
+        logger.debug("mark_active failed: %s", exc)
+
+
+def lookup_by_parent(within_seconds: int = 60) -> Optional[str]:
+    """Return the session_id whose registry key == ``os.getppid()``.
+
+    Called from the MCP server process. ``os.getppid()`` is the PID of
+    the IDE that spawned the MCP server — exactly the same PID that
+    the hook used as its key in ``mark_active``. Collision-free across
+    multiple parallel Claude Code / IDE sessions.
+    """
+    try:
+        parent_key = str(os.getppid())
+        data = _load()
+        row = data.get(parent_key)
+        if not isinstance(row, dict):
+            return None
+        ts = int(row.get("ts_ns", 0))
+        if _now_ns() - ts > within_seconds * 1_000_000_000:
+            return None  # stale — IDE likely restarted
+        return row.get("session_id") or None
+    except Exception:
+        return None
+
+
+def most_recent_active(
+    agent_type: Optional[str] = None,
+    within_seconds: int = 60,
+) -> Optional[str]:
+    """Fallback: most-recently-written entry of the given agent_type.
+
+    Used by surfaces that DON'T have a stable parent-PID linkage (e.g.
+    CLI tools invoked ad-hoc). Prefer ``lookup_by_parent`` for MCP.
+    """
+    try:
+        data = _load()
+        if not data:
+            return None
+        cutoff_ns = _now_ns() - (within_seconds * 1_000_000_000)
+        candidates = []
+        for _key, row in data.items():
+            if not isinstance(row, dict):
+                continue
+            ts = int(row.get("ts_ns", 0))
+            if ts < cutoff_ns:
+                continue
+            if agent_type and row.get("agent_type") != agent_type:
+                continue
+            sid = row.get("session_id")
+            if sid:
+                candidates.append((ts, sid))
+        if not candidates:
+            return None
+        candidates.sort(reverse=True)
+        return candidates[0][1]
+    except Exception:
+        return None
+
+
+def _reset_for_testing() -> None:
+    """TEST-ONLY: wipe registry."""
+    try:
+        _REGISTRY_FILE.unlink(missing_ok=True)
+    except Exception:
+        pass