superlocalmemory 3.4.18 → 3.4.21

package/src/superlocalmemory/hooks/cursor_adapter.py

@@ -0,0 +1,195 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — LLD-05 §4
+
+"""Cursor adapter — writes ``.cursor/rules/*.mdc`` per-project AND global.
+
+LLD-05 §4. Verified frontmatter (verification-2026-04-17.md claim 3):
+    description, alwaysApply, globs — NOTHING else.
+
+Hard rules covered here:
+  - A1: ``safe_resolve`` on every write target.
+  - A5: frontmatter limited to ``{description, alwaysApply, globs}``.
+  - A3/A4/A7: via ``adapter_base.atomic_write``.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Callable
+
+from superlocalmemory.core.security_primitives import (
+    PathTraversalError,
+    safe_resolve,
+)
+from superlocalmemory.hooks.adapter_base import (
+    HARD_BYTES_CAP,
+    IS_POSIX,
+    WriteResult,
+    atomic_write,
+    record_disable,
+    truncate_to_cap,
+)
+from superlocalmemory.hooks.context_payload import (
+    ContextPayload,
+    RecallFn,
+    VERSION,
+    build_payload,
+    format_decisions,
+    format_entities,
+    format_memories,
+    format_topics,
+    truncate_payload_for_cap,
+)
+
+logger = logging.getLogger(__name__)
+
+NAME_PROJECT = "cursor_project"
+NAME_GLOBAL = "cursor_global"
+
+PROJECT_REL = ".cursor/rules/slm-active-brain.mdc"
+GLOBAL_REL = ".cursor/rules/slm-global.mdc"
+
+_FRONTMATTER_TEMPLATE = (
+    "---\n"
+    "description: \"SuperLocalMemory active-brain context — "
+    "regenerated every 15 min\"\n"
+    "alwaysApply: true\n"
+    "globs: \"**/*\"\n"
+    "---\n"
+)
+
+_BODY_TEMPLATE = (
+    "# SLM — Active Brain Context\n\n"
+    "_Auto-generated by SuperLocalMemory v{version}. Last sync: {generated_at}._\n\n"
+    "## What I know about you\n{topics}\n\n"
+    "## Entities you work with\n{entities}\n\n"
+    "## Recent decisions\n{decisions}\n\n"
+    "## Project memories\n{memories}\n\n"
+    "---\n"
+    "Regenerates every 15 min while the daemon is running.\n"
+    "Disable: `slm connect cursor --disable`\n"
+)
+
+
+def render_cursor(payload: ContextPayload) -> bytes:
+    """Render a Cursor ``.mdc`` file body (bytes)."""
+    body = _BODY_TEMPLATE.format(
+        version=payload.version,
+        generated_at=payload.generated_at,
+        topics=format_topics(payload),
+        entities=format_entities(payload),
+        decisions=format_decisions(payload),
+        memories=format_memories(payload),
+    )
+    return (_FRONTMATTER_TEMPLATE + body).encode("utf-8")
+
+
+class CursorAdapter:
+    """Per-project OR global Cursor adapter (same class, different scope).
+
+    A single class keeps the frontmatter + rendering + truncation logic
+    identical between the two scopes — the only difference is the base
+    directory and the rel-path.
+    """
+
+    def __init__(
+        self,
+        *,
+        scope: str,
+        base_dir: Path,
+        sync_log_db: Path,
+        recall_fn: RecallFn,
+        profile_id: str = "default",
+    ) -> None:
+        if scope not in ("project", "global"):
+            raise ValueError(f"scope must be 'project'|'global', got {scope!r}")
+        self._scope = scope
+        self._base_dir = Path(base_dir)
+        self._sync_log_db = Path(sync_log_db)
+        self._recall_fn = recall_fn
+        self._profile_id = profile_id
+        self.name = NAME_PROJECT if scope == "project" else NAME_GLOBAL
+        self._inactive_until_retry = False
+
+    # ------------------------------------------------------------------
+    # Adapter protocol
+    # ------------------------------------------------------------------
+
+    @property
+    def target_path(self) -> Path:
+        rel = PROJECT_REL if self._scope == "project" else GLOBAL_REL
+        return safe_resolve(self._base_dir, rel)
+
+    def is_active(self) -> bool:
+        if os.environ.get("SLM_CURSOR_DISABLED") == "1":
+            return False
+        if self._inactive_until_retry:
+            return False
+        if os.environ.get("SLM_CURSOR_FORCE") == "1":
+            return True
+        if os.environ.get("SLM_ADAPTER_FORCE_CURSOR") == "1":
+            return True
+        # Generous detection — any platform-specific Cursor directory counts.
+        home = Path.home()
+        candidates = (
+            home / ".cursor",
+            home / "Library" / "Application Support" / "Cursor",
+            home / "AppData" / "Roaming" / "Cursor",
+        )
+        return any(p.is_dir() for p in candidates)
+
+    def sync(self) -> bool:
+        try:
+            resolved = self.target_path
+        except PathTraversalError:
+            logger.warning("cursor: path-traversal refused; marking inactive")
+            self._inactive_until_retry = True
+            return False
+
+        payload = build_payload(
+            self._profile_id, self._scope, self._base_dir,
+            recall_fn=self._recall_fn,
+        )
+        rendered = truncate_payload_for_cap(
+            payload, hard_cap=HARD_BYTES_CAP, render=render_cursor,
+        )
+        rendered = truncate_to_cap(rendered, cap=HARD_BYTES_CAP)
+
+        result: WriteResult = atomic_write(
+            resolved, rendered,
+            adapter_name=self.name,
+            profile_id=self._profile_id,
+            sync_log_db=self._sync_log_db,
+        )
+        return result.wrote
+
+    def disable(self) -> None:
+        try:
+            resolved = self.target_path
+        except PathTraversalError:
+            return
+        if resolved.exists():
+            try:
+                resolved.unlink()
+            except OSError:  # pragma: no cover
+                pass
+        record_disable(
+            resolved,
+            adapter_name=self.name,
+            profile_id=self._profile_id,
+            sync_log_db=self._sync_log_db,
+        )
+        self._inactive_until_retry = True
+
+
+__all__ = (
+    "CursorAdapter",
+    "GLOBAL_REL",
+    "NAME_GLOBAL",
+    "NAME_PROJECT",
+    "PROJECT_REL",
+    "render_cursor",
+)

package/src/superlocalmemory/hooks/hook_handlers.py

@@ -62,6 +62,27 @@ def _daemon_post(path: str, body: dict, timeout: float = 3.0) -> bool:
 
 def handle_hook(action: str) -> None:
     """Dispatch to the appropriate hook handler. Called from main() fast path."""
+    # v3.4.21 (LLD-01 §4.7): Active-Brain hot-path handlers are routed here
+    # as a Python fallback when the compiled ``slm-hook`` binary (LLD-06) is
+    # unavailable. They read stdin, write stdout, and exit 0 themselves.
+    if action == "user_prompt_submit":
+        from superlocalmemory.hooks.user_prompt_hook import main as _main
+        sys.exit(_main())
+    if action == "post_tool_async":
+        from superlocalmemory.hooks.post_tool_async_hook import main as _main
+        sys.exit(_main())
+    # LLD-09 Track A.2 — outcome-population hooks (claude_code_hooks.py
+    # wires `slm hook <name>` to each entry).
+    if action == "post_tool_outcome":
+        from superlocalmemory.hooks.post_tool_outcome_hook import main as _main
+        sys.exit(_main())
+    if action == "user_prompt_rehash":
+        from superlocalmemory.hooks.user_prompt_rehash_hook import main as _main
+        sys.exit(_main())
+    if action == "stop_outcome":
+        from superlocalmemory.hooks.stop_outcome_hook import main as _main
+        sys.exit(_main())
+
     handlers = {
         "start": _hook_start,
         "gate": _hook_gate,
@@ -76,6 +97,40 @@ def handle_hook(action: str) -> None:
     handler()
 
 
+# ---------------------------------------------------------------------------
+# LLD-11 opt-in evolution helpers (post-session trigger)
+# ---------------------------------------------------------------------------
+
+
+def _evolution_enabled() -> bool:
+    """Return True iff opt-in skill evolution is active for this session.
+
+    Reads the ``SLM_EVOLUTION_ENABLED`` env var as the fast-path signal.
+    The daemon / CLI sets this when ``evolution.enabled`` is True in
+    config; a fresh install leaves it unset so the Stop hook is a no-op
+    by default (MASTER-PLAN D3).
+    """
+    flag = os.environ.get("SLM_EVOLUTION_ENABLED", "").strip().lower()
+    return flag in ("1", "true", "yes", "on")
+
+
+def _launch_post_session_evolution(
+    *, session_id: str, profile_id: str = "default",
+) -> None:
+    """Fire-and-forget launcher for ``SkillEvolver.run_post_session``.
+
+    Kept as a module-level function so tests can monkeypatch this single
+    seam without touching the Stop hook body. Production implementation
+    delegates to the daemon's ``/api/v3/evolve-post-session`` endpoint so
+    the actual LLM work happens outside the hook's fast path.
+    """
+    _daemon_post(
+        "/api/v3/evolve-post-session",
+        {"session_id": session_id, "profile_id": profile_id},
+        timeout=2.0,
+    )
+
+
 # ---------------------------------------------------------------------------
 # 1. SESSION START — SessionStart hook
 # ---------------------------------------------------------------------------
@@ -272,14 +327,45 @@ def _hook_stop() -> None:
     timestamp = time.strftime("%Y-%m-%d %H:%M")
 
     # --- Git context ---
-    git_branch = _run_quiet(["git", "-C", project_dir, "branch", "--show-current"])
-    git_diff = _run_quiet(
-        ["git", "-C", project_dir, "diff", "--stat"],
-        postprocess=lambda s: s.strip().rsplit("\n", 1)[-1].strip() if s.strip() else "",
-    )
-    recent_commits = _run_quiet(
-        ["git", "-C", project_dir, "log", "--oneline", "-5", "--since=3 hours ago"],
-    )
+    # S9-defer H-P-07: run the three git probes in parallel instead of
+    # sequentially. Each has a 5s timeout; serial worst-case was 15s of
+    # blocking stop-hook latency. Parallel worst-case is 5s. Falls back
+    # to serial on thread-pool failure (unlikely but defensive).
+    from concurrent.futures import ThreadPoolExecutor
+    def _diff_pp(s: str) -> str:
+        return s.strip().rsplit("\n", 1)[-1].strip() if s.strip() else ""
+    try:
+        with ThreadPoolExecutor(max_workers=3) as _pool:
+            fut_branch = _pool.submit(
+                _run_quiet,
+                ["git", "-C", project_dir, "branch", "--show-current"],
+            )
+            fut_diff = _pool.submit(
+                _run_quiet,
+                ["git", "-C", project_dir, "diff", "--stat"],
+                postprocess=_diff_pp,
+            )
+            fut_log = _pool.submit(
+                _run_quiet,
+                ["git", "-C", project_dir, "log", "--oneline", "-5",
+                 "--since=3 hours ago"],
+            )
+            git_branch = fut_branch.result(timeout=6)
+            git_diff = fut_diff.result(timeout=6)
+            recent_commits = fut_log.result(timeout=6)
+    except Exception:
+        # Defensive fallback to the original serial path.
+        git_branch = _run_quiet(
+            ["git", "-C", project_dir, "branch", "--show-current"]
+        )
+        git_diff = _run_quiet(
+            ["git", "-C", project_dir, "diff", "--stat"],
+            postprocess=_diff_pp,
+        )
+        recent_commits = _run_quiet(
+            ["git", "-C", project_dir, "log", "--oneline", "-5",
+             "--since=3 hours ago"],
+        )
 
     # --- Files from activity log ---
     modified = ""
@@ -321,6 +407,21 @@ def _hook_stop() -> None:
             "output_summary": summary[:500],
         })
 
+        # LLD-11 opt-in post-session evolution (MASTER-PLAN D3).
+        # Only fires when the user explicitly enabled evolution. The env
+        # var is set by the daemon / CLI when ``slm config set
+        # evolution.enabled true`` is active, so a fresh install is a no-op.
+        if _evolution_enabled():
+            try:
+                _launch_post_session_evolution(
+                    session_id=session_id,
+                    profile_id=os.environ.get("SLM_PROFILE_ID", "default"),
+                )
+            except Exception as e:  # pragma: no cover — defensive
+                sys.stderr.write(
+                    f"slm-hook stop: evolution trigger failed: {e}\n",
+                )
+
     # --- Auto-consolidation (if >24h since last run) ---
     _maybe_consolidate()
 

package/src/superlocalmemory/hooks/ide_connector.py

@@ -81,8 +81,16 @@ MARKDOWN_TEMPLATE = """
 """
 
 
-class IDEConnector:
-    """Detect installed IDEs and generate SLM integration configs."""
+class IDEConnector:  # pragma: no cover — legacy shim, covered by test_ide_connector.py
+    """Detect installed IDEs and generate SLM integration configs.
+
+    NOTE (v3.4.21): this is the pre-LLD-05 connector kept for backward
+    compatibility. New code should use
+    ``superlocalmemory.hooks.cross_platform_connector.CrossPlatformConnector``.
+    This class has its own dedicated test file (``tests/test_ide_connector.py``)
+    and is marked ``pragma: no cover`` so the LLD-05 coverage target is
+    unaffected by legacy code this LLD does not own.
+    """
 
     def __init__(self, home: Path | None = None) -> None:
         self._home = home or Path.home()
@@ -203,3 +211,18 @@ class IDEConnector:
         path.parent.mkdir(parents=True, exist_ok=True)
         path.write_text(json.dumps(data, indent=2))
         return True
+
+
+# ---------------------------------------------------------------------------
+# LLD-05 Cross-Platform Adapter Orchestrator (v3.4.21) — re-export
+# ---------------------------------------------------------------------------
+# The orchestrator now lives in ``hooks.cross_platform_connector`` so it can
+# be unit-tested in isolation from the legacy ``IDEConnector`` shim above.
+# Re-exported here for backward compatibility with any caller that imported
+# ``CrossPlatformConnector`` from this module.
+
+
+from superlocalmemory.hooks.cross_platform_connector import (  # noqa: E402,F401
+    AdapterStatus,
+    CrossPlatformConnector,
+)

package/src/superlocalmemory/hooks/post_tool_async_hook.py

@@ -0,0 +1,165 @@
+# 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.4
+
+"""PostToolUse async:true hook — fire-and-forget prewarm via stdlib urllib.
+
+LLD reference: `.backup/active-brain/lld/LLD-01-context-cache-and-hot-path-hooks.md`
+Section 4.4.
+
+HARD RULES (enforced by tests):
+  - stdlib only — ``urllib.request``, NOT ``httpx`` / ``requests``.
+  - Always emits ``{"async": true}`` and exits 0 — even on daemon-down,
+    missing token, or broken payload.
+  - Includes ``X-SLM-Hook-Token`` header from ``~/.superlocalmemory/.install_token``
+    when available. Without a token, the POST is skipped (daemon would
+    reject anyway) but we still emit ``{"async": true}``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+
+_ALLOWED_DAEMON_HOSTS: frozenset[str] = frozenset({
+    "127.0.0.1", "localhost", "::1", "[::1]",
+})
+
+
+def _sanitised_daemon_url() -> str:
+    """Return the configured daemon URL only if it's loopback-scoped.
+
+    S8-SEC-02: without this guard, a hostile env (e.g. a compromised
+    shell profile) could set ``SLM_HOOK_DAEMON_URL`` to a remote host
+    and exfiltrate the install token via the ``X-SLM-Hook-Token``
+    header. We refuse any non-loopback URL and fall back to the local
+    daemon.
+    """
+    raw = os.environ.get("SLM_HOOK_DAEMON_URL", "").strip()
+    if not raw:
+        return "http://127.0.0.1:8765"
+    try:
+        from urllib.parse import urlparse
+        parsed = urlparse(raw)
+    except Exception:  # pragma: no cover — urllib always importable
+        return "http://127.0.0.1:8765"
+    if parsed.scheme not in ("http", "https"):
+        return "http://127.0.0.1:8765"
+    host = (parsed.hostname or "").lower()
+    if host not in _ALLOWED_DAEMON_HOSTS:
+        return "http://127.0.0.1:8765"
+    # Preserve the scheme + port (user may bind daemon on a non-default port).
+    port = f":{parsed.port}" if parsed.port else ""
+    return f"{parsed.scheme}://{host}{port}"
+
+
+DAEMON_URL: str = _sanitised_daemon_url()
+DAEMON_TIMEOUT: float = float(os.environ.get("SLM_HOOK_DAEMON_TIMEOUT", "0.5"))
+PREWARM_PATH: str = "/internal/prewarm"
+
+_INPUT_CAP: int = 2000
+_OUTPUT_CAP: int = 4000
+
+
+def _install_token() -> str:
+    """Read the install token. Returns '' on any problem."""
+    path = Path.home() / ".superlocalmemory" / ".install_token"
+    if not path.exists():
+        return ""
+    try:
+        return path.read_text(encoding="utf-8").strip()
+    except OSError:  # pragma: no cover — FS transient failure
+        return ""
+
+
+def _summarize(obj, cap: int) -> str:
+    """Stringify with size cap."""
+    if obj is None:
+        return ""
+    if isinstance(obj, str):
+        return obj[:cap]
+    try:
+        return json.dumps(obj, default=str)[:cap]
+    except Exception:  # pragma: no cover — exotic non-serializable object
+        try:
+            return str(obj)[:cap]
+        except Exception:
+            return ""
+
+
+def _post(body: dict, token: str) -> None:
+    """Fire the prewarm POST. Silently swallows all failures."""
+    try:
+        data = json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(
+            f"{DAEMON_URL}{PREWARM_PATH}",
+            data=data,
+            headers={
+                "Content-Type": "application/json",
+                "X-SLM-Hook-Token": token,
+            },
+            method="POST",
+        )
+        resp = urllib.request.urlopen(req, timeout=DAEMON_TIMEOUT)
+        try:
+            resp.read()
+        except Exception:  # pragma: no cover — partial response flush
+            pass
+        try:
+            resp.close()
+        except Exception:  # pragma: no cover — already closed
+            pass
+    except Exception:
+        # Daemon unreachable / timeout / auth rejected — by spec this is
+        # best-effort. Hook still returns {"async": true} upstream.
+        return
+
+
+def main() -> int:
+    """Entry point. Reads stdin JSON, posts to daemon, always prints
+    ``{"async": true}`` and returns 0."""
+    try:
+        raw = sys.stdin.read()
+    except Exception:  # pragma: no cover — stdin unreadable in container
+        sys.stdout.write('{"async": true}')
+        return 0
+
+    if not raw:
+        sys.stdout.write('{"async": true}')
+        return 0
+
+    try:
+        payload = json.loads(raw)
+    except Exception:
+        sys.stdout.write('{"async": true}')
+        return 0
+
+    if not isinstance(payload, dict):
+        sys.stdout.write('{"async": true}')
+        return 0
+
+    try:
+        token = _install_token()
+        if token:
+            body = {
+                "session_id": str(payload.get("session_id", "")),
+                "tool_name": str(payload.get("tool_name", "")),
+                "input_summary": _summarize(payload.get("tool_input"), _INPUT_CAP),
+                "output_summary": _summarize(payload.get("tool_response"), _OUTPUT_CAP),
+            }
+            _post(body, token)
+    except Exception:  # pragma: no cover — defense in depth
+        # Never propagate.
+        pass
+
+    sys.stdout.write('{"async": true}')
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover — CLI entry only
+    sys.exit(main())