superlocalmemory 3.4.18 → 3.4.21

package/src/superlocalmemory/hooks/adapter_base.py

@@ -0,0 +1,317 @@
+# 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 §2, §4.4, §9.3
+
+"""Cross-platform adapter base — shared Protocol and atomic write primitive.
+
+LLD reference: ``.backup/active-brain/lld/LLD-05-cross-platform-adapters.md``
+Sections: 2 (component catalog), 4.4 (atomic write), 9.3 (sync log contract).
+
+Every adapter (Cursor, Antigravity, Copilot) implements the ``Adapter``
+Protocol. The shared ``_atomic_write`` primitive enforces the hard-rule
+matrix (A1–A3, A7): ``safe_resolve`` + ``O_NOFOLLOW`` + tempfile +
+``os.replace`` + durable content-hash skip via ``cross_platform_sync_log``.
+
+Hard rules enforced here:
+  - A1: every write goes through ``safe_resolve``; POSIX uses ``O_NOFOLLOW``.
+  - A2: atomic replace via tempfile → ``os.replace``.
+  - A3: durable content-hash skip — previous ``content_sha256`` comes from
+    the DB, so this survives daemon restarts.
+  - A7: sync log records ``target_path_sha256`` (full 64-hex, no truncation)
+    + ``target_basename``; never the raw absolute path string.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import sqlite3
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+HARD_BYTES_CAP = 4096
+COPILOT_SOFT_BYTES = 2048
+TRUNCATION_MARKER = b"\n<!-- truncated -->"
+
+
+# ---------------------------------------------------------------------------
+# Protocol
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class Adapter(Protocol):
+    """Contract every cross-platform adapter implements."""
+
+    name: str
+
+    @property
+    def target_path(self) -> Path: ...
+
+    def is_active(self) -> bool: ...
+
+    def sync(self) -> bool: ...
+
+    def disable(self) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# Sync-log helpers (LLD-07 M004 canonical columns)
+# ---------------------------------------------------------------------------
+
+
+def path_sha256(path: Path) -> str:
+    """SHA-256 of the absolute path string, full 64-hex (never truncated)."""
+    return hashlib.sha256(str(path.resolve() if path.exists()
+                              else path).encode("utf-8")).hexdigest()
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _ensure_memory_log(db_path: Path) -> None:
+    """Lazily create ``cross_platform_sync_log`` if a test-mode memory.db is
+    fresh. Production code goes through the migration runner, but tests can
+    hand us an empty DB; this keeps adapters usable without pre-running
+    migrations."""
+    conn = sqlite3.connect(str(db_path))
+    try:
+        conn.executescript(
+            "CREATE TABLE IF NOT EXISTS cross_platform_sync_log ("
+            " adapter_name TEXT NOT NULL,"
+            " profile_id TEXT NOT NULL,"
+            " target_path_sha256 TEXT NOT NULL,"
+            " target_basename TEXT NOT NULL,"
+            " last_sync_at TEXT NOT NULL,"
+            " bytes_written INTEGER NOT NULL,"
+            " content_sha256 TEXT NOT NULL,"
+            " success INTEGER NOT NULL,"
+            " error_msg TEXT,"
+            " PRIMARY KEY (adapter_name, target_path_sha256));"
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def sync_log_last_content_sha256(
+    db_path: Path, adapter_name: str, target_path_sha256: str,
+) -> str | None:
+    """Read last successful ``content_sha256`` for this (adapter, path)."""
+    if not db_path.exists():
+        return None
+    _ensure_memory_log(db_path)
+    conn = sqlite3.connect(str(db_path))
+    try:
+        row = conn.execute(
+            "SELECT content_sha256, success FROM cross_platform_sync_log "
+            "WHERE adapter_name = ? AND target_path_sha256 = ?",
+            (adapter_name, target_path_sha256),
+        ).fetchone()
+    except sqlite3.Error:
+        return None
+    finally:
+        conn.close()
+    if row is None:
+        return None
+    content_hash, success = row
+    if not success:
+        return None
+    return content_hash
+
+
+def sync_log_record(
+    db_path: Path,
+    *,
+    adapter_name: str,
+    profile_id: str,
+    target_path_sha256: str,
+    target_basename: str,
+    bytes_written: int,
+    content_sha256: str,
+    success: bool,
+    error_msg: str | None = None,
+) -> None:
+    """Upsert the canonical M004 row. Rule A7: hash is full 64 hex, no raw path.
+
+    Raises ``ValueError`` if caller attempts to sneak a raw absolute path into
+    ``target_path_sha256`` (defence in depth for the CI grep guard).
+    """
+    if len(target_path_sha256) != 64:
+        raise ValueError(
+            f"target_path_sha256 must be 64 hex chars, got {len(target_path_sha256)}"
+        )
+    if os.sep in target_path_sha256 or "/" in target_path_sha256:
+        raise ValueError("target_path_sha256 must be a hash, not a raw path")
+    _ensure_memory_log(db_path)
+    conn = sqlite3.connect(str(db_path))
+    try:
+        conn.execute(
+            "INSERT INTO cross_platform_sync_log ("
+            "adapter_name, profile_id, target_path_sha256, target_basename, "
+            "last_sync_at, bytes_written, content_sha256, success, error_msg"
+            ") VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) "
+            "ON CONFLICT(adapter_name, target_path_sha256) DO UPDATE SET "
+            " profile_id = excluded.profile_id,"
+            " target_basename = excluded.target_basename,"
+            " last_sync_at = excluded.last_sync_at,"
+            " bytes_written = excluded.bytes_written,"
+            " content_sha256 = excluded.content_sha256,"
+            " success = excluded.success,"
+            " error_msg = excluded.error_msg",
+            (
+                adapter_name, profile_id, target_path_sha256, target_basename,
+                _now_iso(), bytes_written, content_sha256,
+                1 if success else 0, error_msg,
+            ),
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+# ---------------------------------------------------------------------------
+# Atomic write with durable content-hash skip (A1, A2, A3, A7)
+# ---------------------------------------------------------------------------
+
+
+def _is_posix() -> bool:
+    return os.name == "posix"
+
+
+@dataclass(frozen=True, slots=True)
+class WriteResult:
+    """Outcome of ``atomic_write``."""
+    wrote: bool
+    bytes_written: int
+    content_sha256: str
+
+
+def atomic_write(
+    resolved_path: Path,
+    content: bytes,
+    *,
+    adapter_name: str,
+    profile_id: str,
+    sync_log_db: Path,
+    posix_mode: int = 0o600,
+    windows_mode: int = 0o644,
+) -> WriteResult:
+    """Atomic write with durable content-hash skip.
+
+    ``resolved_path`` MUST already be a ``safe_resolve`` output. Passing a
+    raw user-controlled path bypasses the hard-rule A1 guarantee — adapters
+    are responsible for calling ``safe_resolve`` first (enforced by tests).
+    """
+    new_hash = hashlib.sha256(content).hexdigest()
+    target_sha = path_sha256(resolved_path)
+    prev = sync_log_last_content_sha256(sync_log_db, adapter_name, target_sha)
+
+    if prev == new_hash and resolved_path.exists():
+        # Durable skip — no write, no new sync-log row (the prior row still
+        # reflects on-disk truth).
+        return WriteResult(wrote=False, bytes_written=0, content_sha256=new_hash)
+
+    resolved_path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = resolved_path.with_suffix(resolved_path.suffix + ".slm-tmp")
+
+    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
+    if hasattr(os, "O_NOFOLLOW") and _is_posix():
+        flags |= os.O_NOFOLLOW  # SEC — POSIX refuses symlinks
+
+    mode = posix_mode if _is_posix() else windows_mode
+    fd = os.open(str(tmp), flags, mode)
+    try:
+        os.write(fd, content)
+        try:
+            os.fsync(fd)
+        except OSError:  # pragma: no cover — exotic FS
+            pass
+    finally:
+        os.close(fd)
+    os.replace(tmp, resolved_path)
+
+    if _is_posix():
+        try:
+            os.chmod(resolved_path, posix_mode)
+        except OSError:  # pragma: no cover
+            pass
+
+    sync_log_record(
+        sync_log_db,
+        adapter_name=adapter_name,
+        profile_id=profile_id,
+        target_path_sha256=target_sha,
+        target_basename=resolved_path.name,
+        bytes_written=len(content),
+        content_sha256=new_hash,
+        success=True,
+        error_msg=None,
+    )
+    return WriteResult(wrote=True, bytes_written=len(content),
+                       content_sha256=new_hash)
+
+
+def record_disable(
+    resolved_path: Path,
+    *,
+    adapter_name: str,
+    profile_id: str,
+    sync_log_db: Path,
+) -> None:
+    """Log a disable row (LLD-05 §9.4). File deletion is the caller's job."""
+    target_sha = path_sha256(resolved_path)
+    sync_log_record(
+        sync_log_db,
+        adapter_name=adapter_name,
+        profile_id=profile_id,
+        target_path_sha256=target_sha,
+        target_basename=resolved_path.name,
+        bytes_written=0,
+        content_sha256="0" * 64,
+        success=True,
+        error_msg="disabled_by_user",
+    )
+
+
+def truncate_to_cap(content: bytes, *, cap: int = HARD_BYTES_CAP) -> bytes:
+    """Truncate ``content`` to ``cap`` bytes, appending the marker.
+
+    Adapters call this AFTER domain-level truncation (trim sections) and
+    treat the marker as a last-resort safety net — not the primary cap
+    mechanism. Kept in the base module because all three adapters need it.
+    """
+    if len(content) <= cap:
+        return content
+    marker = TRUNCATION_MARKER
+    # Leave room for the marker in the cap.
+    head = content[: max(0, cap - len(marker))]
+    return head + marker
+
+
+__all__ = (
+    "Adapter",
+    "HARD_BYTES_CAP",
+    "COPILOT_SOFT_BYTES",
+    "TRUNCATION_MARKER",
+    "WriteResult",
+    "atomic_write",
+    "path_sha256",
+    "record_disable",
+    "sync_log_last_content_sha256",
+    "sync_log_record",
+    "truncate_to_cap",
+)
+
+
+# Internal platform flag used by adapters to choose permissions.
+IS_POSIX = _is_posix()

package/src/superlocalmemory/hooks/antigravity_adapter.py

@@ -0,0 +1,192 @@
+# 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 §5
+
+"""Antigravity adapter — writes SKILL.md under singular ``.agent/skills/``.
+
+LLD-05 §5. Verified path (verification-2026-04-17.md claim 4, Google
+Codelabs): workspace = ``.agent/skills/slm-memory-adapter/SKILL.md``,
+global = ``~/.gemini/antigravity/skills/slm-memory/SKILL.md``.
+
+Hard rules covered here:
+  - A1 / A3 / A4 / A7: via ``adapter_base.atomic_write``.
+  - A6: singular ``.agent`` and canonical global path enforced by constants.
+
+CI grep guards (banned substrings in this file and in ``hooks/``) are
+documented in LLD-05 §13 — do not reproduce the literal banned tokens here
+(otherwise a docstring trips the very grep guard that protects the module).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+
+from superlocalmemory.core.security_primitives import (
+    PathTraversalError,
+    safe_resolve,
+)
+from superlocalmemory.hooks.adapter_base import (
+    HARD_BYTES_CAP,
+    WriteResult,
+    atomic_write,
+    record_disable,
+    truncate_to_cap,
+)
+from superlocalmemory.hooks.context_payload import (
+    ContextPayload,
+    RecallFn,
+    build_payload,
+    format_decisions,
+    format_entities,
+    format_memories,
+    format_topics,
+    truncate_payload_for_cap,
+)
+
+logger = logging.getLogger(__name__)
+
+NAME_WORKSPACE = "antigravity_workspace"
+NAME_GLOBAL = "antigravity_global"
+
+# Canonical singular paths (Google Codelabs). Do NOT change to plural.
+# Built from pieces so the CI grep for banned plural forms stays clean.
+_AGENT = ".agent"
+_SKILLS = "skills"
+_WORKSPACE_SKILL_NAME = "slm-memory-adapter"
+_GLOBAL_SKILL_NAME = "slm-memory"
+
+WORKSPACE_REL = f"{_AGENT}/{_SKILLS}/{_WORKSPACE_SKILL_NAME}/SKILL.md"
+GLOBAL_REL = f".gemini/antigravity/{_SKILLS}/{_GLOBAL_SKILL_NAME}/SKILL.md"
+
+_FRONTMATTER = (
+    "---\n"
+    "name: slm-memory-adapter\n"
+    "description: \"Surfaces SuperLocalMemory context "
+    "(topics, entities, decisions) at the start of every "
+    "Antigravity conversation.\"\n"
+    "---\n"
+)
+
+_BODY_TEMPLATE = (
+    "\n# SLM Memory Adapter\n\n"
+    "_Auto-generated by SuperLocalMemory v{version}. Last sync: {generated_at}._\n\n"
+    "## Preferences\n{topics}\n\n"
+    "## Entities\n{entities}\n\n"
+    "## Recent decisions\n{decisions}\n\n"
+    "## Project memories\n{memories}\n"
+)
+
+
+def render_antigravity(payload: ContextPayload) -> 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 + body).encode("utf-8")
+
+
+class AntigravityAdapter:
+    """Workspace OR global Antigravity adapter."""
+
+    def __init__(
+        self,
+        *,
+        scope: str,
+        base_dir: Path,
+        sync_log_db: Path,
+        recall_fn: RecallFn,
+        profile_id: str = "default",
+    ) -> None:
+        if scope not in ("workspace", "global"):
+            raise ValueError(
+                f"scope must be 'workspace'|'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_WORKSPACE if scope == "workspace" else NAME_GLOBAL
+        self._inactive_until_retry = False
+
+    @property
+    def target_path(self) -> Path:
+        rel = WORKSPACE_REL if self._scope == "workspace" else GLOBAL_REL
+        return safe_resolve(self._base_dir, rel)
+
+    def is_active(self) -> bool:
+        if os.environ.get("SLM_ANTIGRAVITY_DISABLED") == "1":
+            return False
+        if self._inactive_until_retry:
+            return False
+        if os.environ.get("SLM_ANTIGRAVITY_FORCE") == "1":
+            return True
+        if os.environ.get("SLM_ADAPTER_FORCE_ANTIGRAVITY") == "1":
+            return True
+        home = Path.home()
+        candidates = (
+            home / ".gemini" / "antigravity",
+            home / "Library" / "Application Support" / "Google" / "Antigravity",
+        )
+        return any(p.is_dir() for p in candidates)
+
+    def sync(self) -> bool:
+        try:
+            resolved = self.target_path
+        except PathTraversalError:
+            logger.warning("antigravity: path-traversal refused")
+            self._inactive_until_retry = True
+            return False
+
+        # For builder purposes, treat workspace scope as project.
+        scope_for_builder = "project" if self._scope == "workspace" else "global"
+        payload = build_payload(
+            self._profile_id, scope_for_builder, self._base_dir,
+            recall_fn=self._recall_fn,
+        )
+        rendered = truncate_payload_for_cap(
+            payload, hard_cap=HARD_BYTES_CAP, render=render_antigravity,
+        )
+        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__ = (
+    "AntigravityAdapter",
+    "GLOBAL_REL",
+    "NAME_GLOBAL",
+    "NAME_WORKSPACE",
+    "WORKSPACE_REL",
+    "render_antigravity",
+)

package/src/superlocalmemory/hooks/claude_code_hooks.py

@@ -112,6 +112,32 @@ def _hook_definitions(include_gate: bool = False) -> dict[str, list]:
                         "timeout": 5000,
                     }
                 ],
+            },
+            # LLD-09 Track A.2 — outcome-population on every tool use.
+            # Matches all host tools (SLM MCP tools are excluded via
+            # matcher negation below; actual filtering happens in the
+            # hook by checking tool_name against SLM's own prefixes).
+            {
+                "matcher": _GATED_TOOLS,
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": _wrap_python_cmd("post_tool_outcome"),
+                        "timeout": 5000,
+                    }
+                ],
+            },
+        ],
+        "UserPromptSubmit": [
+            # LLD-09 Track A.2 — re-query detection.
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": _wrap_python_cmd("user_prompt_rehash"),
+                        "timeout": 5000,
+                    }
+                ]
             }
         ],
         "Stop": [
@@ -121,7 +147,13 @@ def _hook_definitions(include_gate: bool = False) -> dict[str, list]:
                         "type": "command",
                         "command": _wrap_python_cmd("stop"),
                         "timeout": 10000,
-                    }
+                    },
+                    # LLD-09 Track A.2 — finalize pending outcomes at end.
+                    {
+                        "type": "command",
+                        "command": _wrap_python_cmd("stop_outcome"),
+                        "timeout": 10000,
+                    },
                 ]
             }
         ],