superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/mcp/_daemon_proxy.py

@@ -1,203 +0,0 @@
-# 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
-
-"""HTTP proxy that lets MCP processes use the daemon as their worker.
-
-Without this, every MCP process (one per IDE) would spawn its own
-``recall_worker`` subprocess through ``WorkerPool.shared()`` and load
-the ONNX embedder into that subprocess. With N IDEs open the total
-RSS was approximately N x 1.6 GB — the exact failure Path B was built
-to avoid.
-
-With this proxy, the MCP process opens an HTTP connection to the
-single long-lived daemon (already running for dashboard / mesh /
-health) and forwards ``recall`` and ``store`` calls there. Heavy
-engine state exists in exactly one process: the daemon.
-"""
-from __future__ import annotations
-
-import logging
-import urllib.parse
-from typing import Any
-
-logger = logging.getLogger(__name__)
-
-_OPAQUE_UNAVAILABLE = "DAEMON_UNAVAILABLE: owned daemon is unavailable; retry later."
-
-
-def daemon_unavailable_error() -> str:
-    """Return a one-line, *diagnosed* daemon-unavailable message.
-
-    The opaque wording this replaces described a stopped daemon, a recycled
-    PID, an unreachable port and an identity mismatch identically (issue #104).
-    Diagnosis is best effort: if it fails for any reason the caller still gets
-    the original, retryable message rather than an exception.
-    """
-    try:
-        from superlocalmemory.cli.daemon import describe_daemon_unavailability
-
-        diagnosis = describe_daemon_unavailability()
-        return (
-            f"DAEMON_UNAVAILABLE ({diagnosis['reason']}): "
-            f"{diagnosis['message']} {diagnosis['hint']}"
-        )
-    except Exception:  # noqa: BLE001 - diagnosis must never mask the failure
-        return _OPAQUE_UNAVAILABLE
-
-
-class DaemonPoolProxy:
-    """:class:`WorkerPool`-shaped facade that talks to the daemon over HTTP.
-
-    The shape matches ``WorkerPool.recall`` / ``WorkerPool.store`` so that
-    the existing pool adapter in ``mcp/_pool_adapter.py`` can swap between
-    a local subprocess pool and the daemon proxy without any adapter
-    change. Errors are returned as ``{"ok": False, "error": "..."}``
-    envelopes — the adapter is responsible for surfacing those.
-    """
-
-    def __init__(
-        self,
-        port: int | None,
-        *,
-        timeout_s: float = 30.0,
-        unavailable: bool = False,
-    ) -> None:
-        # v3.4.59: 8s→30s — dense graph recall can exceed the old timeout.
-        self._port = port
-        self._timeout = timeout_s
-        self._unavailable = unavailable
-
-    @staticmethod
-    def _unavailable_response() -> dict[str, Any]:
-        return {
-            "ok": False,
-            "code": "DAEMON_UNAVAILABLE",
-            "retryable": True,
-            "error": daemon_unavailable_error(),
-        }
-
-    def recall(
-        self, query: str, limit: int = 10, session_id: str = "",
-        fast: bool | None = None,
-        include_global: bool | None = None,
-        include_shared: bool | None = None,
-        window: str | None = None,
-        as_of: str | None = None,
-        known_as_of: str | None = None,
-        valid_at: str | None = None,
-        include_unknown: bool = False,
-    ) -> dict[str, Any]:
-        if self._unavailable:
-            return self._unavailable_response()
-        _params: dict[str, Any] = {
-            "q": query,
-            "limit": limit,
-            "session_id": session_id or "",
-        }
-        # v3.8.2 client-driven agentic: only send ``fast`` when the caller set it
-        # explicitly. Unset (None) lets the daemon resolve the configured
-        # client-driven-agentic default — the same way scope flags are handled.
-        if fast is not None:
-            _params["fast"] = "true" if fast else "false"
-        # v3.6.15 multi-scope: only send the scope flags when explicitly set, so
-        # an unset value lets the daemon resolve the configured default (shared
-        # is opt-in). "None" must NOT become the string "none" on the wire.
-        if include_global is not None:
-            _params["include_global"] = "true" if include_global else "false"
-        if include_shared is not None:
-            _params["include_shared"] = "true" if include_shared else "false"
-        if window:
-            _params["window"] = window
-        if as_of:
-            _params["as_of"] = as_of
-        if known_as_of:
-            _params["known_as_of"] = known_as_of
-        if valid_at:
-            _params["valid_at"] = valid_at
-        if include_unknown:
-            _params["include_unknown"] = "true"
-        params = urllib.parse.urlencode(_params)
-        try:
-            from superlocalmemory.cli.daemon import daemon_request
-
-            data = daemon_request(
-                "GET",
-                f"/recall?{params}",
-                timeout_seconds=self._timeout,
-            )
-        except Exception as exc:
-            logger.warning("daemon /recall failed: %s", exc)
-            return self._unavailable_response()
-        if not isinstance(data, dict):
-            return self._unavailable_response()
-        data.setdefault("ok", True)
-        return data
-
-    def store(
-        self, content: str, metadata: dict | None = None,
-    ) -> dict[str, Any]:
-        if self._unavailable:
-            return self._unavailable_response()
-        tags = (metadata or {}).get("tags", "")
-        if isinstance(tags, (list, tuple, set)):
-            tags = ",".join(str(tag) for tag in tags)
-        body = {
-            "content": content,
-            "tags": tags,
-            "metadata": metadata or {},
-            "session_id": (metadata or {}).get("session_id", ""),
-            "idempotency_key": (metadata or {}).get("idempotency_key") or None,
-            "profile_id": (metadata or {}).get("profile_id", ""),
-        }
-        # One identity-aware daemon client owns descriptor validation,
-        # capability delivery, and exact-instance targeting. A raw urllib POST
-        # here previously became unauthenticated when /remember was hardened
-        # and could also attach to a stale/foreign port.
-        try:
-            from superlocalmemory.cli.daemon import DaemonConflict, daemon_request
-        except Exception as exc:
-            logger.warning("daemon client import failed: %s", exc)
-            return self._unavailable_response()
-        try:
-            data = daemon_request(
-                "POST",
-                "/remember",
-                body,
-                preserve_conflict=True,
-            )
-        except DaemonConflict as exc:
-            return {
-                "ok": False,
-                "code": "PROFILE_MISMATCH",
-                "retryable": False,
-                "error": str(exc),
-            }
-        except Exception as exc:
-            logger.warning("daemon /remember failed: %s", exc)
-            return self._unavailable_response()
-        if not isinstance(data, dict):
-            return self._unavailable_response()
-        data.setdefault("ok", True)
-        return data
-
-
-def choose_pool() -> Any:
-    """Return the best available pool for this MCP process.
-
-    The daemon is the sole canonical writer. A bounded daemon auto-start is
-    attempted for first use; if it cannot become healthy, return a facade that
-    reports a retryable ``DAEMON_UNAVAILABLE`` envelope. Never construct a
-    process-local ``WorkerPool`` from an MCP client.
-    """
-    try:
-        from superlocalmemory.cli.daemon import (
-            _get_port,
-            ensure_daemon,
-            is_daemon_running,
-        )
-        if is_daemon_running() or ensure_daemon():
-            return DaemonPoolProxy(port=_get_port())
-    except Exception as exc:
-        logger.warning("daemon probe or bounded start failed: %s", exc)
-    return DaemonPoolProxy(port=None, unavailable=True)

package/src/superlocalmemory/mcp/_pool_adapter.py

@@ -1,181 +0,0 @@
-# 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
-
-"""MCP-side adapters onto the pool (daemon HTTP or local subprocess).
-
-The pool returns plain dicts with an ``ok`` flag. Hooks
-(``AutoRecall`` / ``AutoCapture``) expect a ``RecallResponse``-shaped
-object and a list of fact ids. These adapters bridge the two.
-
-On ``{"ok": False, "error": "..."}`` the adapters raise
-:class:`PoolError` instead of silently returning empty results — worker
-death must be distinguishable from "no memories" on the user side.
-"""
-from __future__ import annotations
-
-import logging
-from dataclasses import dataclass, field
-from typing import Any
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass(frozen=True)
-class PoolFact:
-    fact_id: str = ""
-    content: str = ""
-    memory_id: str = ""
-    created_at: str = ""
-
-
-@dataclass(frozen=True)
-class PoolRecallItem:
-    fact: PoolFact = field(default_factory=PoolFact)
-    score: float = 0.0
-    confidence: float = 0.0
-    relevance_score: float = 0.0
-    ranking_score: float | None = None
-    memory_confidence: float = 0.0
-    rank_position: int = 0
-    trust_score: float = 0.0
-    channel_scores: dict[str, float] = field(default_factory=dict)
-    evidence_chain: list[Any] = field(default_factory=list)
-
-
-@dataclass(frozen=True)
-class PoolRecallResponse:
-    results: list[PoolRecallItem] = field(default_factory=list)
-    query_type: str = ""
-    retrieval_time_ms: float = 0.0
-    channel_weights: dict[str, float] = field(default_factory=dict)
-    total_candidates: int = 0
-    score_contract_version: str = "2"
-    calibration_status: str = "uncalibrated"
-    calibration_id: str | None = None
-    answer_confidence: float | None = None
-    abstained: bool = False
-    abstention_reason: str | None = None
-
-
-class PoolError(RuntimeError):
-    """Raised when the pool returns an error envelope.
-
-    Callers that want the old silent-empty behaviour (e.g. hook paths
-    that must never break the user's session) catch this and log at
-    WARNING. Callers that want to surface the failure (e.g. dashboard
-    resources) let it propagate.
-    """
-
-
-def _pool():
-    """Lazy pool factory — prefers the daemon HTTP proxy.
-
-    Split out so tests can monkey-patch the factory without touching
-    the real ``WorkerPool.shared()`` singleton.
-    """
-    from superlocalmemory.mcp._daemon_proxy import choose_pool
-    return choose_pool()
-
-
-def _unwrap_error(raw: Any, op: str) -> None:
-    """Raise PoolError if the pool returned an ``{"ok": False}`` envelope."""
-    if isinstance(raw, dict) and raw.get("ok") is False:
-        reason = raw.get("error") or "pool returned ok=False"
-        raise PoolError(f"pool.{op} failed: {reason}")
-
-
-def pool_recall(query: str, limit: int = 10, **kwargs: Any) -> PoolRecallResponse:
-    """Call pool.recall and reshape its dict into a typed response.
-
-    Raises :class:`PoolError` on worker death or any non-ok envelope.
-    """
-    # v3.6.15 multi-scope: forward the scope-visibility flags when the caller
-    # set them. ``None`` (the default) is passed through so the daemon/engine
-    # resolves the configured default — shared memory is opt-in, so omitting
-    # them keeps recall scoped to this profile only.
-    _recall_kwargs: dict[str, Any] = {
-        "query": query,
-        "limit": limit,
-        "session_id": str(kwargs.get("session_id") or ""),
-        # v3.8.2 client-driven agentic: pass ``fast`` through unchanged. None
-        # (unset) flows to the daemon/engine which resolves the configured
-        # client-driven-agentic default; an explicit bool always wins.
-        "fast": kwargs.get("fast", None),
-    }
-    if "include_global" in kwargs:
-        _recall_kwargs["include_global"] = kwargs["include_global"]
-    if "include_shared" in kwargs:
-        _recall_kwargs["include_shared"] = kwargs["include_shared"]
-    if kwargs.get("window"):
-        _recall_kwargs["window"] = kwargs["window"]
-    raw = _pool().recall(**_recall_kwargs)
-    _unwrap_error(raw, "recall")
-    items = raw.get("results", []) if isinstance(raw, dict) else []
-    results = [
-        PoolRecallItem(
-            fact=PoolFact(
-                fact_id=item.get("fact_id", ""),
-                content=item.get("content", ""),
-                memory_id=item.get("memory_id", ""),
-                created_at=item.get("created_at", "") or "",
-            ),
-            score=float(item.get("score", 0.0)),
-            confidence=float(item.get("confidence", 0.0)),
-            relevance_score=float(item.get("relevance_score", item.get("score", 0.0))),
-            ranking_score=(
-                float(item["ranking_score"])
-                if item.get("ranking_score") is not None else None
-            ),
-            memory_confidence=float(
-                item.get("memory_confidence", item.get("confidence", 0.0))
-            ),
-            rank_position=int(item.get("rank_position", 0)),
-            trust_score=float(item.get("trust_score", 0.0)),
-            channel_scores=item.get("channel_scores", {}) or {},
-            evidence_chain=list(item.get("evidence_chain", []) or []),
-        )
-        for item in items
-    ]
-    return PoolRecallResponse(
-        results=results,
-        query_type=raw.get("query_type", "") if isinstance(raw, dict) else "",
-        retrieval_time_ms=float(raw.get("retrieval_time_ms", 0.0))
-        if isinstance(raw, dict) else 0.0,
-        channel_weights=raw.get("channel_weights", {})
-        if isinstance(raw, dict) else {},
-        total_candidates=int(raw.get("total_candidates", 0))
-        if isinstance(raw, dict) else 0,
-        score_contract_version=str(raw.get("score_contract_version", "2"))
-        if isinstance(raw, dict) else "2",
-        calibration_status=str(raw.get("calibration_status", "uncalibrated"))
-        if isinstance(raw, dict) else "uncalibrated",
-        calibration_id=raw.get("calibration_id") if isinstance(raw, dict) else None,
-        answer_confidence=raw.get("answer_confidence") if isinstance(raw, dict) else None,
-        abstained=bool(raw.get("abstained", False)) if isinstance(raw, dict) else False,
-        abstention_reason=raw.get("abstention_reason") if isinstance(raw, dict) else None,
-    )
-
-
-def pool_store(content: str, metadata: dict | None = None) -> list[str]:
-    """Call pool.store and return fact id list (or pending tracker).
-
-    v3.4.32: the daemon /remember endpoint is async by default — it
-    returns ``pending_id`` and queues the write. We surface this to
-    callers as ``["pending:<id>"]`` so they have a stable identifier
-    without blocking the remember on the embedder worker.
-
-    Legacy synchronous path (``?wait=true``) still returns real
-    ``fact_ids``. Worker death raises :class:`PoolError`.
-    """
-    raw = _pool().store(content=content, metadata=metadata or {})
-    _unwrap_error(raw, "store")
-    if not isinstance(raw, dict):
-        return []
-    fact_ids = raw.get("fact_ids")
-    if fact_ids:
-        return list(fact_ids)
-    pending_id = raw.get("pending_id")
-    if pending_id is not None:
-        return [f"pending:{pending_id}"]
-    return []

package/src/superlocalmemory/mcp/_stdin_guard.py

@@ -1,60 +0,0 @@
-# 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
-
-"""Pure decision logic for the MCP stdin-EOF self-termination monitor.
-
-Isolated here (no imports, no side effects) so the kqueue ``EV_EOF``
-handling contract is unit-testable without importing the FastMCP server
-module, which starts daemon threads and auto-starts the SLM daemon at
-import time.
-
-Background (v3.6.4 fix)
------------------------
-The stdin-EOF monitor (``superlocalmemory.mcp.server._stdin_eof_monitor``)
-exists to reap orphaned ``slm mcp`` processes when an IDE/agent abandons the
-stdio pipe without quitting. It registers ``EVFILT_READ | EV_EOF`` on stdin
-and terminates the process when the write-end closes.
-
-On macOS, ``EVFILT_READ`` reports ``EV_EOF`` *together with* still-readable
-bytes (``ev.data > 0``) when the write-end is closed while a final request
-is still buffered in the pipe. The original monitor exited on the EOF flag
-alone — dropping that buffered request and tearing down a session that
-still had a pending in-flight call. Under strict MCP hosts whose transport
-half-closes stdin around reconnect/teardown, this surfaced as the server
-self-terminating mid-request, which the host then logged as a keepalive
-failure and respawned (observed against the Hermes agent).
-
-The guard defers termination until the buffer is genuinely drained
-(``ev.data <= 0``), letting the FastMCP reader consume the last request
-first. Genuine disconnects (EOF with an empty buffer) still terminate
-immediately — behaviour identical to before for the common case.
-"""
-
-from __future__ import annotations
-
-__all__ = ["eof_action"]
-
-
-def eof_action(flags: int, data: int, eof_flag: int) -> str:
-    """Decide how the stdin-EOF monitor should react to one kqueue event.
-
-    Args:
-        flags: ``kevent.flags`` bitmask returned by ``kqueue.control``.
-        data: ``kevent.data`` — for ``EVFILT_READ`` this is the number of
-            bytes still readable on the descriptor.
-        eof_flag: the platform ``select.KQ_EV_EOF`` constant (injected so
-            this function stays import-free and trivially testable).
-
-    Returns:
-        - ``"exit"``   — genuine end-of-stream: write-end closed and the
-          buffer is drained (``data <= 0``). Safe to self-terminate.
-        - ``"drain"``  — write-end closed but unread bytes remain
-          (``data > 0``). Must NOT terminate yet; let the reader consume
-          the buffered request first, otherwise it is silently dropped.
-        - ``"ignore"`` — no EOF on this event (ordinary readability or a
-          spurious wake); nothing to do.
-    """
-    if not (flags & eof_flag):
-        return "ignore"
-    return "drain" if data > 0 else "exit"

package/src/superlocalmemory/mcp/agent_context.py

@@ -1,115 +0,0 @@
-"""Per-HTTP-request agent ID resolution — ContextVar home.
-
-Kept in a standalone module so both tools_core and tools_active can import
-it without creating circular dependencies (server.py → tools_core → here,
-and unified_daemon.py → here independently).
-
-Priority chain (HTTP-first, stdio-fallback):
-  1. ContextVar set by _AgentIDExtractorASGI middleware from /mcp/{agent_id} URL path.
-  2. SLM_AGENT_ID environment variable (stdio transport legacy).
-  3. Hard-coded "mcp_client" sentinel.
-"""
-from __future__ import annotations
-
-import contextvars
-import os
-import re
-
-# v3.6.12 (parity-1): default is "" (the "no agent routed" sentinel), NOT the
-# user-visible "mcp_client". Sanitized agent ids are [A-Za-z0-9._-], so "" can
-# never collide — a client that explicitly routes to /mcp/mcp_client is now
-# distinguishable from a bare /mcp/ request with no agent segment.
-_current_agent_id: contextvars.ContextVar[str] = contextvars.ContextVar(
-    "slm_agent_id", default=""
-)
-
-# Agent ids arrive from an untrusted URL path segment. They are ATTRIBUTION
-# metadata, never an authenticated principal — but they reach loggers, the
-# agent registry, and SQL-bound attribution columns, so we hard-restrict the
-# charset at the single extraction chokepoint. This neutralises log-injection
-# (CRLF / ANSI), oversized ids, and any path-ish characters in one place.
-_AGENT_ID_SANITIZE = re.compile(r"[^A-Za-z0-9._-]")
-_AGENT_ID_MAX_LEN = 64
-
-
-def sanitize_agent_id(raw: str) -> str:
-    """Coerce an untrusted agent-id segment to a safe, bounded token."""
-    return _AGENT_ID_SANITIZE.sub("_", raw)[:_AGENT_ID_MAX_LEN]
-
-
-def get_current_agent_id(env_fallback: bool = True) -> str:
-    """Return the agent_id for the current asyncio task.
-
-    For HTTP transport the ASGI wrapper sets the ContextVar from the URL path
-    before the request reaches any MCP tool, so this returns the URL-derived id.
-    For stdio transport the ContextVar holds its default ("mcp_client") and we
-    fall through to the SLM_AGENT_ID env var instead.
-    """
-    ctx_id = _current_agent_id.get()
-    if ctx_id:
-        return ctx_id  # an explicitly-routed agent id (incl. "mcp_client")
-    if env_fallback:
-        return os.environ.get("SLM_AGENT_ID", "mcp_client")
-    return "mcp_client"
-
-
-class AgentIDExtractorASGI:
-    """ASGI wrapper that maps ``/mcp/{agent_id}`` → the agent-id ContextVar.
-
-    Mounted at ``/mcp`` in unified_daemon. IMPORTANT: Starlette's ``Mount``
-    (≥0.35 / 1.x) does NOT strip the mount prefix from ``scope["path"]`` — it
-    records the prefix in ``scope["root_path"]`` and leaves ``path`` as the full
-    request path (e.g. ``/mcp/claude`` with ``root_path == "/mcp"``). So we
-    compute the mount-relative sub-path ourselves as ``path[len(root_path):]``.
-
-    Flow for ``POST /mcp/claude``:
-      sub-path ``/claude`` → agent id ``claude`` → set ContextVar → rewrite the
-      scope path to ``{root_path}/`` so the inner FastMCP app (Starlette, route
-      ``/``) sees the same mount-relative ``/`` it sees for a bare ``/mcp/``.
-
-    Backward compatible: bare ``/mcp/`` has sub-path ``/`` → no agent segment →
-    the request passes through untouched and the ContextVar keeps its
-    ``"mcp_client"`` default.
-
-    Per-request isolation is guaranteed by ContextVar + ``reset(token)`` in a
-    ``finally``, so concurrent HTTP sessions never see each other's agent id.
-    """
-
-    __slots__ = ("_app",)
-
-    def __init__(self, inner) -> None:
-        self._app = inner
-
-    async def __call__(self, scope, receive, send):
-        if scope.get("type") == "http":
-            root_path: str = scope.get("root_path", "")
-            full_path: str = scope.get("path", "/")
-            # Mount-relative sub-path (what comes AFTER /mcp). When a root_path
-            # is present the request path MUST start with it (Starlette Mount
-            # guarantees this); if it somehow does not, treat it as no-agent and
-            # pass through untouched rather than mis-parsing the full path.
-            if root_path:
-                if not full_path.startswith(root_path):
-                    await self._app(scope, receive, send)
-                    return
-                subpath = full_path[len(root_path):]
-            else:
-                subpath = full_path
-            first = subpath.lstrip("/").split("/")[0]
-            if first:
-                first = sanitize_agent_id(first)
-                token = _current_agent_id.set(first)
-                # Rewrite the path so the inner app sees the bare mount root,
-                # exactly as it would for a no-agent /mcp/ request.
-                new_full = (root_path + "/") if root_path else "/"
-                new_scope = {
-                    **scope,
-                    "path": new_full,
-                    "raw_path": new_full.encode(),
-                }
-                try:
-                    await self._app(new_scope, receive, send)
-                finally:
-                    _current_agent_id.reset(token)
-                return
-        await self._app(scope, receive, send)