Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
"""Versioned, principal-scoped host cache for remote Skill snapshots."""
from __future__ import annotations
import asyncio
import json
import os
import shutil
import time
import uuid
from collections.abc import AsyncIterator, Awaitable, Callable
from contextlib import asynccontextmanager
from dataclasses import dataclass
from pathlib import Path
from typing import TYPE_CHECKING, Any
from loguru import logger
if TYPE_CHECKING:
from vikingbot.config.schema import Config
_CACHE_FORMAT_VERSION = 1
_CACHE_METADATA = "metadata.json"
_CACHE_SNAPSHOT = "snapshot"
@dataclass(frozen=True)
class RemoteSkillCacheKey:
"""Opaque filesystem-safe identity for one authorized Skill revision."""
scope_digest: str
root_digest: str
revision_digest: str
@dataclass(frozen=True)
class SnapshotBuildResult:
"""Validated size information returned by a cache snapshot builder."""
total_bytes: int
file_count: int
@dataclass(frozen=True)
class CachedSkillSnapshot:
"""One leased immutable host-side Skill snapshot."""
key: RemoteSkillCacheKey
path: Path
hit: bool
total_bytes: int
file_count: int
@dataclass
class _KeyLockState:
"""One keyed lock plus the holders and waiters that still reference it."""
lock: asyncio.Lock
users: int = 0
SnapshotBuilder = Callable[[Path], Awaitable[SnapshotBuildResult]]
class RemoteSkillCacheError(RuntimeError):
"""The host cache is unavailable; callers may fall back to uncached materialization."""
class RemoteSkillSnapshotCache:
"""Retain validated Skill bytes across Agent Turns without exposing them to tools."""
def __init__(self, config: Config):
settings = config.remote_skills
self.root = config.bot_data_path / "remote_skill_cache"
self.idle_ttl_seconds = float(settings.cache_idle_ttl_seconds)
self.max_entries = int(settings.cache_max_entries)
self.max_bytes = int(settings.cache_max_bytes)
self._key_locks: dict[RemoteSkillCacheKey, _KeyLockState] = {}
self._state_lock = asyncio.Lock()
self._prune_lock = asyncio.Lock()
self._active_entries: dict[Path, int] = {}
def entry_path(self, key: RemoteSkillCacheKey) -> Path:
return self.root / key.scope_digest / key.root_digest / key.revision_digest
@asynccontextmanager
async def acquire(
self,
*,
key: RemoteSkillCacheKey,
root_uri: str,
revision: str,
manifest_signature: str,
builder: SnapshotBuilder,
) -> AsyncIterator[CachedSkillSnapshot]:
"""Lease a validated cached snapshot, building it once on a cache miss."""
async with self._key_lock(key):
entry = self.entry_path(key)
await self._lease(entry)
used_successfully = False
try:
metadata = await asyncio.to_thread(
self._load_entry,
entry,
root_uri=root_uri,
revision=revision,
manifest_signature=manifest_signature,
)
hit = metadata is not None
if metadata is None:
if entry.exists():
await asyncio.to_thread(shutil.rmtree, entry, True)
metadata = await self._build_entry(
entry=entry,
root_uri=root_uri,
revision=revision,
manifest_signature=manifest_signature,
builder=builder,
)
yield CachedSkillSnapshot(
key=key,
path=entry / _CACHE_SNAPSHOT,
hit=hit,
total_bytes=int(metadata["total_bytes"]),
file_count=int(metadata["file_count"]),
)
used_successfully = True
finally:
await self._release(entry, touch=used_successfully)
try:
await self.prune()
except Exception as exc:
logger.warning("Failed to prune remote Skill cache {}: {}", self.root, exc)
async def invalidate(self, key: RemoteSkillCacheKey) -> None:
"""Remove a corrupt or otherwise unusable cache entry."""
async with self._key_lock(key):
entry = self.entry_path(key)
async with self._state_lock:
active = self._active_entries.get(entry, 0)
if active:
return
await asyncio.to_thread(shutil.rmtree, entry, True)
@asynccontextmanager
async def _key_lock(self, key: RemoteSkillCacheKey) -> AsyncIterator[None]:
"""Serialize one cache key and discard the lock after its last user exits."""
async with self._state_lock:
state = self._key_locks.get(key)
if state is None:
state = _KeyLockState(lock=asyncio.Lock())
self._key_locks[key] = state
state.users += 1
try:
async with state.lock:
yield
finally:
async with self._state_lock:
state.users -= 1
if state.users == 0 and self._key_locks.get(key) is state:
self._key_locks.pop(key, None)
async def prune(self) -> None:
"""Apply idle-TTL, entry-count, and byte-size eviction to inactive entries."""
async with self._prune_lock:
if not self.root.exists():
return
async with self._state_lock:
active = {path for path, count in self._active_entries.items() if count > 0}
now = time.time()
entries = await asyncio.to_thread(self._scan_entries)
retained: list[tuple[Path, int, float]] = []
for entry, total_bytes, last_access in entries:
if entry not in active and now - last_access >= self.idle_ttl_seconds:
await asyncio.to_thread(shutil.rmtree, entry, True)
continue
retained.append((entry, total_bytes, last_access))
total = sum(item[1] for item in retained)
count = len(retained)
for entry, total_bytes, _last_access in sorted(retained, key=lambda item: item[2]):
if count <= self.max_entries and total <= self.max_bytes:
break
if entry in active:
continue
await asyncio.to_thread(shutil.rmtree, entry, True)
count -= 1
total -= total_bytes
await asyncio.to_thread(self._remove_empty_parents)
async def _build_entry(
self,
*,
entry: Path,
root_uri: str,
revision: str,
manifest_signature: str,
builder: SnapshotBuilder,
) -> dict[str, Any]:
staging = self.root / f".partial-{uuid.uuid4().hex}"
snapshot = staging / _CACHE_SNAPSHOT
try:
await asyncio.to_thread(self._prepare_root)
await asyncio.to_thread(snapshot.mkdir, parents=True, exist_ok=False, mode=0o700)
result = await builder(snapshot)
metadata = {
"format_version": _CACHE_FORMAT_VERSION,
"root_uri": root_uri,
"revision": revision,
"manifest_signature": manifest_signature,
"total_bytes": int(result.total_bytes),
"file_count": int(result.file_count),
"created_at": time.time(),
}
await asyncio.to_thread(self._write_metadata, staging, metadata)
await asyncio.to_thread(self._make_private, staging)
await asyncio.to_thread(entry.parent.mkdir, parents=True, exist_ok=True, mode=0o700)
if entry.exists():
await asyncio.to_thread(shutil.rmtree, entry, True)
await asyncio.to_thread(os.replace, staging, entry)
return metadata
except OSError as exc:
await asyncio.to_thread(shutil.rmtree, staging, True)
raise RemoteSkillCacheError(f"Remote Skill cache is unavailable: {exc}") from exc
except Exception:
await asyncio.to_thread(shutil.rmtree, staging, True)
raise
async def _lease(self, entry: Path) -> None:
async with self._state_lock:
self._active_entries[entry] = self._active_entries.get(entry, 0) + 1
async def _release(self, entry: Path, *, touch: bool) -> None:
metadata = entry / _CACHE_METADATA
if touch and metadata.exists():
try:
await asyncio.to_thread(os.utime, metadata, None)
except OSError:
pass
async with self._state_lock:
remaining = self._active_entries.get(entry, 0) - 1
if remaining > 0:
self._active_entries[entry] = remaining
else:
self._active_entries.pop(entry, None)
def _prepare_root(self) -> None:
self.root.mkdir(parents=True, exist_ok=True, mode=0o700)
try:
self.root.chmod(0o700)
except OSError:
pass
@staticmethod
def _write_metadata(staging: Path, metadata: dict[str, Any]) -> None:
path = staging / _CACHE_METADATA
path.write_text(
json.dumps(metadata, sort_keys=True, separators=(",", ":")),
encoding="utf-8",
)
path.chmod(0o600)
@staticmethod
def _make_private(root: Path) -> None:
for current, directories, files in os.walk(root):
Path(current).chmod(0o700)
for directory in directories:
(Path(current) / directory).chmod(0o700)
for filename in files:
(Path(current) / filename).chmod(0o600)
def _load_entry(
self,
entry: Path,
root_uri: str,
revision: str,
manifest_signature: str,
) -> dict[str, Any] | None:
metadata_path = entry / _CACHE_METADATA
snapshot_path = entry / _CACHE_SNAPSHOT
try:
metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
except (OSError, ValueError, TypeError):
return None
if not isinstance(metadata, dict) or not snapshot_path.is_dir():
return None
expected = {
"format_version": _CACHE_FORMAT_VERSION,
"root_uri": root_uri,
"revision": revision,
"manifest_signature": manifest_signature,
}
if any(metadata.get(key) != value for key, value in expected.items()):
return None
try:
if int(metadata.get("total_bytes", -1)) < 0 or int(metadata.get("file_count", -1)) < 1:
return None
if time.time() - metadata_path.stat().st_mtime >= self.idle_ttl_seconds:
return None
except (OSError, TypeError, ValueError):
return None
return metadata
def _scan_entries(self) -> list[tuple[Path, int, float]]:
entries: list[tuple[Path, int, float]] = []
for metadata_path in self.root.glob(f"*/*/*/{_CACHE_METADATA}"):
entry = metadata_path.parent
try:
metadata = json.loads(metadata_path.read_text(encoding="utf-8"))
total_bytes = int(metadata.get("total_bytes", 0))
last_access = metadata_path.stat().st_mtime
except (OSError, ValueError, TypeError):
shutil.rmtree(entry, ignore_errors=True)
continue
entries.append((entry, max(total_bytes, 0), last_access))
for partial in self.root.glob(".partial-*"):
try:
if time.time() - partial.stat().st_mtime >= self.idle_ttl_seconds:
shutil.rmtree(partial, ignore_errors=True)
except OSError:
pass
return entries
def _remove_empty_parents(self) -> None:
if not self.root.exists():
return
for depth in (3, 2, 1):
pattern = "/".join("*" for _ in range(depth))
for path in self.root.glob(pattern):
if not path.is_dir() or path.name.startswith(".partial-"):
continue
try:
path.rmdir()
except OSError:
pass
try:
next(self.root.iterdir())
except StopIteration:
try:
self.root.rmdir()
except OSError:
pass
except OSError:
logger.debug("Unable to inspect remote Skill cache root {}", self.root)