superlocalmemory 4.1.9 → 4.1.12

package/src/superlocalmemory/integrations/bounded_loops_mcp.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import hashlib
 import json
 import os
 import shutil
@@ -12,7 +13,13 @@ from copy import deepcopy
 from pathlib import Path
 from typing import Any
 
+from superlocalmemory.storage.execution_learning import (
+    VerifiedExecutionEvidence,
+    _seal_verified_execution_evidence,
+)
+
 CONTRACT_ID = "bounded-loops.dev/slm-bridge/v1"
+CONTRACT_V2_ID = "bounded-loops.dev/slm-bridge/v2"
 _OBSERVATION_TIMEOUT_SECONDS = 5.0
 _MAX_MCP_TEXT_BYTES = 2 * 1024 * 1024
 _ADVERTISEMENT = {
@@ -20,6 +27,11 @@ _ADVERTISEMENT = {
     "tool": "bl_graph_evidence",
     "operation": "observe_terminal_run",
 }
+_ADVERTISEMENT_V2 = {
+    "id": CONTRACT_V2_ID,
+    "tool": "bl_graph_execution_evidence",
+    "operation": "observe_verified_terminal_run",
+}
 
 
 class BridgeUnavailable(ValueError):
@@ -36,6 +48,37 @@ def supports_bridge(capabilities: dict[str, Any]) -> bool:
     )
 
 
+def supports_bridge_v2(capabilities: dict[str, Any]) -> bool:
+    """Negotiate the additive v2 capability without altering v1 semantics."""
+    advertised = capabilities.get("evidence_contracts")
+    return isinstance(advertised, list) and any(
+        isinstance(item, dict)
+        and all(item.get(key) == value for key, value in _ADVERTISEMENT_V2.items())
+        for item in advertised
+    )
+
+
+def _bridge_v2_payload(
+    evidence: dict[str, Any], *, profile_id: str, terminal_run: dict[str, Any]
+) -> dict[str, Any]:
+    """Bind v2 evidence to the terminal run independently enumerated this session.
+
+    A v2 producer cannot promote an arbitrary schema-shaped JSON object: the
+    evidence must agree exactly with the separately fetched terminal listing.
+    The resulting payload is sealed below before it can reach storage.
+    """
+    if evidence.get("contract") != CONTRACT_V2_ID:
+        raise BridgeUnavailable("unsupported bounded-loops execution evidence contract")
+    required_listing = ("run_ref", "run_id", "run_state", "terminal_at")
+    if any(not isinstance(terminal_run.get(field), str) for field in required_listing):
+        raise BridgeUnavailable("bounded-loops terminal listing is malformed")
+    if any(evidence.get(field) != terminal_run[field] for field in required_listing):
+        raise BridgeUnavailable("bounded-loops execution evidence does not match terminal listing")
+    payload = deepcopy(evidence)
+    payload["profile_id"] = profile_id
+    return payload
+
+
 def bridge_payload(evidence: dict[str, Any], *, profile_id: str) -> dict[str, Any]:
     """Attach active-profile identity after refusing incompatible evidence."""
     if evidence.get("contract") != CONTRACT_ID:
@@ -96,6 +139,126 @@ async def observe_terminal_runs(
     return observed
 
 
+async def observe_terminal_runs_v2(
+    call_tool: Callable[[str, dict[str, Any]], Awaitable[dict[str, Any]]], *, profile_id: str,
+    producer_identity: str,
+) -> list[VerifiedExecutionEvidence]:
+    """Collect v2 receipts only after verified local producer provenance.
+
+    The producer identity is measured by the stdio launcher, not supplied by
+    producer JSON.  The capability and terminal-listing digests record the
+    exact independently observed control-plane statements that authorized
+    each sealed payload.
+    """
+    if not isinstance(producer_identity, str) or not producer_identity:
+        raise BridgeUnavailable("bounded-loops execution producer identity is unavailable")
+    discovery = await call_tool("bl_capabilities", {})
+    if discovery.get("status") != "ok" or not supports_bridge_v2(discovery.get("capabilities", {})):
+        raise BridgeUnavailable("bounded-loops does not advertise slm-bridge/v2")
+    listing = await call_tool("bl_graph_terminal_runs", {"limit": 100})
+    if (
+        listing.get("status") != "ok"
+        or listing.get("contract") != CONTRACT_ID
+        or not isinstance(listing.get("runs"), list)
+    ):
+        raise BridgeUnavailable("bounded-loops terminal listing is unavailable")
+    capability_digest = _canonical_digest(discovery["capabilities"])
+    listing_digest = _canonical_digest(listing["runs"])
+    observed: list[VerifiedExecutionEvidence] = []
+    for run in listing["runs"][:100]:
+        if not isinstance(run, dict) or any(
+            not isinstance(run.get(field), str)
+            for field in ("run_ref", "run_id", "run_state", "terminal_at")
+        ):
+            raise BridgeUnavailable("bounded-loops terminal listing is malformed")
+        response = await call_tool("bl_graph_execution_evidence", {"run_ref": run["run_ref"]})
+        if response.get("status") == "unavailable":
+            continue
+        if response.get("status") != "ok" or not isinstance(response.get("evidence"), dict):
+            raise BridgeUnavailable("bounded-loops execution evidence response is malformed")
+        payload = _bridge_v2_payload(
+            response["evidence"], profile_id=profile_id, terminal_run=run
+        )
+        try:
+            observed.append(_seal_verified_execution_evidence(
+                payload,
+                producer_identity=producer_identity,
+                capability_digest=capability_digest,
+                terminal_listing_digest=listing_digest,
+            ))
+        except ValueError as exc:
+            raise BridgeUnavailable("bounded-loops execution evidence is invalid") from exc
+    return observed
+
+
+def _canonical_digest(value: Any) -> str:
+    """Stable audit identity for a negotiated MCP control-plane document."""
+    encoded = json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    return "sha256:" + hashlib.sha256(encoded.encode("utf-8")).hexdigest()
+
+
+def _file_digest(path: Path, digest: hashlib._Hash) -> None:
+    """Feed one regular file into an already-bound identity hash."""
+    try:
+        with path.open("rb") as handle:
+            for chunk in iter(lambda: handle.read(64 * 1024), b""):
+                digest.update(chunk)
+    except OSError as exc:
+        raise BridgeUnavailable("bounded-loops producer source could not be identified") from exc
+
+
+def _package_source_identity(executable: Path) -> str:
+    """Digest the bounded_loops source loaded by the MCP launcher's venv.
+
+    The console script is only a shim. Its shebang identifies the interpreter
+    whose site-packages directory owns the running MCP server, so bind the
+    source files from that environment rather than whichever package happens
+    to be importable by SLM itself.
+    """
+    try:
+        first_line = executable.open("rb").readline(4096).decode("utf-8").strip()
+    except (OSError, UnicodeDecodeError) as exc:
+        raise BridgeUnavailable("bounded-loops executable has no readable interpreter") from exc
+    if not first_line.startswith("#!"):
+        raise BridgeUnavailable("bounded-loops executable has no absolute interpreter")
+    interpreter = Path(first_line[2:])
+    if not interpreter.is_absolute() or not interpreter.is_file():
+        raise BridgeUnavailable("bounded-loops executable interpreter is unavailable")
+    if interpreter.parent.name not in {"bin", "Scripts"}:
+        raise BridgeUnavailable("bounded-loops executable is not an isolated environment launcher")
+    environment = interpreter.parent.parent
+    candidates = sorted(
+        candidate.resolve(strict=True)
+        for candidate in (environment / "lib").glob("python*/site-packages/bounded_loops")
+        if candidate.is_dir() and not candidate.is_symlink()
+    )
+    if len(candidates) != 1:
+        raise BridgeUnavailable("bounded-loops package source is unavailable or ambiguous")
+    package = candidates[0]
+    digest = hashlib.sha256()
+    source_files = sorted(
+        path for path in package.rglob("*.py") if path.is_file() and not path.is_symlink()
+    )
+    if not source_files:
+        raise BridgeUnavailable("bounded-loops package source is empty")
+    for path in source_files:
+        digest.update(path.relative_to(package).as_posix().encode("utf-8"))
+        digest.update(b"\0")
+        _file_digest(path, digest)
+        digest.update(b"\0")
+    return "sha256:" + digest.hexdigest()
+
+
+def _producer_identity(executable: Path) -> str:
+    """Bind the trusted launcher and actual bounded_loops package source."""
+    digest = hashlib.sha256()
+    digest.update(b"bounded-loops-launcher\0")
+    _file_digest(executable, digest)
+    digest.update(b"\0bounded-loops-package\0")
+    digest.update(_package_source_identity(executable).encode("ascii"))
+    return "sha256:" + digest.hexdigest()
+
+
 def _assert_trusted_executable(executable: Path) -> None:
     """Raise BridgeUnavailable if executable does not pass the bridge trust checks."""
     try:
@@ -182,6 +345,58 @@ async def observe_from_stdio(*, command: str, cwd: str, profile_id: str) -> list
         raise BridgeUnavailable("bounded-loops observation timed out or could not start") from exc
 
 
+async def observe_v2_from_stdio(
+    *, command: str, cwd: str, profile_id: str
+) -> list[VerifiedExecutionEvidence]:
+    """Use the same trusted stdio boundary for additive v2 evidence."""
+    # Reuse the hardened v1 launcher while selecting only v2 after capability
+    # negotiation.  The injected helper is intentionally local to this call.
+    executable, workspace = Path(command), Path(cwd)
+    if (
+        not executable.is_absolute()
+        or not executable.is_file()
+        or not workspace.is_absolute()
+        or not workspace.is_dir()
+        or workspace.is_symlink()
+    ):
+        raise BridgeUnavailable("bounded-loops bridge requires an approved executable and workspace")
+    try:
+        executable = executable.resolve(strict=True)
+        workspace = workspace.resolve(strict=True)
+    except OSError as exc:
+        raise BridgeUnavailable("bounded-loops bridge path is unavailable") from exc
+    _assert_trusted_executable(executable)
+    producer_identity = _producer_identity(executable)
+    from mcp import ClientSession, StdioServerParameters
+    from mcp.client.stdio import stdio_client
+    try:
+        parameters = StdioServerParameters(command=str(executable), args=[], cwd=str(workspace))
+        async with stdio_client(parameters) as (read, write):
+            async with ClientSession(read, write, read_timeout_seconds=_OBSERVATION_TIMEOUT_SECONDS) as session:
+                await session.initialize()
+                async def call(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+                    result = await session.call_tool(name, arguments)
+                    texts = [item.text for item in result.content if hasattr(item, "text")]
+                    if result.is_error or len(texts) != 1 or len(texts[0].encode("utf-8")) > _MAX_MCP_TEXT_BYTES:
+                        raise BridgeUnavailable("bounded-loops returned an invalid MCP payload")
+                    payload = json.loads(texts[0])
+                    if not isinstance(payload, dict):
+                        raise BridgeUnavailable("bounded-loops returned an invalid MCP payload")
+                    return payload
+                return await asyncio.wait_for(
+                    observe_terminal_runs_v2(
+                        call,
+                        profile_id=profile_id,
+                        producer_identity=producer_identity,
+                    ),
+                    _OBSERVATION_TIMEOUT_SECONDS,
+                )
+    except BridgeUnavailable:
+        raise
+    except Exception as exc:
+        raise BridgeUnavailable("bounded-loops execution observation timed out or could not start") from exc
+
+
 async def observe_installed(*, workspace: str, profile_id: str) -> list[dict[str, Any]]:
     """Observe a user-installed producer without accepting an agent command.
 
@@ -200,3 +415,17 @@ async def observe_installed(*, workspace: str, profile_id: str) -> list[dict[str
     return await observe_from_stdio(
         command=str(Path(command).resolve()), cwd=workspace, profile_id=profile_id
     )
+
+
+async def observe_installed_v2(
+    *, workspace: str, profile_id: str
+) -> list[VerifiedExecutionEvidence]:
+    """Observe only from the installed bounded-loops MCP executable."""
+    command = shutil.which("bounded-loops-mcp")
+    if command is None or not Path(command).is_absolute():
+        raise BridgeUnavailable("bounded-loops-mcp is not installed")
+    executable = Path(command).resolve()
+    if executable.name not in {"bounded-loops-mcp", "bounded-loops-mcp.exe"}:
+        raise BridgeUnavailable("bounded-loops-mcp discovery returned an unsafe executable")
+    return await observe_v2_from_stdio(command=str(executable), cwd=workspace,
+                                       profile_id=profile_id)

package/src/superlocalmemory/learning/database.py

@@ -639,7 +639,8 @@ class LearningDatabase:
                     for row in conn.execute(
                         "SELECT name FROM sqlite_master WHERE type='table' "
                         "AND name IN ('agent_experiences', 'cognitive_turn_receipts', "
-                        "'external_evidence_receipts')"
+                        "'external_evidence_receipts', 'execution_learning_receipts', "
+                        "'execution_learning_events')"
                     )
                 }
                 if profile_id is None:

package/src/superlocalmemory/loops/__init__.py

@@ -21,6 +21,7 @@ from superlocalmemory.loops.ledger import (
     SLMMemoryLedger,
     engine_backed_ledger,
     open_engine_store,
+    pool_backed_ledger,
 )
 from superlocalmemory.loops.models import (
     Bounds,
@@ -49,6 +50,7 @@ __all__ = [
     "InMemoryLedger",
     "SLMMemoryLedger",
     "engine_backed_ledger",
+    "pool_backed_ledger",
     "open_engine_store",
     "no_progress",
     "rung_requires_approval",

package/src/superlocalmemory/loops/ledger.py

@@ -223,6 +223,36 @@ class _EngineLedgerStore:
             self._engine.close()
 
 
+class _PoolLedgerStore(_EngineLedgerStore):
+    """Write through the owned daemon/worker; read through the LIGHT engine.
+
+    MCP intentionally keeps a LIGHT engine in-process.  That engine owns a
+    read-only database view but refuses ``store``/``store_fast``.  The pool is
+    the admitted writer and shares the same canonical store, so loop laps stay
+    immediately queryable without turning every MCP process into a heavy
+    writer.
+    """
+
+    def __init__(self, pool: Any, reader_engine: Any) -> None:
+        super().__init__(reader_engine, owns_engine=False)
+        self._pool = pool
+
+    def add(self, content: str, *, session_id: str, metadata: dict) -> None:
+        result = self._pool.store(
+            content,
+            metadata={
+                **metadata,
+                "session_id": session_id,
+                "profile_id": self._engine.profile_id,
+            },
+        )
+        accepted = bool(result.get("ok") or result.get("success"))
+        if not accepted:
+            raise RuntimeError(
+                result.get("error", "owned SLM writer rejected loop ledger entry")
+            )
+
+
 def engine_backed_ledger(engine: Any) -> SLMMemoryLedger:
     """Build an SLM-backed ledger over an ALREADY-OPEN engine.
 
@@ -236,6 +266,11 @@ def engine_backed_ledger(engine: Any) -> SLMMemoryLedger:
     return SLMMemoryLedger(_EngineLedgerStore(engine, owns_engine=False))
 
 
+def pool_backed_ledger(pool: Any, reader_engine: Any) -> SLMMemoryLedger:
+    """Build an MCP-safe ledger: admitted pool writes, LIGHT engine reads."""
+    return SLMMemoryLedger(_PoolLedgerStore(pool, reader_engine))
+
+
 def open_engine_store(db_path: str | Path) -> _EngineLedgerStore:
     """Build an engine-backed ledger store rooted at ``db_path``.
 

package/src/superlocalmemory/mcp/_daemon_proxy.py

@@ -139,21 +139,40 @@ class DaemonPoolProxy:
     ) -> 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": (metadata or {}).get("tags", ""),
+            "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:
-            # 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.
-            from superlocalmemory.cli.daemon import daemon_request
-
-            data = daemon_request("POST", "/remember", body)
+            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()

package/src/superlocalmemory/mcp/server.py

@@ -280,7 +280,12 @@ register_evolution_tools(_target, get_engine)  # v3.4.11: Skill evolution tools
 from superlocalmemory.mcp.tools_optimize import register_optimize_tools
 register_optimize_tools(_target)  # v3.6.11: Surface B Optimize tools (proxy-free)
 from superlocalmemory.mcp.tools_loops import register_loop_tools
-register_loop_tools(_target, get_engine)  # v3.8.0: bounded-loop tools (CLI+command+MCP)
+from superlocalmemory.mcp._daemon_proxy import choose_pool as _choose_loop_pool
+register_loop_tools(
+    _target,
+    get_engine,
+    _choose_loop_pool,
+)  # v3.8.0: bounded-loop tools (CLI+command+MCP)
 from superlocalmemory.mcp.tools_ops import register_ops_tools
 register_ops_tools(_target, get_engine)  # operational recovery & admin remediation
 from superlocalmemory.mcp.tools_brain import register_brain_tools

package/src/superlocalmemory/mcp/tools_active.py

@@ -318,6 +318,8 @@ def register_active_tools(server, get_engine: Callable) -> None:
         query: str = "",
         max_results: int = 10,
         max_age_days: int = 30,
+        session_id: str = "",
+        agent_id: str = "",
     ) -> dict:
         """Initialize session with relevant memory context.
 
@@ -563,18 +565,24 @@ def register_active_tools(server, get_engine: Callable) -> None:
                 )
                 feedback_count = 0
 
-            # v3.6.9 (#35): generate a stable session_id so clients can pass it
-            # to remember() and close_session() for proper session aggregation.
-            session_id = (
+            # A gateway can serve concurrent host conversations.  An explicit
+            # host id therefore always wins; generating one is retained only
+            # for older clients that cannot supply lifecycle identity.
+            effective_session_id = session_id.strip() or (
                 f"slm-{datetime.datetime.now(datetime.timezone.utc):%Y%m%d}"
                 f"-{uuid.uuid4().hex[:8]}"
             )
+            effective_agent_id = agent_id.strip() or _get_agent_id()
+            # Backward-compatible default for legacy close_session() callers;
+            # native hosts must pass their explicit id when sessions overlap.
+            engine._last_session_id = effective_session_id
 
             _upcoming_events = _upcoming_scheduled_facts(engine, _now)
 
             return {
                 "success": True,
-                "session_id": session_id,
+                "session_id": effective_session_id,
+                "agent_id": effective_agent_id,
                 "context": context,
                 "memories": memories[:max_results],
                 "memory_count": len(memories),
@@ -623,6 +631,7 @@ def register_active_tools(server, get_engine: Callable) -> None:
     async def observe(
         content: str,
         agent_id: str | None = None,
+        session_id: str = "",
     ) -> dict:
         """Observe conversation content for automatic memory capture.
 
@@ -673,11 +682,16 @@ def register_active_tools(server, get_engine: Callable) -> None:
             # Auto-store via engine.
             # pool_store uses blocking urllib (DaemonPoolProxy) — run in
             # thread so the MCP event loop stays unblocked (#34 class).
+            from superlocalmemory.mcp.session_binding import resolve_session_id
+            effective_session_id = resolve_session_id(
+                session_id, agent_id=agent_id, allow_agent_fallback=False,
+            )
             stored = await asyncio.to_thread(
                 auto.capture,
                 content,
                 category=decision.category,
-                metadata={"agent_id": agent_id, "source": "auto-observe"},
+                metadata={"agent_id": agent_id, "session_id": effective_session_id,
+                          "source": "auto-observe"},
             )
 
             if stored:
@@ -693,6 +707,7 @@ def register_active_tools(server, get_engine: Callable) -> None:
                 "category": decision.category,
                 "confidence": round(decision.confidence, 3),
                 "reason": decision.reason,
+                "session_id": effective_session_id,
             }
         except Exception as exc:
             logger.exception("observe failed")

package/src/superlocalmemory/mcp/tools_brain.py

@@ -20,7 +20,15 @@ from superlocalmemory.brain.truth import BrainTruthService
 from superlocalmemory.core.admission import admits
 from superlocalmemory.core.operation_request import OperationKind
 from superlocalmemory.infra.data_root import state_path
-from superlocalmemory.integrations.bounded_loops_mcp import BridgeUnavailable, observe_installed
+from superlocalmemory.integrations.bounded_loops_mcp import (
+    BridgeUnavailable,
+    observe_installed,
+    observe_installed_v2,
+)
+from superlocalmemory.storage.execution_learning import (
+    ExecutionLearningStore,
+    ExecutionLearningValidationError,
+)
 from superlocalmemory.storage.agent_experience import (
     AgentExperienceConflictError,
     AgentExperienceStore,
@@ -51,6 +59,14 @@ def _external_store_for(engine: Any) -> ExternalEvidenceStore:
     )
 
 
+def _execution_store_for(engine: Any) -> ExecutionLearningStore:
+    active_profile = engine.profile_id
+    return ExecutionLearningStore(
+        Path(state_path("learning.db")),
+        is_profile_active=lambda profile_id: profile_id == active_profile,
+    )
+
+
 def _brain_truth_for(engine: Any) -> dict[str, Any]:
     """Read the portable truth snapshot without opening an engine or a writer."""
     return BrainTruthService(
@@ -259,3 +275,24 @@ def register_brain_tools(server: Any, get_engine: Callable[[], Any]) -> None:
             "created": created,
             "control_plane": "observation_only",
         }
+
+    @server.tool()
+    @admits(OperationKind.REMEMBER)
+    async def observe_bounded_loop_execution_learning(workspace: str) -> dict[str, Any]:
+        """Ingest negotiated bridge-v2 terminal evidence into the execution plane.
+
+        The producer is reached only through the installed bounded-loops MCP
+        capability handshake.  This never writes semantic facts or preferences.
+        """
+        engine = get_engine()
+        try:
+            observed = await observe_installed_v2(workspace=workspace, profile_id=engine.profile_id)
+            store = _execution_store_for(engine)
+            created = 0
+            for payload in observed:
+                created += int(await asyncio.to_thread(store.ingest, payload))
+            return {"success": True, "durable": True, "observed": len(observed),
+                    "created": created, "control_plane": "execution_reliability_only"}
+        except (BridgeUnavailable, ExecutionLearningValidationError, ProfileAdmissionError,
+                sqlite3.Error) as exc:
+            return {"success": False, "durable": False, "error": str(exc)}