superlocalmemory 3.7.7 → 3.8.0

package/src/superlocalmemory/mcp/tools_loops.py

@@ -0,0 +1,300 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""SLM v3.8.0 — MCP bounded-loop tools.
+
+Exposes the ``superlocalmemory.loops`` engine over MCP so an agent connected
+via MCP — not only the ``slm loop`` CLI or the ``/slm-loop`` command — can run
+a gated, bounded loop and inspect its durable ledger. Bounded loops therefore
+ship on three surfaces: CLI, plugin command, and MCP.
+
+The loop's one invariant holds identically here: an INDEPENDENT gate decides
+when the loop is done, never the agent's own claim. Over MCP the gate is an SLM
+*recall*: the loop converges the first lap a memory matching ``gate_query``
+becomes retrievable with confidence (the "verification lives in memory" model
+the engine is designed around). That makes ``slm_loop_run`` a safe, shell-free
+multi-agent coordination primitive — one agent waits, under strict bounds, for
+a memory another agent will write into shared SLM.
+
+Three tools:
+  * ``slm_loop_run``     — run one bounded, gate-verified loop to a terminal
+                           outcome. Blocks (polling the gate) until the gate
+                           passes or a bound trips. Every lap is persisted to
+                           SLM memory (tag ``loop:<name>``) and shows on the
+                           dashboard.
+  * ``slm_loop_history`` — list recorded runs for a loop name (read-only).
+  * ``slm_loop_show``    — show every lap of one run (read-only).
+
+Fail-open: every tool body returns a dict; internal errors surface as
+``ok: False`` with a message, never a raised exception.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Any, Callable
+
+from mcp.types import ToolAnnotations
+
+from superlocalmemory.loops import (
+    Bounds,
+    LapResult,
+    Verdict,
+    engine_backed_ledger,
+    run_bounded_loop,
+)
+
+logger = logging.getLogger("slm.mcp.tools_loops")
+
+# ─── Exported tool name list (used by server.py + tests) ─────────────────────
+
+_LOOP_TOOL_NAMES = (
+    "slm_loop_run",
+    "slm_loop_history",
+    "slm_loop_show",
+)
+
+# ─── Hard caps (a loop tool must never hang the daemon or spin unbounded) ────
+
+_MAX_ITERATIONS = 200
+_MAX_WALLCLOCK_S = 120.0
+_MIN_POLL_S = 0.25
+_MAX_NAME_CHARS = 128
+_MAX_QUERY_CHARS = 2000
+
+
+def _top_score(resp: Any) -> float:
+    """Highest result score in a RecallResponse (0.0 when there are none)."""
+    best = 0.0
+    for r in getattr(resp, "results", None) or []:
+        s = getattr(r, "score", None)
+        if s is None:
+            s = getattr(r, "relevance_score", 0.0) or 0.0
+        try:
+            best = max(best, float(s))
+        except (TypeError, ValueError):
+            continue
+    return best
+
+
+def register_loop_tools(server, get_engine: Callable) -> None:
+    """Register the 3 bounded-loop tools on *server*.
+
+    *server* is duck-typed: must support the ``@server.tool()`` decorator.
+    Compatible with FastMCP, _FilteredServer, and the test mock server.
+    """
+
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False))
+    async def slm_loop_run(
+        name: str,
+        gate_query: str,
+        gate_min_score: float = 0.0,
+        max_iterations: int = 20,
+        max_wallclock_s: float = 15.0,
+        poll_interval_s: float = 1.0,
+        max_tokens: int = 0,
+        no_progress_window: int = 0,
+    ) -> dict:
+        """Run one bounded loop that finishes only when an INDEPENDENT gate passes.
+
+        The gate is an SLM recall of ``gate_query``: the loop converges on the
+        first lap that recall returns a confident match scoring at least
+        ``gate_min_score``. The agent cannot end the loop by asserting it is
+        done — only the gate can. The call BLOCKS (polling every
+        ``poll_interval_s``) until the gate passes or a bound trips, then
+        returns the outcome. Every lap is written to SLM memory (tag
+        ``loop:<name>``) and is visible on the dashboard.
+
+        Use it to wait, under strict bounds, for a verification or coordination
+        condition to hold — e.g. for another agent to record a "build passed"
+        memory in shared SLM.
+
+        Args:
+            name: Loop name, also the memory tag. 1–128 chars.
+            gate_query: Recall query the independent gate checks each lap.
+            gate_min_score: Minimum top-result score to pass (0.0 = any
+                confident hit above the evidence floor).
+            max_iterations: Hard cap on laps (1–200).
+            max_wallclock_s: Hard cap on wall-clock seconds (0 disables; capped at 120).
+            poll_interval_s: Seconds to wait between laps (minimum 0.25).
+            max_tokens: Optional token budget (0 disables).
+            no_progress_window: Halt after this many consecutive no-change laps
+                (0 disables). A pure watcher never "changes", so leave at 0
+                unless the runner reports progress.
+        """
+        try:
+            name = (name or "").strip()
+            if not name or len(name) > _MAX_NAME_CHARS:
+                return {"ok": False, "error": f"name must be 1–{_MAX_NAME_CHARS} chars"}
+            gate_query = (gate_query or "").strip()
+            if not gate_query or len(gate_query) > _MAX_QUERY_CHARS:
+                return {
+                    "ok": False,
+                    "error": f"gate_query must be 1–{_MAX_QUERY_CHARS} chars",
+                }
+
+            iters = max(1, min(int(max_iterations), _MAX_ITERATIONS))
+            wall = (
+                min(float(max_wallclock_s), _MAX_WALLCLOCK_S)
+                if max_wallclock_s and float(max_wallclock_s) > 0
+                else None
+            )
+            poll = max(float(poll_interval_s), _MIN_POLL_S)
+            tok = int(max_tokens) if max_tokens and int(max_tokens) > 0 else None
+            # 0 = disabled (a pure watcher never "changes", so no-progress must
+            # be off by default or it would halt before the gate can pass).
+            npw = (
+                int(no_progress_window)
+                if no_progress_window and int(no_progress_window) > 0
+                else 0
+            )
+            min_score = float(gate_min_score)
+
+            engine = get_engine()
+
+            def gate(lap: int) -> Verdict:
+                resp = engine.recall(gate_query, limit=3, fast=True)
+                results = getattr(resp, "results", None) or []
+                floored = bool(getattr(resp, "no_confident_match", False))
+                top = _top_score(resp)
+                passed = bool(results) and not floored and top >= min_score
+                return Verdict(
+                    passed,
+                    f"recall '{gate_query[:48]}': hits={len(results)} "
+                    f"top={top:.3f} floor={floored}",
+                )
+
+            def runner(lap: int) -> LapResult:
+                # Watcher lap: no work of our own. Give the gate condition time
+                # to become true (e.g. another agent writing a memory) between
+                # polls. Bounded by poll interval so the wall-clock / iteration
+                # caps stay meaningful. The first lap checks immediately.
+                if lap > 1:
+                    time.sleep(poll)
+                return LapResult(changed=False, tokens=0)
+
+            ledger = engine_backed_ledger(engine)
+
+            # The loop blocks (sleeps between laps); run it off the event loop.
+            # The engine's per-call WAL connection model makes this thread-safe.
+            outcome = await asyncio.to_thread(
+                run_bounded_loop,
+                name,
+                bounds=Bounds(
+                    max_iterations=iters,
+                    max_tokens=tok,
+                    max_wallclock_s=wall,
+                    no_progress_window=npw,
+                ),
+                runner=runner,
+                gate=gate,
+                ledger=ledger,
+            )
+            laps = await asyncio.to_thread(ledger.laps, outcome.run_id)
+            return {
+                "ok": True,
+                "status": outcome.status.value,
+                "reason": outcome.reason,
+                "passed": bool(outcome.ok),
+                "laps": outcome.laps,
+                "run_id": outcome.run_id,
+                "ledger": [
+                    {
+                        "lap": e.lap,
+                        "decision": e.decision,
+                        "passed": e.passed,
+                        "detail": e.detail,
+                    }
+                    for e in laps
+                ],
+                "note": (
+                    "The gate — an independent SLM recall — decided this "
+                    "outcome; the agent's own done-claim never terminates a loop."
+                ),
+            }
+        except Exception as exc:
+            logger.exception("slm_loop_run failed (fail-open)")
+            return {"ok": False, "error": str(exc)}
+
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
+    async def slm_loop_history(name: str, limit: int = 20) -> dict:
+        """List recorded bounded-loop runs for a loop name, newest laps summarised.
+
+        Reads the durable SLM-backed ledger (the same rows ``slm loop history``
+        and the dashboard show). Read-only.
+
+        Args:
+            name: Loop name to list runs for.
+            limit: Maximum runs to return (1–200).
+        """
+        try:
+            name = (name or "").strip()
+            if not name:
+                return {"ok": False, "error": "name is required"}
+            lim = max(1, min(int(limit), 200))
+            engine = get_engine()
+            ledger = engine_backed_ledger(engine)
+
+            def _collect() -> list[dict]:
+                run_ids = ledger.runs(name)[:lim]
+                rows: list[dict] = []
+                for rid in run_ids:
+                    laps = ledger.laps(rid)
+                    last = laps[-1] if laps else None
+                    rows.append(
+                        {
+                            "run_id": rid,
+                            "laps": len(laps),
+                            "final": last.decision if last else "unknown",
+                            "ts": last.ts if last else "",
+                        }
+                    )
+                return rows
+
+            rows = await asyncio.to_thread(_collect)
+            return {"ok": True, "name": name, "count": len(rows), "runs": rows}
+        except Exception as exc:
+            logger.exception("slm_loop_history failed (fail-open)")
+            return {"ok": False, "error": str(exc)}
+
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
+    async def slm_loop_show(run_id: str, limit: int = 200) -> dict:
+        """Show every lap of one bounded-loop run, in order, from SLM memory.
+
+        Read-only. Each lap carries the gate verdict plus the agent's recorded
+        (advisory, never loop-terminating) done-claim.
+
+        Args:
+            run_id: Run identifier returned by ``slm_loop_run``.
+            limit: Maximum laps to return (1–1000).
+        """
+        try:
+            run_id = (run_id or "").strip()
+            if not run_id:
+                return {"ok": False, "error": "run_id is required"}
+            lim = max(1, min(int(limit), 1000))
+            engine = get_engine()
+            ledger = engine_backed_ledger(engine)
+
+            def _collect() -> list[dict]:
+                return [
+                    {
+                        "lap": e.lap,
+                        "ts": e.ts,
+                        "decision": e.decision,
+                        "passed": e.passed,
+                        "detail": e.detail,
+                        "agent_claimed_done": e.agent_claimed_done,
+                        "tokens": e.budget.get("tokens", 0),
+                    }
+                    for e in ledger.laps(run_id)[:lim]
+                ]
+
+            laps = await asyncio.to_thread(_collect)
+            return {"ok": True, "run_id": run_id, "count": len(laps), "laps": laps}
+        except Exception as exc:
+            logger.exception("slm_loop_show failed (fail-open)")
+            return {"ok": False, "error": str(exc)}

package/src/superlocalmemory/mcp/tools_mesh.py

@@ -28,6 +28,103 @@ from mcp.types import ToolAnnotations
 
 logger = logging.getLogger(__name__)
 
+
+# ---------------------------------------------------------------------------
+# M03: Simple circuit breaker for mesh_send
+# ---------------------------------------------------------------------------
+# Prevents runaway retries (~30s stall) when the daemon is dead.
+# State machine: CLOSED → OPEN (after 3 consecutive failures)
+#               OPEN → HALF_OPEN (after 60s cooldown)
+#               HALF_OPEN → CLOSED (on one successful probe)
+#               HALF_OPEN → OPEN (on probe failure)
+
+_CB_FAILURE_THRESHOLD = 3
+_CB_COOLDOWN_SECONDS = 60
+
+# Client-side mesh message cap (mirrors the broker's MAX_MESSAGE_SIZE).
+MAX_MESSAGE_SIZE = 4096
+
+_CB_STATE_CLOSED = "closed"
+_CB_STATE_OPEN = "open"
+_CB_STATE_HALF_OPEN = "half_open"
+
+
+class _SendCircuitBreaker:
+    """Thread-safe circuit breaker scoped to mesh_send daemon calls."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._state: str = _CB_STATE_CLOSED
+        self._failure_count: int = 0
+        self._opened_at: float = 0.0
+
+    def reset(self) -> None:
+        """Reset to CLOSED; used by tests for isolation."""
+        with self._lock:
+            self._state = _CB_STATE_CLOSED
+            self._failure_count = 0
+            self._opened_at = 0.0
+
+    def is_open(self) -> bool:
+        with self._lock:
+            if self._state == _CB_STATE_OPEN:
+                if time.monotonic() - self._opened_at >= _CB_COOLDOWN_SECONDS:
+                    self._state = _CB_STATE_HALF_OPEN
+                    return False  # allow one probe
+                return True
+            return False
+
+    def allow_request(self) -> bool:
+        """Return True if the call should proceed; False if circuit is OPEN.
+
+        State transitions inside the lock prevent concurrent probe races:
+        - CLOSED → allow
+        - OPEN (cooldown not elapsed) → block
+        - OPEN (cooldown elapsed) → transition to HALF_OPEN, allow one probe,
+          and immediately re-enter OPEN so any concurrent call is blocked until
+          the probe result comes in via record_success / record_failure.
+        - HALF_OPEN → block (probe already dispatched and not yet resolved)
+        """
+        with self._lock:
+            if self._state == _CB_STATE_CLOSED:
+                return True
+            if self._state == _CB_STATE_OPEN:
+                if time.monotonic() - self._opened_at >= _CB_COOLDOWN_SECONDS:
+                    # Grant exactly one probe by briefly entering HALF_OPEN then
+                    # going back to OPEN.  Subsequent callers are blocked until
+                    # record_success or record_failure resolves the probe.
+                    self._state = _CB_STATE_HALF_OPEN
+                    return True
+                return False
+            # HALF_OPEN: probe is in flight — block until resolved
+            return False
+
+    def record_success(self) -> None:
+        with self._lock:
+            self._state = _CB_STATE_CLOSED
+            self._failure_count = 0
+
+    def record_failure(self) -> None:
+        with self._lock:
+            if self._state == _CB_STATE_HALF_OPEN:
+                # Probe failed — reopen immediately
+                self._state = _CB_STATE_OPEN
+                self._opened_at = time.monotonic()
+                return
+            self._failure_count += 1
+            if self._failure_count >= _CB_FAILURE_THRESHOLD:
+                self._state = _CB_STATE_OPEN
+                self._opened_at = time.monotonic()
+                logger.warning(
+                    "mesh_send circuit breaker OPEN after %d consecutive failures; "
+                    "fast-failing for %ds",
+                    self._failure_count,
+                    _CB_COOLDOWN_SECONDS,
+                )
+
+
+_SEND_CIRCUIT = _SendCircuitBreaker()
+
 # Unique peer ID for this MCP server session
 _PEER_ID = str(uuid.uuid4())[:12]
 _SESSION_SUMMARY = ""
@@ -69,7 +166,15 @@ def _ensure_registered() -> None:
         "session_id": os.environ.get("CLAUDE_SESSION_ID", _PEER_ID),
         "summary": _SESSION_SUMMARY or "SLM MCP session",
         "project_path": _PROJECT_PATH,
-        "agent_type": os.environ.get("CLAUDE_AGENT_TYPE", "claude_code"),
+        # Peer identity is the canonical SLM_AGENT_ID (same var memory
+        # attribution uses), so Antigravity/Hermes/Cursor/etc. show as
+        # themselves instead of collapsing to "claude_code". Fall back to the
+        # legacy CLAUDE_AGENT_TYPE, then a generic default.
+        "agent_type": (
+            os.environ.get("SLM_AGENT_ID")
+            or os.environ.get("CLAUDE_AGENT_TYPE")
+            or "claude_code"
+        ),
     })
     if result:
         # v3.6.12 (mesh-1): the broker mints its OWN peer_id (RegisterRequest has
@@ -174,12 +279,34 @@ def register_mesh_tools(server, get_engine: Callable) -> None:
                 - "project:/path/to/dir" (all sessions in that project directory)
             message: The message content (max 4KB — use file paths for large data)
         """
+        # Enforce the documented 4KB notification cap client-side too (the
+        # broker also caps, but fail fast without a round-trip).
+        if len(message.encode("utf-8")) > MAX_MESSAGE_SIZE:
+            return {"ok": False, "error": (
+                f"message too large (max {MAX_MESSAGE_SIZE} bytes) — "
+                "reference a file path instead")}
+        # M03: circuit breaker — fast-fail if daemon is repeatedly unreachable
+        if not _SEND_CIRCUIT.allow_request():
+            return {
+                "ok": False,
+                "error": (
+                    "mesh_send circuit open: daemon unreachable after repeated failures. "
+                    f"Retrying in {_CB_COOLDOWN_SECONDS}s."
+                ),
+            }
+
         await asyncio.to_thread(_ensure_registered)
         result = await asyncio.to_thread(
             _mesh_request, "POST", "/send",
             {"from_peer": _PEER_ID, "to_peer": to, "content": message},
         )
-        return result or {"ok": False, "error": "Failed to send message"}
+        # Circuit tracks daemon-unreachable (None) only — not valid broker errors
+        # like "recipient not found", which are application-level, not failures.
+        if result is None:
+            _SEND_CIRCUIT.record_failure()
+            return {"ok": False, "error": "Failed to send message"}
+        _SEND_CIRCUIT.record_success()
+        return result
 
     @server.tool()
     async def mesh_inbox() -> dict:
@@ -190,9 +317,11 @@ def register_mesh_tools(server, get_engine: Callable) -> None:
         Messages auto-expire after 48 hours.
         """
         await asyncio.to_thread(_ensure_registered)
+        from urllib.parse import quote
         project = _PROJECT_PATH or _detect_project_path()
         messages = await asyncio.to_thread(
-            _mesh_request, "GET", f"/inbox/{_PEER_ID}?project_path={project}",
+            _mesh_request, "GET",
+            f"/inbox/{_PEER_ID}?project_path={quote(project, safe='')}",
         )
         msg_list = (messages or {}).get("messages", [])
         # Auto-mark unread messages as read. v3.6.12 (failopen-2): use .get("id")
@@ -250,9 +379,16 @@ def register_mesh_tools(server, get_engine: Callable) -> None:
         Before editing a shared file, check if another session has it locked.
 
         Args:
-            file_path: Path to the file
+            file_path: Absolute path to the file
             action: "query" (check lock), "acquire" (lock file), "release" (unlock)
         """
+        # Require a non-empty absolute path; a relative/blank path is ambiguous
+        # and lets a caller probe arbitrary strings via the coordination store.
+        if not file_path or not (
+            file_path.startswith("/")
+            or (len(file_path) >= 3 and file_path[1] == ":")
+        ):
+            return {"ok": False, "error": "file_path must be a non-empty absolute path"}
         await asyncio.to_thread(_ensure_registered)
         result = await asyncio.to_thread(
             _mesh_request, "POST", "/lock",

package/src/superlocalmemory/mcp/tools_optimize.py

@@ -170,7 +170,7 @@ def register_optimize_tools(server) -> None:
                     "ok": False, "content": None, "size_bytes": 0,
                     "error": "ccr_id must be a UUID4",
                 }
-            original = CCRStore.get_instance().retrieve(ccr_id)
+            original = CCRStore.get_instance().retrieve(ccr_id, tenant_id=_tenant())
             if original is None:
                 return {
                     "ok": False, "content": None, "size_bytes": 0,
@@ -257,13 +257,16 @@ def register_optimize_tools(server) -> None:
             cache_key = hashlib.sha256(f"mcpkv:{tenant}:{key}".encode()).hexdigest()
             norm_tid = _normalize_tenant_id(tenant)
 
-            blob = CacheDB.get_default().get_value(cache_key, norm_tid)
+            db = CacheDB.get_default()
+            blob = db.get_value(cache_key, norm_tid)
             if blob is None:
                 with _kv_lock:
                     _kv_misses += 1
+                db.kv_counter_incr("kv_misses")  # M2: durable across restarts
                 return {"ok": True, "hit": False, "value": None, "note": None}
             with _kv_lock:
                 _kv_hits += 1
+            db.kv_counter_incr("kv_hits")  # M2: durable across restarts
             return {"ok": True, "hit": True, "value": blob.decode("utf-8"), "note": None}
 
         except Exception as exc:
@@ -277,14 +280,18 @@ def register_optimize_tools(server) -> None:
     async def slm_optimize_stats() -> dict:
         """Return compression and cache statistics.
 
-        Proxy/compress stats are daemon-persisted (accurate across restarts).
-        KV stats are in-module counters for this MCP process session only.
+        Proxy/compress AND KV stats are daemon-persisted (accurate across
+        restarts). KV counters fall back to this session's in-memory tally if
+        the persisted counters can't be read.
         """
         try:
-            snap = CacheDB.get_default().metrics_load()
+            db = CacheDB.get_default()
+            snap = db.metrics_load()
+            # M2: prefer the durable KV counters; fall back to session counters.
+            persisted = db.kv_counters_load()
             with _kv_lock:
-                kv_h = _kv_hits
-                kv_m = _kv_misses
+                kv_h = persisted.get("kv_hits", _kv_hits)
+                kv_m = persisted.get("kv_misses", _kv_misses)
             return {
                 "ok": True,
                 "compress_runs": snap.compress_runs,
@@ -297,7 +304,7 @@ def register_optimize_tools(server) -> None:
                     "CCR entry count not tracked per-session; "
                     "see daemon /api/v1/metrics"
                 ),
-                "note": "proxy stats are daemon-persisted; kv stats are this session only",
+                "note": "proxy and kv stats are daemon-persisted across restarts",
             }
         except Exception as exc:
             logger.error("slm_optimize_stats failed (fail-open): %s", exc)