nucleus-mcp 1.0.7 → 1.2.0

package/src/mcp_server_nucleus/runtime/depth_ops.py

@@ -1,339 +0,0 @@
-"""
-Nucleus Runtime - Depth Tracking Operations
-===========================================
-Core logic for depth tracking (Rabbit hole protection).
-"""
-
-import json
-import time
-import logging
-from typing import Dict, Any
-from pathlib import Path
-
-# Relative imports assuming this is in mcp_server_nucleus.runtime
-from .common import get_brain_path
-from .event_ops import _emit_event
-
-logger = logging.getLogger("nucleus.depth_ops")
-
-def _get_depth_path() -> Path:
-    """Get the path to the depth tracking file."""
-    brain = get_brain_path()
-    session_dir = brain / "session"
-    session_dir.mkdir(parents=True, exist_ok=True)
-    return session_dir / "depth.json"
-
-def _get_depth_state() -> Dict[str, Any]:
-    """Get current depth tracking state."""
-    try:
-        depth_path = _get_depth_path()
-        
-        if not depth_path.exists():
-            # Initialize with default state
-            default_state = {
-                "session_id": f"session-{time.strftime('%Y%m%d')}",
-                "current_depth": 0,
-                "max_safe_depth": 5,
-                "levels": [],
-                "created_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
-                "updated_at": time.strftime("%Y-%m-%dT%H:%M:%S%z")
-            }
-            with open(depth_path, "w") as f:
-                json.dump(default_state, f, indent=2)
-            return default_state
-        
-        with open(depth_path, "r") as f:
-            return json.load(f)
-    except Exception as e:
-        logger.error(f"Error getting depth state: {e}")
-        return {"current_depth": 0, "levels": [], "max_safe_depth": 5}
-
-def _save_depth_state(state: Dict[str, Any]) -> str:
-    """Save depth tracking state."""
-    try:
-        depth_path = _get_depth_path()
-        state["updated_at"] = time.strftime("%Y-%m-%dT%H:%M:%S%z")
-        with open(depth_path, "w") as f:
-            json.dump(state, f, indent=2)
-        return "Depth state saved"
-    except Exception as e:
-        return f"Error saving depth state: {str(e)}"
-
-def _depth_push(topic: str) -> Dict[str, Any]:
-    """Go deeper into a subtopic. Returns current state with warnings."""
-    try:
-        state = _get_depth_state()
-        
-        new_depth = state.get("current_depth", 0) + 1
-        max_safe = state.get("max_safe_depth", 5)
-        
-        # Create new level entry
-        new_level = {
-            "depth": new_depth,
-            "topic": topic,
-            "started_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
-            "status": "current"
-        }
-        
-        # Update previous level status
-        levels = state.get("levels", [])
-        for level in levels:
-            if level.get("status") == "current":
-                level["status"] = "active"
-        
-        levels.append(new_level)
-        
-        state["current_depth"] = new_depth
-        state["levels"] = levels
-        _save_depth_state(state)
-        
-        # Generate warning based on depth
-        warning = None
-        warning_level = "safe"
-        
-        if new_depth >= max_safe:
-            warning = f"🔴🔴 RABBIT HOLE! You're at level {new_depth}/{max_safe}. Consider resurfacing."
-            warning_level = "danger"
-        elif new_depth >= max_safe - 1:
-            warning = f"🔴 DEEP DIVE ALERT! Level {new_depth}/{max_safe}. You're in the danger zone."
-            warning_level = "danger"
-        elif new_depth >= 3:
-            warning = f"🟡 CAUTION: Level {new_depth}/{max_safe}. Getting deep - just so you know."
-            warning_level = "caution"
-        
-        # Build breadcrumb path
-        breadcrumbs = " → ".join([lv["topic"] for lv in levels])
-        
-        # Emit event
-        _emit_event("depth_increased", "depth_tracker", {
-            "new_depth": new_depth,
-            "topic": topic,
-            "warning_level": warning_level
-        })
-        
-        return {
-            "current_depth": new_depth,
-            "max_safe_depth": max_safe,
-            "topic": topic,
-            "breadcrumbs": breadcrumbs,
-            "warning": warning,
-            "warning_level": warning_level,
-            "indicator": _format_depth_indicator(new_depth, max_safe)
-        }
-    except Exception as e:
-        return {"error": str(e)}
-
-def _depth_pop() -> Dict[str, Any]:
-    """Come back up one level. Returns new state."""
-    try:
-        state = _get_depth_state()
-        levels = state.get("levels", [])
-        
-        if not levels:
-            return {
-                "current_depth": 0,
-                "message": "Already at root level (depth 0). Nothing to pop.",
-                "indicator": _format_depth_indicator(0, state.get("max_safe_depth", 5))
-            }
-        
-        # Pop the current level
-        popped = levels.pop()
-        
-        # Set new current
-        if levels:
-            levels[-1]["status"] = "current"
-        
-        new_depth = len(levels)
-        state["current_depth"] = new_depth
-        state["levels"] = levels
-        _save_depth_state(state)
-        
-        # Build breadcrumb path
-        breadcrumbs = " → ".join([lv["topic"] for lv in levels]) if levels else "(root)"
-        returned_to = levels[-1]["topic"] if levels else "root"
-        
-        # Emit event
-        _emit_event("depth_decreased", "depth_tracker", {
-            "new_depth": new_depth,
-            "returned_to": returned_to,
-            "popped_topic": popped["topic"]
-        })
-        
-        return {
-            "current_depth": new_depth,
-            "returned_to": returned_to,
-            "popped_topic": popped["topic"],
-            "breadcrumbs": breadcrumbs,
-            "message": f"✅ Resurfaced! Now at level {new_depth}: {returned_to}",
-            "indicator": _format_depth_indicator(new_depth, state.get("max_safe_depth", 5))
-        }
-    except Exception as e:
-        return {"error": str(e)}
-
-def _depth_show() -> Dict[str, Any]:
-    """Show current depth state with visual indicator."""
-    try:
-        state = _get_depth_state()
-        current_depth = state.get("current_depth", 0)
-        max_safe = state.get("max_safe_depth", 5)
-        levels = state.get("levels", [])
-        
-        # Build breadcrumb path
-        breadcrumbs = " → ".join([lv["topic"] for lv in levels]) if levels else "(root)"
-        
-        # Build tree visualization
-        tree_lines = []
-        for i, level in enumerate(levels):
-            indent = "  " * i
-            prefix = "└─ " if i > 0 else ""
-            marker = " ← YOU ARE HERE" if level.get("status") == "current" else ""
-            tree_lines.append(f"{indent}{prefix}{i}: {level['topic']}{marker}")
-        
-        tree = "\n".join(tree_lines) if tree_lines else "(At root level)"
-        
-        # Generate status
-        if current_depth >= max_safe:
-            status = "🔴 RABBIT HOLE"
-        elif current_depth >= max_safe - 1:
-            status = "🔴 DANGER ZONE"
-        elif current_depth >= 3:
-            status = "🟡 CAUTION"
-        else:
-            status = "🟢 SAFE"
-        
-        return {
-            "current_depth": current_depth,
-            "max_safe_depth": max_safe,
-            "status": status,
-            "breadcrumbs": breadcrumbs,
-            "tree": tree,
-            "indicator": _format_depth_indicator(current_depth, max_safe),
-            "levels": levels,
-            "session_id": state.get("session_id"),
-            "help": "Commands: brain_depth_push(topic), brain_depth_pop(), brain_depth_reset(), brain_depth_set_max(n)"
-        }
-    except Exception as e:
-        return {"error": str(e)}
-
-def _depth_reset() -> Dict[str, Any]:
-    """Reset depth to 0 (root level). Clears all levels."""
-    try:
-        state = _get_depth_state()
-        state["current_depth"] = 0
-        state["levels"] = []
-        _save_depth_state(state)
-        
-        return {
-            "current_depth": 0,
-            "message": "✅ Depth reset to root level.",
-            "indicator": _format_depth_indicator(0, state.get("max_safe_depth", 5))
-        }
-    except Exception as e:
-        return {"error": str(e)}
-
-def _depth_set_max(max_depth: int) -> Dict[str, Any]:
-    """Set the maximum safe depth threshold."""
-    try:
-        # Validate range
-        if max_depth < 1 or max_depth > 10:
-            return {
-                "error": "max_depth must be between 1 and 10",
-                "current_max": None
-            }
-        
-        state = _get_depth_state()
-        old_max = state.get("max_safe_depth", 5)
-        state["max_safe_depth"] = max_depth
-        _save_depth_state(state)
-        
-        current = state.get("current_depth", 0)
-        return {
-            "old_max": old_max,
-            "new_max": max_depth,
-            "current_depth": current,
-            "indicator": _format_depth_indicator(current, max_depth),
-            "message": f"✅ Max depth updated: {old_max} → {max_depth}"
-        }
-    except Exception as e:
-        return {"error": str(e)}
-
-def _format_depth_indicator(current: int, max_safe: int) -> str:
-    """Returns a visual progress-style indicator of depth."""
-    indicator = "["
-    for i in range(max_safe):
-        if i < current:
-            indicator += "█"
-        else:
-            indicator += "░"
-    indicator += "]"
-    
-    if current >= max_safe:
-        indicator += " ⚠️"
-        
-    return indicator
-
-def _generate_depth_map() -> Dict[str, Any]:
-    """Generate a Mermaid diagram of the current exploration path."""
-    try:
-        state = _get_depth_state()
-        levels = state.get("levels", [])
-        max_safe = state.get("max_safe_depth", 5)
-        
-        if not levels:
-            return {
-                "mermaid": "```mermaid\ngraph TD\n    ROOT((🏠 START))\n    style ROOT fill:#ccffcc,stroke:#0a0\n```",
-                "message": "You're at the root level. No exploration path yet.",
-                "node_count": 0
-            }
-        
-        # Build Mermaid graph
-        lines = ["graph TD"]
-        lines.append("    ROOT((🏠 START))")
-        
-        prev_id = "ROOT"
-        for i, level in enumerate(levels):
-            node_id = f"L{i}"
-            topic = level.get("topic", f"Level {i+1}")
-            # Escape quotes and special chars
-            topic_safe = topic.replace('"', "'").replace("[", "(").replace("]", ")")
-            
-            # Determine node style based on depth
-            depth = i + 1
-            if depth >= max_safe:
-                style = "fill:#ffcccc,stroke:#f00"  # Red - rabbit hole
-                node_shape = f'{node_id}[["🔴 {topic_safe}"]]'
-            elif depth >= max_safe - 1:
-                style = "fill:#ffddcc,stroke:#f60"  # Orange - danger
-                node_shape = f'{node_id}[["🔴 {topic_safe}"]]'
-            elif depth >= 3:
-                style = "fill:#ffffcc,stroke:#cc0"  # Yellow - caution
-                node_shape = f'{node_id}["🟡 {topic_safe}"]'
-            else:
-                style = "fill:#ccffcc,stroke:#0a0"  # Green - safe
-                node_shape = f'{node_id}["🟢 {topic_safe}"]'
-            
-            lines.append(f"    {prev_id} --> {node_shape}")
-            lines.append(f"    style {node_id} {style}")
-            prev_id = node_id
-        
-        # Mark the last node as current
-        if levels:
-            lines.append(f"    style {prev_id} stroke-width:3px")
-        
-        # Wrap in code block
-        mermaid_code = "```mermaid\n" + "\n".join(lines) + "\n```"
-        
-        # Build path summary
-        path = " → ".join([lv.get("topic", "?") for lv in levels])
-        
-        return {
-            "mermaid": mermaid_code,
-            "path": f"🏠 → {path}",
-            "current_depth": len(levels),
-            "max_safe_depth": max_safe,
-            "node_count": len(levels),
-            "message": f"Exploration map with {len(levels)} nodes. Current depth: {len(levels)}/{max_safe}"
-        }
-    except Exception as e:
-        return {"error": str(e)}
-

package/src/mcp_server_nucleus/runtime/event_ops.py

@@ -1,103 +0,0 @@
-"""
-Nucleus Runtime - Event Operations
-==================================
-Core logic for event stream management.
-"""
-
-import json
-import time
-import uuid
-from typing import Dict, Any, List
-from datetime import datetime, timezone
-
-from .common import get_brain_path, logger
-
-def _log_interaction(emitter: str, event_type: str, data: Dict[str, Any]) -> None:
-    """Log a cryptographic hash of the interaction for user trust (V9 Security)."""
-    try:
-        import hashlib
-        brain = get_brain_path()
-        log_path = brain / "ledger" / "interaction_log.jsonl"
-        
-        # Create a stable string representation for hashing
-        payload = json.dumps({"type": event_type, "emitter": emitter, "data": data}, sort_keys=True)
-        h = hashlib.sha256(payload.encode()).hexdigest()
-        
-        entry = {
-            "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
-            "emitter": emitter,
-            "type": event_type,
-            "hash": h,
-            "alg": "sha256"
-        }
-        
-        with open(log_path, "a") as f:
-            f.write(json.dumps(entry) + "\n")
-    except Exception as e:
-        logger.warning(f"Failed to log interaction trust signal: {e}")
-
-def _emit_event(event_type: str, emitter: str, data: Dict[str, Any], description: str = "") -> str:
-    """Core logic for emitting an event."""
-    try:
-        brain = get_brain_path()
-        events_path = brain / "ledger" / "events.jsonl"
-        
-        event_id = f"evt-{int(time.time())}-{str(uuid.uuid4())[:8]}"
-        timestamp = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
-        
-        event = {
-            "event_id": event_id,
-            "timestamp": timestamp,
-            "type": event_type,
-            "emitter": emitter,
-            "data": data,
-            "description": description
-        }
-        
-        with open(events_path, "a") as f:
-            f.write(json.dumps(event) + "\n")
-
-        # Log interaction for security audit (Trust Signal)
-        _log_interaction(emitter, event_type, data)
-        
-        # Update activity summary for fast satellite view (Tier 2 precomputation)
-        try:
-            summary_path = brain / "ledger" / "activity_summary.json"
-            summary = {}
-            if summary_path.exists():
-                with open(summary_path, "r") as f:
-                    summary = json.load(f)
-            
-            summary["last_event"] = event
-            summary["updated_at"] = timestamp
-            summary["event_count"] = summary.get("event_count", 0) + 1
-            
-            with open(summary_path, "w") as f:
-                json.dump(summary, f, indent=2)
-        except Exception:
-            pass  # Don't fail event emit if summary update fails
-            
-        return event_id
-    except Exception as e:
-        return f"Error emitting event: {str(e)}"
-
-def _read_events(limit: int = 10) -> List[Dict[str, Any]]:
-    """Core logic for reading events."""
-    try:
-        brain = get_brain_path()
-        events_path = brain / "ledger" / "events.jsonl"
-        
-        if not events_path.exists():
-            return []
-            
-        events = []
-        with open(events_path, "r") as f:
-            for line in f:
-                if line.strip():
-                    events.append(json.loads(line))
-        
-        return events[-limit:]
-    except Exception as e:
-        # Avoid logger dependency here if possible, or print
-        print(f"Error reading events: {e}")
-        return []

package/src/mcp_server_nucleus/runtime/event_stream.py

@@ -1,213 +0,0 @@
-"""
-Nucleus Agent Runtime - Event Stream
-=====================================
-The nervous system of the Agent Control Plane.
-Events flow through here, triggering agent activation.
-
-Location: mcp_server_nucleus/runtime/event_stream.py
-"""
-
-import json
-from datetime import datetime, timezone
-from enum import Enum
-from pathlib import Path
-from typing import Dict, List, Any, Optional
-import uuid
-
-
-class EventSeverity(Enum):
-    """Event severity levels per synthesizer.md protocol"""
-    ROUTINE = "ROUTINE"     # Auto-approve, log only
-    NOTABLE = "NOTABLE"     # Include in Daily Digest
-    CRITICAL = "CRITICAL"   # IMMEDIATE escalation to founder
-
-
-def get_events_path(brain_path: Path) -> Path:
-    """Get path to event stream"""
-    return brain_path / "ledger" / "events.jsonl"
-
-
-def read_events(brain_path: Path, limit: int = 50) -> List[Dict]:
-    """
-    Read the last N events from the stream.
-    Returns events in reverse chronological order (newest first).
-    """
-    events_path = get_events_path(brain_path)
-    
-    if not events_path.exists():
-        return []
-    
-    # Read all events
-    events = []
-    with open(events_path, 'r') as f:
-        for line in f:
-            line = line.strip()
-            if line:
-                try:
-                    events.append(json.loads(line))
-                except json.JSONDecodeError:
-                    continue
-    
-    # Return last N, reversed (newest first)
-    return events[-limit:][::-1]
-
-
-def emit_event(
-    brain_path: Path,
-    event_type: str,
-    emitter: str,
-    payload: Dict[str, Any],
-    severity: EventSeverity = EventSeverity.ROUTINE,
-    metadata: Optional[Dict] = None
-) -> Dict:
-    """
-    Emit an event to the stream.
-    Returns the created event.
-    """
-    events_path = get_events_path(brain_path)
-    events_path.parent.mkdir(parents=True, exist_ok=True)
-    
-    event = {
-        "event_id": f"{emitter[:3]}-{uuid.uuid4().hex[:8]}",
-        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
-        "emitter": emitter,
-        "event_type": event_type,
-        "severity": severity.value,
-        "payload": payload,
-        "metadata": metadata or {}
-    }
-    
-    # Append to stream
-    with open(events_path, 'a') as f:
-        f.write(json.dumps(event) + '\n')
-    
-    # Bridge to Cloud (Fire & Forget)
-    try:
-        from mcp_server_nucleus.runtime.firestore_bridge import get_bridge
-        get_bridge().push_event(event)
-    except Exception:
-        # Never block local op on cloud fail
-        pass
-    
-    return event
-
-
-def get_unprocessed_events(
-    brain_path: Path, 
-    last_processed_id: Optional[str] = None,
-    severity_filter: Optional[EventSeverity] = None
-) -> List[Dict]:
-    """
-    Get events that haven't been processed yet.
-    Optionally filter by severity.
-    """
-    events = read_events(brain_path, limit=100)
-    
-    # If we have a last processed ID, skip events until we find it
-    if last_processed_id:
-        found = False
-        filtered = []
-        for event in events:
-            if found:
-                filtered.append(event)
-            elif event.get('event_id') == last_processed_id:
-                found = True
-        events = filtered if found else events
-    
-    # Filter by severity if specified
-    if severity_filter:
-        events = [e for e in events if e.get('severity') == severity_filter.value]
-    
-    return events
-
-
-def get_critical_events(brain_path: Path, limit: int = 10) -> List[Dict]:
-    """Get CRITICAL events that need immediate attention"""
-    events = read_events(brain_path, limit=limit * 5)  # Read more to find criticals
-    return [e for e in events if e.get('severity') == 'CRITICAL'][:limit]
-
-
-def rotate_events(brain_path: Path, keep_count: int = 1000) -> int:
-    """
-    Rotate event stream to prevent unbounded growth.
-    Keeps the last N events, archives the rest.
-    Returns count of archived events.
-    """
-    events_path = get_events_path(brain_path)
-    archive_path = brain_path / "ledger" / "archive" / f"events_{datetime.now().strftime('%Y%m%d_%H%M%S')}.jsonl"
-    
-    if not events_path.exists():
-        return 0
-    
-    # Read all events
-    events = []
-    with open(events_path, 'r') as f:
-        for line in f:
-            line = line.strip()
-            if line:
-                events.append(line)
-    
-    if len(events) <= keep_count:
-        return 0
-    
-    # Split into keep and archive
-    to_archive = events[:-keep_count]
-    to_keep = events[-keep_count:]
-    
-    # Write archive
-    archive_path.parent.mkdir(parents=True, exist_ok=True)
-    with open(archive_path, 'w') as f:
-        f.write('\n'.join(to_archive) + '\n')
-    
-    # Overwrite main file with kept events
-    with open(events_path, 'w') as f:
-        f.write('\n'.join(to_keep) + '\n')
-    
-    return len(to_archive)
-
-
-# ============================================================
-# COMMON EVENT TYPES (for type safety)
-# ============================================================
-
-class EventTypes:
-    """Standard event types in the system"""
-    # Task lifecycle
-    TASK_ASSIGNED = "task_assigned"
-    TASK_COMPLETED = "task_completed"
-    TASK_FAILED = "task_failed"
-    
-    # Sprint lifecycle
-    SPRINT_STARTED = "sprint_started"
-    SPRINT_COMPLETED = "sprint_completed"
-    
-    # Agent lifecycle
-    AGENT_ACTIVATED = "agent_activated"
-    AGENT_TERMINATED = "agent_terminated"
-    
-    # Review lifecycle
-    IMPLEMENTATION_COMPLETE = "implementation_complete"
-    REVIEW_APPROVED = "review_approved"
-    REVIEW_BLOCKED = "review_blocked"
-    
-    # Escalation
-    FOUNDER_DECISION_NEEDED = "founder_decision_needed"
-    
-    # System
-    BRAIN_INITIALIZED = "brain_initialized"
-    DAILY_DIGEST_GENERATED = "daily_digest_generated"
-    META_OPTIMIZATION_COMPLETE = "meta_optimization_complete"
-    
-    # v0.6.0 DSoR - Federation Events
-    FEDERATION_PEER_JOINED = "federation_peer_joined"
-    FEDERATION_PEER_LEFT = "federation_peer_left"
-    FEDERATION_PEER_SUSPECT = "federation_peer_suspect"
-    FEDERATION_LEADER_ELECTED = "federation_leader_elected"
-    FEDERATION_TASK_ROUTED = "federation_task_routed"
-    FEDERATION_STATE_SYNCED = "federation_state_synced"
-    
-    # v0.6.0 DSoR - Decision Provenance
-    DECISION_MADE = "decision_made"
-    CONTEXT_SNAPSHOT = "context_snapshot"
-    IPC_TOKEN_ISSUED = "ipc_token_issued"
-    IPC_TOKEN_CONSUMED = "ipc_token_consumed"