skillpool 4.3.0__py3-none-any.whl

skillpool/bridge/freeze_detector.py

@@ -0,0 +1,134 @@
+"""SkillPool Freeze Detector — Detect and recover from frozen/stalled operations."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, model_validator
+
+
+class FreezeStatus(str, Enum):
+    """Status of a freeze check."""
+
+    HEALTHY = "healthy"
+    FROZEN = "frozen"
+    STALE = "stale"
+    RECOVERING = "recovering"
+
+
+class FreezeReport(BaseModel):
+    """Report from a freeze detection check."""
+
+    status: FreezeStatus
+    frozen_operations: list[str] = []
+    stale_threshold_seconds: int = 300
+    last_heartbeat: str = ""
+    timestamp: str = ""
+
+    @model_validator(mode="after")
+    def _set_timestamp(self) -> FreezeReport:
+        if not self.timestamp:
+            self.timestamp = datetime.now(timezone.utc).isoformat()
+        return self
+
+
+class FreezeDetector:
+    """Detect and recover from frozen/stalled operations.
+
+    Monitors heartbeat files to detect operations that have stalled
+    beyond a configurable threshold. Provides recovery actions.
+    """
+
+    def __init__(self, state_dir: Path, stale_threshold: int = 300) -> None:
+        self._state_dir = state_dir / "freeze_state"
+        self._heartbeats_dir = self._state_dir / "heartbeats"
+        self._state_dir.mkdir(parents=True, exist_ok=True)
+        self._heartbeats_dir.mkdir(parents=True, exist_ok=True)
+        self._stale_threshold = stale_threshold
+
+    def heartbeat(self, operation_id: str) -> None:
+        """Record a heartbeat for an ongoing operation."""
+        hb_file = self._heartbeats_dir / f"{operation_id}.json"
+        data = {
+            "operation_id": operation_id,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+        }
+        hb_file.write_text(json.dumps(data), encoding="utf-8")
+
+    def complete_operation(self, operation_id: str) -> None:
+        """Mark an operation as completed (remove heartbeat)."""
+        hb_file = self._heartbeats_dir / f"{operation_id}.json"
+        if hb_file.exists():
+            hb_file.unlink()
+
+    def check(self) -> FreezeReport:
+        """Check for frozen/stalled operations."""
+        frozen_ops: list[str] = []
+        now = datetime.now(timezone.utc)
+        last_hb = ""
+
+        for hb_file in self._heartbeats_dir.iterdir():
+            if not hb_file.suffix == ".json":
+                continue
+            try:
+                data = json.loads(hb_file.read_text(encoding="utf-8"))
+                ts_str = data.get("timestamp", "")
+                if ts_str:
+                    last_hb = ts_str
+                    ts = datetime.fromisoformat(ts_str)
+                    age = (now - ts).total_seconds()
+                    if age > self._stale_threshold:
+                        frozen_ops.append(data.get("operation_id", hb_file.stem))
+            except (json.JSONDecodeError, Exception):
+                frozen_ops.append(hb_file.stem)
+
+        if frozen_ops:
+            return FreezeReport(
+                status=FreezeStatus.FROZEN,
+                frozen_operations=frozen_ops,
+                stale_threshold_seconds=self._stale_threshold,
+                last_heartbeat=last_hb,
+            )
+
+        return FreezeReport(
+            status=FreezeStatus.HEALTHY,
+            stale_threshold_seconds=self._stale_threshold,
+            last_heartbeat=last_hb,
+        )
+
+    def recover(self, operation_id: str) -> bool:
+        """Attempt to recover a frozen operation.
+
+        Removes the heartbeat file and returns True if recovery was possible.
+        """
+        hb_file = self._heartbeats_dir / f"{operation_id}.json"
+        if hb_file.exists():
+            hb_file.unlink()
+            return True
+        return False
+
+    def recover_all(self) -> list[str]:
+        """Recover all frozen operations."""
+        recovered: list[str] = []
+        for hb_file in list(self._heartbeats_dir.iterdir()):
+            if hb_file.suffix == ".json":
+                recovered.append(hb_file.stem)
+                hb_file.unlink()
+        return recovered
+
+    def list_active_operations(self) -> list[dict[str, Any]]:
+        """List all active (heartbeat-present) operations."""
+        ops: list[dict[str, Any]] = []
+        for hb_file in self._heartbeats_dir.iterdir():
+            if hb_file.suffix != ".json":
+                continue
+            try:
+                data = json.loads(hb_file.read_text(encoding="utf-8"))
+                ops.append(data)
+            except (json.JSONDecodeError, Exception):
+                ops.append({"operation_id": hb_file.stem, "timestamp": "unknown"})
+        return ops

skillpool/bridge/maintenance.py

@@ -0,0 +1,119 @@
+"""SkillPool Maintenance Cron — Periodic maintenance tasks for registry health."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+from .freeze_detector import FreezeDetector
+from .wal_manager import WALManager
+
+
+class MaintenanceResult(BaseModel):
+    """Result of a maintenance run."""
+
+    tasks_run: list[str] = []
+    wal_compacted: int = 0
+    frozen_recovered: list[str] = []
+    errors: list[str] = []
+    timestamp: str = ""
+
+    def __init__(self, **data: Any) -> None:
+        super().__init__(**data)
+        if not self.timestamp:
+            object.__setattr__(self, "timestamp", datetime.now(timezone.utc).isoformat())
+
+
+class MaintenanceCron:
+    """Periodic maintenance tasks for SkillPool registry health.
+
+    Tasks:
+    - WAL compaction: remove committed WAL entries
+    - Freeze recovery: recover frozen operations
+    - State cleanup: remove stale temporary files
+    - Health report: generate system health summary
+    """
+
+    def __init__(self, state_dir: Path, stale_threshold: int = 300) -> None:
+        self._state_dir = state_dir
+        self._wal_dir = state_dir / "wal"
+        self._wal_manager = WALManager(self._wal_dir)
+        self._freeze_detector = FreezeDetector(state_dir, stale_threshold=stale_threshold)
+        self._report_dir = state_dir / "maintenance_reports"
+        self._report_dir.mkdir(parents=True, exist_ok=True)
+
+    def run_all(self) -> MaintenanceResult:
+        """Run all maintenance tasks."""
+        result = MaintenanceResult()
+        result.tasks_run.append("wal_compact")
+        try:
+            result.wal_compacted = self._wal_manager.compact()
+        except Exception as e:
+            result.errors.append(f"wal_compact: {e}")
+
+        result.tasks_run.append("freeze_check")
+        try:
+            report = self._freeze_detector.check()
+            if report.frozen_operations:
+                result.frozen_recovered = self._freeze_detector.recover_all()
+                result.tasks_run.append("freeze_recovery")
+        except Exception as e:
+            result.errors.append(f"freeze_check: {e}")
+
+        result.tasks_run.append("state_cleanup")
+        try:
+            self._cleanup_temp_files()
+        except Exception as e:
+            result.errors.append(f"state_cleanup: {e}")
+
+        self._save_report(result)
+        return result
+
+    def _cleanup_temp_files(self) -> int:
+        """Remove stale .tmp files older than 1 hour."""
+        removed = 0
+        cutoff = datetime.now(timezone.utc).timestamp() - 3600
+        for tmp_file in self._state_dir.rglob("*.tmp"):
+            try:
+                if tmp_file.stat().st_mtime < cutoff:
+                    tmp_file.unlink()
+                    removed += 1
+            except OSError:
+                continue
+        return removed
+
+    def _save_report(self, result: MaintenanceResult) -> None:
+        """Save maintenance report to disk."""
+        ts = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+        report_path = self._report_dir / f"maintenance_{ts}.json"
+        report_path.write_text(result.model_dump_json(), encoding="utf-8")
+        # Keep only last 10 reports
+        reports = sorted(self._report_dir.glob("maintenance_*.json"))
+        for old in reports[:-10]:
+            old.unlink()
+
+    def get_last_report(self) -> dict[str, Any] | None:
+        """Get the most recent maintenance report."""
+        reports = sorted(self._report_dir.glob("maintenance_*.json"))
+        if not reports:
+            return None
+        try:
+            return dict(json.loads(reports[-1].read_text(encoding="utf-8")))
+        except (json.JSONDecodeError, Exception):
+            return None
+
+    def get_health_summary(self) -> dict[str, Any]:
+        """Generate a health summary of the SkillPool system."""
+        wal_stats = self._wal_manager.get_stats()
+        freeze_report = self._freeze_detector.check()
+        last_report = self.get_last_report()
+        return {
+            "wal": wal_stats,
+            "freeze_status": freeze_report.status.value,
+            "frozen_operations": freeze_report.frozen_operations,
+            "last_maintenance": last_report,
+        }

skillpool/bridge/wal_manager.py

@@ -0,0 +1,136 @@
+"""SkillPool WAL Manager — Write-Ahead Log for atomic registry operations."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, model_validator
+
+
+class WALEntryType(str, Enum):
+    """Types of WAL operations."""
+
+    REGISTER = "register"
+    UPDATE = "update"
+    DELETE = "delete"
+    CHECKPOINT = "checkpoint"
+
+
+class WALEntry(BaseModel):
+    """A single WAL entry."""
+
+    entry_type: WALEntryType
+    skill_name: str
+    data: dict[str, Any] = {}
+    timestamp: str = ""
+    txn_id: str = ""
+
+    @model_validator(mode="after")
+    def _set_timestamp(self) -> WALEntry:
+        if not self.timestamp:
+            self.timestamp = datetime.now(timezone.utc).isoformat()
+        return self
+
+
+class WALManager:
+    """Write-Ahead Log manager for atomic registry operations.
+
+    Ensures crash-recovery by logging all mutations before applying them.
+    On startup, replays any uncommitted entries to restore consistency.
+    """
+
+    def __init__(self, wal_dir: Path) -> None:
+        self._wal_dir = wal_dir
+        self._wal_file = wal_dir / "wal.jsonl"
+        self._checkpoint_file = wal_dir / "checkpoint.json"
+        self._wal_dir.mkdir(parents=True, exist_ok=True)
+        self._txn_counter = 0
+
+    def _next_txn_id(self) -> str:
+        self._txn_counter += 1
+        ts = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
+        return f"txn-{ts}-{self._txn_counter:04d}"
+
+    def append(self, entry_type: WALEntryType, skill_name: str, data: dict[str, Any] | None = None) -> WALEntry:
+        """Append a new WAL entry."""
+        entry = WALEntry(
+            entry_type=entry_type,
+            skill_name=skill_name,
+            data=data or {},
+            txn_id=self._next_txn_id(),
+        )
+        with open(self._wal_file, "a", encoding="utf-8") as f:
+            f.write(entry.model_dump_json() + "\n")
+        return entry
+
+    def read_uncommitted(self) -> list[WALEntry]:
+        """Read WAL entries since last checkpoint."""
+        checkpoint_ts = self._load_checkpoint_timestamp()
+        entries: list[WALEntry] = []
+        if not self._wal_file.exists():
+            return entries
+        with open(self._wal_file, encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entry = WALEntry(**json.loads(line))
+                    if checkpoint_ts and entry.timestamp <= checkpoint_ts:
+                        continue
+                    entries.append(entry)
+                except (json.JSONDecodeError, Exception):
+                    continue
+        return entries
+
+    def checkpoint(self) -> str:
+        """Create a checkpoint marking all current WAL entries as committed."""
+        ts = datetime.now(timezone.utc).isoformat()
+        self._checkpoint_file.write_text(
+            json.dumps({"timestamp": ts, "entries": len(self.read_uncommitted())}),
+            encoding="utf-8",
+        )
+        self._wal_file.write_text("", encoding="utf-8")
+        return ts
+
+    def _load_checkpoint_timestamp(self) -> str | None:
+        """Load the last checkpoint timestamp."""
+        if not self._checkpoint_file.exists():
+            return None
+        try:
+            data = json.loads(self._checkpoint_file.read_text(encoding="utf-8"))
+            return str(data.get("timestamp")) if data.get("timestamp") is not None else None
+        except (json.JSONDecodeError, Exception):
+            return None
+
+    def recover(self) -> list[WALEntry]:
+        """Recover uncommitted entries after a crash."""
+        return self.read_uncommitted()
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get WAL statistics."""
+        uncommitted = self.read_uncommitted()
+        checkpoint_ts = self._load_checkpoint_timestamp()
+        wal_size = self._wal_file.stat().st_size if self._wal_file.exists() else 0
+        return {
+            "uncommitted_count": len(uncommitted),
+            "last_checkpoint": checkpoint_ts,
+            "wal_file_size_bytes": wal_size,
+            "wal_file_path": str(self._wal_file),
+        }
+
+    def compact(self) -> int:
+        """Compact the WAL by removing committed entries."""
+        uncommitted = self.read_uncommitted()
+        if not self._wal_file.exists():
+            return 0
+        with open(self._wal_file, encoding="utf-8") as f:
+            total = sum(1 for line in f if line.strip())
+        with open(self._wal_file, "w", encoding="utf-8") as f:
+            for entry in uncommitted:
+                f.write(entry.model_dump_json() + "\n")
+        return total - len(uncommitted)

skillpool/clawmem_client.py

@@ -0,0 +1,176 @@
+"""ClawMem integration — dual-write for blind spots, upgrades, and audit events.
+
+Provides ClawMemClient that wraps the ClawMem diary_write API (CLI or HTTP).
+When ClawMem is unavailable, writes are silently skipped (graceful degradation).
+
+Usage:
+    client = ClawMemClient()
+    client.write_blindspot("D3 score below 7.0", dimension="D3", severity="P1")
+    client.write_upgrade("S09 MINOR upgrade", upgrade_type="MINOR")
+    client.write_audit("cost_record accepted", trace_id="abc123")
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import subprocess
+from dataclasses import dataclass
+from enum import StrEnum
+
+logger = logging.getLogger(__name__)
+
+
+class ClawMemStatus(StrEnum):
+    AVAILABLE = "available"
+    UNAVAILABLE = "unavailable"
+    DEGRADED = "degraded"
+
+
+@dataclass
+class ClawMemWriteResult:
+    """Result of a ClawMem write attempt."""
+
+    success: bool
+    entry_id: str = ""
+    error: str = ""
+
+
+class ClawMemClient:
+    """Client for ClawMem diary_write integration.
+
+    Supports two transport modes:
+    - CLI: calls `clawmem diary write` subprocess
+    - HTTP: calls ClawMem HTTP API on port 7438 (preferred when available)
+
+    When ClawMem is unavailable, writes are silently skipped.
+    """
+
+    def __init__(
+        self,
+        http_url: str = "http://127.0.0.1:7438",
+        use_http: bool = True,
+        timeout_seconds: float = 5.0,
+    ) -> None:
+        self._http_url = http_url
+        self._use_http = use_http
+        self._timeout = timeout_seconds
+        self._status = ClawMemStatus.AVAILABLE
+        self._pending_writes: list[dict] = []
+
+    def write_blindspot(
+        self,
+        description: str,
+        dimension: str = "",
+        severity: str = "P2",
+        skill_id: str = "",
+    ) -> ClawMemWriteResult:
+        """Write a blind spot to ClawMem with appropriate tags."""
+        tags = ["blindspot-report", severity.lower()]
+        if dimension:
+            tags.append(dimension)
+        if skill_id:
+            tags.append(skill_id)
+        return self._write(description, tags)
+
+    def write_upgrade(
+        self,
+        description: str,
+        upgrade_type: str = "PATCH",
+        skill_id: str = "",
+    ) -> ClawMemWriteResult:
+        """Write an upgrade event to ClawMem."""
+        tags = ["skill-upgrade", upgrade_type.lower()]
+        if skill_id:
+            tags.append(skill_id)
+        return self._write(description, tags)
+
+    def write_audit(
+        self,
+        description: str,
+        trace_id: str = "",
+    ) -> ClawMemWriteResult:
+        """Write an audit event to ClawMem."""
+        tags = ["audit-event"]
+        if trace_id:
+            tags.append(f"trace:{trace_id[:8]}")
+        return self._write(description, tags)
+
+    def get_status(self) -> ClawMemStatus:
+        """Get current ClawMem availability status."""
+        return self._status
+
+    def get_pending_writes(self) -> list[dict]:
+        """Get writes that failed and are pending retry."""
+        return list(self._pending_writes)
+
+    def _write(self, entry: str, tags: list[str]) -> ClawMemWriteResult:
+        """Write an entry to ClawMem diary."""
+        if self._status == ClawMemStatus.UNAVAILABLE:
+            self._pending_writes.append({"entry": entry, "tags": tags})
+            return ClawMemWriteResult(success=False, error="ClawMem unavailable")
+
+        if self._use_http:
+            result = self._write_http(entry, tags)
+        else:
+            result = self._write_cli(entry, tags)
+
+        if not result.success:
+            self._pending_writes.append({"entry": entry, "tags": tags})
+            if self._status == ClawMemStatus.AVAILABLE:
+                self._status = ClawMemStatus.DEGRADED
+
+        return result
+
+    def _write_http(self, entry: str, tags: list[str]) -> ClawMemWriteResult:
+        """Write via ClawMem HTTP API."""
+        try:
+            import urllib.request
+
+            url = f"{self._http_url}/diary/write"
+            data = json.dumps({"entry": entry, "tags": tags}).encode()
+            req = urllib.request.Request(
+                url,
+                data=data,
+                headers={"Content-Type": "application/json"},
+            )
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                if resp.status == 200:
+                    body = json.loads(resp.read())
+                    return ClawMemWriteResult(
+                        success=True,
+                        entry_id=body.get("entry_id", ""),
+                    )
+                return ClawMemWriteResult(success=False, error=f"HTTP {resp.status}")
+        except Exception as e:
+            return ClawMemWriteResult(success=False, error=str(e))
+
+    def _write_cli(self, entry: str, tags: list[str]) -> ClawMemWriteResult:
+        """Write via ClawMem CLI subprocess."""
+        try:
+            cmd = ["clawmem", "diary", "write", entry]
+            for tag in tags:
+                cmd.extend(["-t", tag])
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=self._timeout,
+            )
+            if result.returncode == 0:
+                return ClawMemWriteResult(success=True, entry_id=result.stdout.strip())
+            return ClawMemWriteResult(
+                success=False,
+                error=f"CLI exit {result.returncode}: {result.stderr.strip()}",
+            )
+        except FileNotFoundError:
+            self._status = ClawMemStatus.UNAVAILABLE
+            return ClawMemWriteResult(success=False, error="clawmem CLI not found")
+        except subprocess.TimeoutExpired:
+            return ClawMemWriteResult(success=False, error="CLI timeout")
+        except Exception as e:
+            return ClawMemWriteResult(success=False, error=str(e))
+
+    def mark_available(self) -> None:
+        """Mark ClawMem as available (e.g., after recovery)."""
+        self._status = ClawMemStatus.AVAILABLE