@smilintux/skcapstone 0.10.0 → 0.12.5

package/src/skcapstone/api.py

@@ -139,7 +139,7 @@ class HealthResponse(BaseModel):
     )
     backend_health: Dict[str, Any] = Field(
         default_factory=dict,
-        description="Per-transport liveness flags (e.g. {skcomm: true}).",
+        description="Per-transport liveness flags (e.g. {skcomms: true}).",
     )
     disk_free_gb: float = Field(0.0, description="Free disk space in gigabytes.")
     memory_usage_mb: float = Field(0.0, description="Current RSS memory usage in MB.")
@@ -507,7 +507,7 @@ def _check_bearer(
 ) -> str:
     """Validate a CapAuth Bearer token for privileged endpoints.
 
-    Attempts CapAuth validation first (if skcomm is installed), then falls
+    Attempts CapAuth validation first (if skcomms is installed), then falls
     back to skcapstone signed token verification.
 
     Args:
@@ -527,7 +527,7 @@ def _check_bearer(
     config = _ctx.get("config")
 
     try:
-        from skcomm.capauth_validator import CapAuthValidator
+        from skcomms.capauth_validator import CapAuthValidator
 
         fingerprint = CapAuthValidator(require_auth=True).validate(token_str)
     except ImportError:
@@ -828,23 +828,23 @@ async def get_dashboard(
                 "consciousness": m.consciousness.value if hasattr(m, "consciousness") else "",
                 "version": m.version,
             }
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.warning("Failed to read agent identity from runtime manifest: %s", exc)
     if not agent:
         try:
             identity_path = config.home / "identity" / "identity.json"
             if identity_path.exists():
                 agent = json.loads(identity_path.read_text(encoding="utf-8"))
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to read identity.json for API status: %s", exc)
 
     # Consciousness stats
     c_stats: Dict[str, Any] = {}
     if consciousness:
         try:
             c_stats = dict(consciousness.stats)
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to read consciousness stats: %s", exc)
 
     # Recent conversations
     conversations: List[Dict[str, Any]] = []
@@ -862,8 +862,8 @@ async def get_dashboard(
                         "last": last.get("timestamp"),
                         "preview": preview,
                     })
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.warning("Failed to list recent conversations for API status: %s", exc)
 
     daemon_summary = DaemonSummary(
         running=snap.get("running", True),
@@ -924,8 +924,8 @@ async def get_capstone(
             m = runtime.manifest
             agent = {"name": m.identity.name, "fingerprint": m.identity.fingerprint or ""}
             pillars = {k: v.value for k, v in m.pillar_summary.items()}
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.warning("Failed to read agent pillars from runtime manifest: %s", exc)
 
     # Memory stats
     memory = MemorySummary()
@@ -940,8 +940,8 @@ async def get_capstone(
             long_term=ms.long_term,
             status=ms.status.value,
         )
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.warning("Failed to collect memory stats for capstone API: %s", exc)
 
     # Coordination board
     board: Dict[str, Any] = {"summary": {}, "active": []}
@@ -970,16 +970,16 @@ async def get_capstone(
                 if v.status.value in ("in_progress", "claimed")
             ],
         }
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.warning("Failed to collect coordination board data for capstone API: %s", exc)
 
     # Consciousness stats
     c_stats: Dict[str, Any] = {}
     if consciousness:
         try:
             c_stats = dict(consciousness.stats)
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to read consciousness stats for capstone API: %s", exc)
 
     return CapstoneResponse(
         agent=agent,
@@ -1027,8 +1027,8 @@ async def get_activity_stream(
         try:
             for chunk in _activity.get_history_encoded():
                 yield chunk
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to replay activity stream history: %s", exc)
         # Stream live events; yield keep-alive comments on timeout
         try:
             while True:
@@ -1100,8 +1100,8 @@ async def list_household_agents(
             if identity_path.exists():
                 try:
                     entry["identity"] = json.loads(identity_path.read_text(encoding="utf-8"))
-                except Exception:
-                    pass
+                except Exception as exc:
+                    logger.warning("Failed to read identity for agent %s: %s", agent_name, exc)
 
             hb: Optional[Dict[str, Any]] = None
             hb_path = heartbeats_dir / f"{agent_name.lower()}.json"
@@ -1112,7 +1112,8 @@ async def list_household_agents(
                     hb["alive"] = alive
                     entry["heartbeat"] = hb
                     entry["status"] = hb.get("status", "unknown") if alive else "stale"
-                except Exception:
+                except Exception as exc:
+                    logger.warning("Failed to read heartbeat for agent %s: %s", agent_name, exc)
                     entry["status"] = "unknown"
             else:
                 entry["status"] = "no_heartbeat"
@@ -1174,8 +1175,8 @@ async def get_household_agent(
     if identity_path.exists():
         try:
             entry["identity"] = json.loads(identity_path.read_text(encoding="utf-8"))
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to read identity for agent %s: %s", name, exc)
 
     hb_path = config.shared_root / "heartbeats" / f"{name.lower()}.json"
     if hb_path.exists():
@@ -1185,8 +1186,8 @@ async def get_household_agent(
             hb["alive"] = alive
             entry["heartbeat"] = hb
             entry["status"] = hb.get("status", "unknown") if alive else "stale"
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to read heartbeat for agent %s: %s", name, exc)
 
     # Memory count
     memory_dir = agent_dir / "memory"
@@ -1249,8 +1250,8 @@ async def list_conversations(
                             last_message_preview=(last_content or "")[:120],
                         )
                     )
-            except Exception:
-                pass
+            except Exception as exc:
+                logger.warning("Failed to read conversation file %s: %s", cf, exc)
     return ConversationsResponse(conversations=conversations)
 
 
@@ -1329,7 +1330,7 @@ async def send_message(
 ) -> SendMessageResponse:
     """Send a message to a named peer.
 
-    Writes the message envelope to the SKComm outbox for delivery by the
+    Writes the message envelope to the SKComms outbox for delivery by the
     transport layer.  If the consciousness loop is running the message is
     also processed inline to generate a reply.
 
@@ -1534,8 +1535,8 @@ def _load_first_argocd_doc(path: Path) -> Optional[dict]:
                     "sync_policy": spec.get("syncPolicy", {}),
                     "manifest_file": path.name,
                 }
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.warning("Failed to parse ArgoCD manifest %s: %s", path, exc)
     return None
 
 
@@ -1618,8 +1619,8 @@ def _get_argocd_status() -> dict:
                     "last_synced": (item_status.get("operationState") or {}).get("finishedAt"),
                 }
             source = "yaml+kubectl"
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.warning("kubectl ArgoCD status query failed (using yaml only): %s", exc)
 
     # ── Merge and build output ───────────────────────────────────────────────
     apps = []
@@ -1737,7 +1738,7 @@ async def websocket_logs(
     config = _ctx.get("config")
 
     try:
-        from skcomm.capauth_validator import CapAuthValidator
+        from skcomms.capauth_validator import CapAuthValidator
 
         fingerprint = CapAuthValidator(require_auth=True).validate(token_str)
     except ImportError:
@@ -1767,8 +1768,8 @@ async def websocket_logs(
                 tail_lines = list(deque(fh, maxlen=50))
             for line in tail_lines:
                 await websocket.send_json({"type": "line", "line": line.rstrip("\n")})
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to replay log tail history over websocket: %s", exc)
 
     # Tail the log file and stream new lines
     try:
@@ -1783,8 +1784,8 @@ async def websocket_logs(
                             for ln in chunk.splitlines():
                                 await websocket.send_json({"type": "line", "line": ln})
                         offset = fh.tell()
-                except Exception:
-                    pass
+                except Exception as exc:
+                    logger.warning("Log tail websocket read error: %s", exc)
             await asyncio.sleep(0.5)
     except WebSocketDisconnect:
         pass

package/src/skcapstone/auction.py

@@ -95,7 +95,8 @@ def _collect_local_bid(task_id: str, agent_name: str, shared_root: Path) -> Auct
         import psutil  # optional dep
 
         cpu = psutil.cpu_percent(interval=0.1)
-    except Exception:
+    except Exception as e:
+        logger.warning("auction.py: %s", e)
         cpu = 0.0
 
     # Claimed-tasks count from agent file
@@ -107,8 +108,8 @@ def _collect_local_bid(task_id: str, agent_name: str, shared_root: Path) -> Auct
         agent_file = board.load_agent(agent_name)
         if agent_file:
             claimed_count = len(agent_file.claimed_tasks)
-    except Exception:
-        pass
+    except Exception as exc:
+        logger.warning("Failed to read claimed task count for agent %s: %s", agent_name, exc)
 
     return AuctionBid(
         task_id=task_id,
@@ -283,8 +284,8 @@ class AuctionManager:
                     ttl_seconds=3600,
                     tags=["auction", "no_bidders"],
                 )
-            except Exception:
-                pass
+            except Exception as exc:
+                logger.warning("Failed to publish auction_no_bidders event for %s: %s", task_id, exc)
             return None
 
         winner_bid = min(record.bids, key=_load_score)
@@ -327,8 +328,8 @@ class AuctionManager:
                 ttl_seconds=3600,
                 tags=["auction", "resolved"],
             )
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to publish auction_resolved event for %s: %s", task_id, exc)
 
         # Notify activity stream
         try:
@@ -338,8 +339,8 @@ class AuctionManager:
                 "task.auction_resolved",
                 {"task_id": task_id, "winner": winner, "bids": len(record.bids)},
             )
-        except Exception:
-            pass
+        except Exception as exc:
+            logger.warning("Failed to push auction_resolved activity for %s: %s", task_id, exc)
 
         return winner
 
@@ -361,7 +362,8 @@ class AuctionManager:
                 key=lambda p: p.stat().st_mtime,
                 reverse=True,
             )[:limit]
-        except Exception:
+        except Exception as e:
+            logger.warning("auction.py: %s", e)
             paths = []
 
         for path in paths:
@@ -371,7 +373,8 @@ class AuctionManager:
                         json.loads(path.read_text(encoding="utf-8"))
                     )
                 )
-            except Exception:
+            except Exception as e:
+                logger.warning("auction.py: %s", e)
                 continue
 
         return {

package/src/skcapstone/backup.py

@@ -340,6 +340,7 @@ def _read_agent_name(home: Path) -> str:
                 name = data.get("name") or data.get("agent_name")
                 if name:
                     return name
-            except Exception:
+            except Exception as e:
+                logger.warning("backup.py: %s", e)
                 continue
     return "unknown"

package/src/skcapstone/blueprint_registry.py

@@ -183,8 +183,8 @@ class BlueprintRegistryClient:
             error_body = ""
             try:
                 error_body = exc.read().decode("utf-8", errors="replace")
-            except Exception:
-                pass
+            except Exception as read_exc:
+                logger.debug("Failed to read error body from registry HTTP error: %s", read_exc)
             msg = f"Registry API error {exc.code} for {method} {path}"
             if error_body:
                 msg += f": {error_body[:500]}"
@@ -406,7 +406,8 @@ def _fetch_github_blueprints(query: str = "") -> Optional[list[dict[str, Any]]]:
             )
             with urllib.request.urlopen(cat_req, timeout=10) as resp:
                 files = json.loads(resp.read().decode("utf-8"))
-        except Exception:
+        except Exception as e:
+            logger.warning("blueprint_registry.py: %s", e)
             continue
 
         for file_entry in files:

package/src/skcapstone/brain_first.py

@@ -0,0 +1,238 @@
+"""
+Brain-First Protocol — think before you act.
+
+Before an agent acts on any task, it consults its memory to see if it
+already knows something relevant.  This avoids redundant work, surfaces
+prior decisions, and grounds the agent in its own experience.
+
+Usage:
+    from skcapstone.brain_first import brain_first_check
+
+    result = brain_first_check("deploy the monitoring stack")
+    if result.has_memories:
+        # use result.memories as additional context
+        ...
+
+Configuration (config.yaml):
+    brain_first:
+      enabled: true          # master toggle (default: true)
+      max_results: 5          # how many memories to surface (default: 5)
+      min_importance: 0.3     # ignore low-importance memories (default: 0.3)
+      auto_inject: false      # auto-prepend memories to MCP tool responses (default: false)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger("skcapstone.brain_first")
+
+# Stop-words to strip from queries before searching memory
+_STOP_WORDS = frozenset({
+    "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
+    "have", "has", "had", "do", "does", "did", "will", "would", "shall",
+    "should", "may", "might", "must", "can", "could", "to", "of", "in",
+    "for", "on", "with", "at", "by", "from", "as", "into", "through",
+    "during", "before", "after", "above", "below", "between", "out",
+    "off", "over", "under", "again", "further", "then", "once", "here",
+    "there", "when", "where", "why", "how", "all", "each", "every",
+    "both", "few", "more", "most", "other", "some", "such", "no", "nor",
+    "not", "only", "own", "same", "so", "than", "too", "very", "just",
+    "because", "but", "and", "or", "if", "while", "about", "up", "it",
+    "its", "this", "that", "these", "those", "i", "me", "my", "we",
+    "our", "you", "your", "he", "him", "his", "she", "her", "they",
+    "them", "their", "what", "which", "who", "whom",
+})
+
+
+@dataclass
+class BrainFirstConfig:
+    """Configuration for the brain-first protocol."""
+
+    enabled: bool = True
+    max_results: int = 5
+    min_importance: float = 0.3
+    auto_inject: bool = False
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "BrainFirstConfig":
+        """Create config from a dict (e.g. from config.yaml brain_first section)."""
+        return cls(
+            enabled=data.get("enabled", True),
+            max_results=data.get("max_results", 5),
+            min_importance=data.get("min_importance", 0.3),
+            auto_inject=data.get("auto_inject", False),
+        )
+
+
+@dataclass
+class BrainFirstResult:
+    """Result of a brain-first memory consultation."""
+
+    query: str
+    keywords: list[str]
+    memories: list[dict] = field(default_factory=list)
+    enabled: bool = True
+    error: Optional[str] = None
+
+    @property
+    def has_memories(self) -> bool:
+        """Whether any relevant memories were found."""
+        return len(self.memories) > 0
+
+    def as_context(self) -> str:
+        """Format memories as a context block for injection into prompts."""
+        if not self.has_memories:
+            return ""
+        lines = ["[Brain-First: relevant memories found]"]
+        for i, mem in enumerate(self.memories, 1):
+            content = mem.get("content", "")[:200]
+            layer = mem.get("layer", "?")
+            importance = mem.get("importance", 0)
+            tags = ", ".join(mem.get("tags", []))
+            lines.append(
+                f"  {i}. [{layer}|imp={importance:.1f}] {content}"
+                + (f"  tags: {tags}" if tags else "")
+            )
+        return "\n".join(lines)
+
+
+def extract_keywords(text: str) -> list[str]:
+    """Extract meaningful keywords from a text string.
+
+    Strips stop-words and short tokens, keeping domain-relevant terms.
+
+    Args:
+        text: Input text (task title, prompt, etc.).
+
+    Returns:
+        List of unique keywords, longest first.
+    """
+    # Lowercase, split on non-alphanumeric
+    tokens = re.split(r"[^a-zA-Z0-9_-]+", text.lower())
+    # Filter: no stop-words, no short tokens
+    keywords = list(dict.fromkeys(
+        t for t in tokens if t and t not in _STOP_WORDS and len(t) > 2
+    ))
+    # Sort longest first (longer terms tend to be more specific)
+    keywords.sort(key=len, reverse=True)
+    return keywords
+
+
+def _load_config() -> BrainFirstConfig:
+    """Load brain-first config from the agent's config.yaml.
+
+    Falls back to defaults if the file or section is missing.
+    """
+    try:
+        import yaml
+    except ImportError:
+        return BrainFirstConfig()
+
+    from . import AGENT_HOME, SKCAPSTONE_AGENT
+
+    for base in [
+        Path(AGENT_HOME).expanduser() / "agents" / SKCAPSTONE_AGENT,
+        Path(AGENT_HOME).expanduser(),
+    ]:
+        config_file = base / "config" / "config.yaml"
+        if config_file.exists():
+            try:
+                data = yaml.safe_load(config_file.read_text(encoding="utf-8")) or {}
+                bf_data = data.get("brain_first", {})
+                if bf_data:
+                    return BrainFirstConfig.from_dict(bf_data)
+            except Exception as exc:
+                logger.debug("Failed to load brain_first config from %s: %s", config_file, exc)
+
+    return BrainFirstConfig()
+
+
+def brain_first_check(
+    context: str,
+    config: Optional[BrainFirstConfig] = None,
+    tags: Optional[list[str]] = None,
+) -> BrainFirstResult:
+    """Consult memory before acting on a task.
+
+    This is the core brain-first function.  Given a task description or
+    prompt context, it extracts keywords, searches memory, and returns
+    any relevant memories that the agent should consider.
+
+    Args:
+        context: The task description, prompt, or action context.
+        config: Override config (uses agent config.yaml if None).
+        tags: Optional tag filter for the memory search.
+
+    Returns:
+        BrainFirstResult with any relevant memories.
+    """
+    if config is None:
+        config = _load_config()
+
+    keywords = extract_keywords(context)
+    result = BrainFirstResult(
+        query=context,
+        keywords=keywords,
+        enabled=config.enabled,
+    )
+
+    if not config.enabled:
+        result.error = "brain-first protocol disabled"
+        return result
+
+    if not keywords:
+        result.error = "no meaningful keywords extracted"
+        return result
+
+    # Build a search query from top keywords (limit to 6 to avoid noise)
+    search_query = " ".join(keywords[:6])
+
+    try:
+        from .memory_engine import search as memory_search
+        from .mcp_tools._helpers import _home
+
+        home = _home()
+        entries = memory_search(
+            home=home,
+            query=search_query,
+            tags=tags,
+            limit=config.max_results * 2,  # over-fetch, then filter
+        )
+
+        # Filter by minimum importance
+        entries = [e for e in entries if e.importance >= config.min_importance]
+
+        # Truncate to max_results
+        entries = entries[:config.max_results]
+
+        result.memories = [
+            {
+                "memory_id": e.memory_id,
+                "content": e.content[:300],
+                "layer": e.layer.value,
+                "tags": e.tags,
+                "importance": e.importance,
+                "access_count": e.access_count,
+                "source": e.source,
+            }
+            for e in entries
+        ]
+
+        logger.info(
+            "Brain-first check: %d memories found for %d keywords from '%s'",
+            len(result.memories),
+            len(keywords),
+            context[:80],
+        )
+
+    except Exception as exc:
+        result.error = f"memory search failed: {exc}"
+        logger.warning("Brain-first check failed: %s", exc)
+
+    return result

package/src/skcapstone/changelog.py

@@ -21,7 +21,7 @@ from .coordination import Board, TaskStatus
 
 
 TAG_CATEGORIES = {
-    "feature": ["skcapstone", "skchat", "skcomm", "skmemory", "capauth", "cloud9", "skworld"],
+    "feature": ["skcapstone", "skchat", "skcomms", "skmemory", "capauth", "cloud9", "skworld"],
     "security": ["security", "encryption", "capauth", "integrity", "quantum-resistant", "pgp"],
     "infrastructure": ["ci", "docker", "systemd", "daemon", "syncthing", "pypi", "packaging"],
     "documentation": ["documentation", "docs", "readme", "quickstart", "api"],