livepilot 1.9.21 → 1.9.23

package/mcp_server/stuckness_detector/models.py

@@ -0,0 +1,66 @@
+"""Stuckness Detector data models — pure dataclasses, zero I/O."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+
+
+RESCUE_TYPES = [
+    "contrast_needed",
+    "section_missing",
+    "hook_underdeveloped",
+    "transition_not_earned",
+    "overpolished_loop",
+    "identity_unclear",
+    "too_dense_to_progress",
+    "too_safe_to_progress",
+]
+
+
+@dataclass
+class StucknessSignal:
+    """A single signal contributing to stuckness detection."""
+
+    signal_type: str = ""  # "repeated_undo", "local_tweaking", "long_loop", etc.
+    strength: float = 0.0  # 0-1
+    evidence: str = ""
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class StucknessReport:
+    """Full stuckness analysis for a session."""
+
+    confidence: float = 0.0  # 0-1 how stuck the session is
+    level: str = "flowing"  # "flowing", "slowing", "stuck", "deeply_stuck"
+    signals: list[StucknessSignal] = field(default_factory=list)
+    diagnosis: str = ""
+    primary_rescue_type: str = ""
+    secondary_rescue_types: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "confidence": round(self.confidence, 3),
+            "level": self.level,
+            "signals": [s.to_dict() for s in self.signals],
+            "diagnosis": self.diagnosis,
+            "primary_rescue_type": self.primary_rescue_type,
+            "secondary_rescue_types": self.secondary_rescue_types,
+        }
+
+
+@dataclass
+class RescueSuggestion:
+    """A momentum rescue suggestion."""
+
+    rescue_type: str = ""
+    title: str = ""
+    description: str = ""
+    urgency: str = "medium"  # "low", "medium", "high"
+    strategies: list[str] = field(default_factory=list)
+    identity_effect: str = "preserves"
+
+    def to_dict(self) -> dict:
+        return asdict(self)

package/mcp_server/stuckness_detector/tools.py

@@ -0,0 +1,195 @@
+"""Stuckness Detector MCP tools — 3 tools for momentum rescue.
+
+  detect_stuckness — identify whether the session is losing momentum
+  suggest_momentum_rescue — get strategic rescue suggestions
+  start_rescue_workflow — structured step-by-step rescue for a stuckness type
+"""
+
+from __future__ import annotations
+
+from fastmcp import Context
+
+from ..server import mcp
+from . import detector
+
+
+def _get_ableton(ctx: Context):
+    return ctx.lifespan_context["ableton"]
+
+
+def _get_action_history(ctx: Context) -> list[dict]:
+    """Get recent action history from the session-scoped action ledger.
+
+    Returns move entries as dicts for stuckness pattern analysis:
+    repeated undos, local-tweaking, loop-without-structure detection.
+    Falls back to empty list when no ledger data exists (graceful degradation).
+    """
+    try:
+        from ..runtime.action_ledger import SessionLedger
+        ledger = ctx.lifespan_context.get("action_ledger")
+        if isinstance(ledger, SessionLedger):
+            recent = ledger.get_recent_moves(limit=20)
+            return [e.to_dict() for e in recent]
+    except Exception:
+        pass
+    return []
+
+
+def _get_session_and_brain(ctx: Context) -> tuple[dict, dict, int]:
+    """Fetch session info, song brain, and section count."""
+    ableton = _get_ableton(ctx)
+    session_info: dict = {}
+    song_brain: dict = {}
+    section_count = 0
+
+    try:
+        session_info = ableton.send_command("get_session_info", {})
+        section_count = session_info.get("scene_count", 0)
+    except Exception:
+        pass
+
+    try:
+        from ..song_brain.tools import _current_brain
+        if _current_brain is not None:
+            song_brain = _current_brain.to_dict()
+    except Exception as _e:
+        if __debug__:
+            import sys
+            print(f"LivePilot: SongBrain unavailable in stuckness_detector: {_e}", file=sys.stderr)
+
+    return session_info, song_brain, section_count
+
+
+@mcp.tool()
+def detect_stuckness(ctx: Context) -> dict:
+    """Detect whether the session is losing momentum.
+
+    Analyzes action history for stuckness signals:
+    - repeated undos
+    - many low-impact parameter changes in one area
+    - long loop time with no structural edits
+    - repeated requests without acceptance
+    - too many decorative layers without role clarity
+    - unclear song identity
+
+    Returns confidence level, diagnosis, and recommended rescue type.
+    Use this proactively when the user seems to be going in circles.
+    """
+    history = _get_action_history(ctx)
+    session_info, song_brain, section_count = _get_session_and_brain(ctx)
+
+    report = detector.detect_stuckness(
+        action_history=history,
+        session_info=session_info,
+        song_brain=song_brain,
+        section_count=section_count,
+    )
+
+    return report.to_dict()
+
+
+@mcp.tool()
+def suggest_momentum_rescue(
+    ctx: Context,
+    mode: str = "gentle",
+) -> dict:
+    """Suggest strategic moves to restore session momentum.
+
+    First detects stuckness, then generates rescue suggestions.
+    In "gentle" mode, provides the top suggestion. In "direct" mode,
+    provides up to 3 rescue strategies.
+
+    mode: "gentle" (one suggestion) or "direct" (up to 3 suggestions)
+
+    Returns rescue suggestions with strategies and identity effects.
+    """
+    if mode not in ("gentle", "direct"):
+        mode = "gentle"
+
+    history = _get_action_history(ctx)
+    session_info, song_brain, section_count = _get_session_and_brain(ctx)
+
+    report = detector.detect_stuckness(
+        action_history=history,
+        session_info=session_info,
+        song_brain=song_brain,
+        section_count=section_count,
+    )
+
+    if report.level == "flowing":
+        return {
+            "stuckness": report.to_dict(),
+            "note": "Session is flowing well — no rescue needed",
+            "suggestions": [],
+        }
+
+    suggestions = detector.suggest_rescue(report, mode)
+
+    return {
+        "stuckness": report.to_dict(),
+        "suggestions": [s.to_dict() for s in suggestions],
+        "suggestion_count": len(suggestions),
+    }
+
+
+@mcp.tool()
+def start_rescue_workflow(
+    ctx: Context,
+    rescue_type: str = "",
+    kernel_id: str = "",
+) -> dict:
+    """Start a structured rescue workflow for a specific stuckness type.
+
+    Provides a step-by-step action plan to restore session momentum.
+    Each rescue type has targeted strategies with identity-preserving defaults.
+
+    rescue_type: one of "contrast_needed", "section_missing",
+                 "hook_underdeveloped", "transition_not_earned",
+                 "overpolished_loop", "identity_unclear",
+                 "too_dense_to_progress", "too_safe_to_progress"
+    kernel_id: optional session kernel reference
+    """
+    from .models import RESCUE_TYPES
+
+    if not rescue_type:
+        return {
+            "error": "rescue_type is required",
+            "available_types": RESCUE_TYPES,
+        }
+
+    if rescue_type not in RESCUE_TYPES:
+        return {
+            "error": f"Unknown rescue type: {rescue_type}",
+            "available_types": RESCUE_TYPES,
+        }
+
+    # Build a rescue suggestion for this specific type
+    from .models import StucknessReport
+    report = StucknessReport(
+        confidence=0.6,
+        level="stuck",
+        primary_rescue_type=rescue_type,
+        secondary_rescue_types=[],
+    )
+    suggestions = detector.suggest_rescue(report, mode="direct")
+
+    if not suggestions:
+        return {"error": f"No rescue strategies available for {rescue_type}"}
+
+    rescue = suggestions[0]
+
+    # Build workflow steps from strategies
+    steps = [
+        {"step": i + 1, "action": strategy, "done": False}
+        for i, strategy in enumerate(rescue.strategies)
+    ]
+
+    return {
+        "rescue_type": rescue_type,
+        "title": rescue.title,
+        "description": rescue.description,
+        "steps": steps,
+        "identity_effect": rescue.identity_effect,
+        "urgency": rescue.urgency,
+        "note": "Complete steps in order. Each step should be followed by evaluation.",
+    }

package/mcp_server/tools/_conductor.py

@@ -39,6 +39,12 @@ class ConductorPlan:
     notes: list[str] = field(default_factory=list)
     budget: Optional[dict] = None
 
+    # V2 additions
+    semantic_moves: list[dict] = field(default_factory=list)
+    workflow_mode: str = "guided_workflow"  # quick_fix | guided_workflow | agentic_loop | creative_search | performance_safe
+    use_session_kernel: bool = True
+    experiment_recommended: bool = False
+
     def to_dict(self) -> dict:
         result = {
             "request": self.request,
@@ -48,6 +54,10 @@ class ConductorPlan:
             "primary_engine": self.routes[0].engine if self.routes else None,
             "capability_requirements": self.capability_requirements,
             "notes": self.notes,
+            "semantic_moves": self.semantic_moves,
+            "workflow_mode": self.workflow_mode,
+            "use_session_kernel": self.use_session_kernel,
+            "experiment_recommended": self.experiment_recommended,
         }
         if self.budget is not None:
             result["budget"] = self.budget
@@ -103,6 +113,65 @@ _ROUTING_PATTERNS: list[tuple[str, str, str, str, list[str]]] = [
 ]
 
 
+def _find_matching_semantic_moves(request_lower: str) -> list[dict]:
+    """Search the semantic move registry for moves matching the request."""
+    try:
+        from ..semantic_moves.registry import _REGISTRY
+    except ImportError:
+        return []
+
+    matches = []
+    request_words = set(request_lower.split())
+
+    for move in _REGISTRY.values():
+        score = 0.0
+        move_words = set(move.move_id.replace("_", " ").split())
+        intent_words = set(move.intent.lower().split())
+
+        # Word overlap
+        overlap = request_words & (move_words | intent_words)
+        score += len(overlap) * 0.3
+
+        # Dimension keyword matching
+        for dim in move.targets:
+            if dim in request_lower:
+                score += 0.2
+
+        # Direct ID match
+        if move.move_id.replace("_", " ") in request_lower:
+            score += 1.0
+
+        if score > 0.1:
+            d = move.to_dict()
+            d["match_score"] = round(score, 3)
+            matches.append(d)
+
+    matches.sort(key=lambda x: -x["match_score"])
+    return matches[:3]
+
+
+def _infer_workflow_mode(request_lower: str) -> str:
+    """Infer the appropriate workflow mode from request language."""
+    # Performance-safe keywords
+    if re.search(r"live|perform|safe|set\b|show\b|gig", request_lower):
+        return "performance_safe"
+
+    # Creative search keywords
+    if re.search(r"try|experiment|explore|surprise|option|variant|idea|branch", request_lower):
+        return "creative_search"
+
+    # Quick fix keywords
+    if re.search(r"fix|quick|just|only|undo|revert|simple", request_lower):
+        return "quick_fix"
+
+    # Agentic loop keywords (full autonomous)
+    if re.search(r"autonomous|auto|full|everything|deep|polish|finish", request_lower):
+        return "agentic_loop"
+
+    # Default
+    return "guided_workflow"
+
+
 def classify_request(request: str) -> ConductorPlan:
     """Analyze a production request and route to the right engines.
 
@@ -126,7 +195,15 @@ def classify_request(request: str) -> ConductorPlan:
             engine_scores[engine]["score"] += 1
 
     if not engine_scores:
-        # Default: try Agent OS core loop (general "make it better")
+        # No engine matched — but semantic moves might still apply
+        semantic_moves = _find_matching_semantic_moves(lower)
+        workflow_mode = _infer_workflow_mode(lower)
+        notes = ["General request — Agent OS core loop with goal vector"]
+        if semantic_moves:
+            notes.append(
+                f"Semantic moves available: {', '.join(m['move_id'] for m in semantic_moves[:3])}. "
+                "Use apply_semantic_move for intent-level execution."
+            )
         return ConductorPlan(
             request=request,
             request_type="general",
@@ -134,11 +211,14 @@ def classify_request(request: str) -> ConductorPlan:
                 engine="agent_os",
                 priority=1,
                 reason="No specific engine matched — using core Agent OS loop",
-                entry_tool="build_world_model",
-                follow_up_tools=["evaluate_move"],
+                entry_tool="get_session_kernel",
+                follow_up_tools=["propose_next_best_move", "evaluate_move"],
             )],
             capability_requirements=["session_access"],
-            notes=["General request — Agent OS core loop with goal vector"],
+            notes=notes,
+            semantic_moves=semantic_moves,
+            workflow_mode=workflow_mode,
+            experiment_recommended=(workflow_mode == "creative_search"),
         )
 
     # Sort engines by score (most matches = primary)
@@ -165,19 +245,37 @@ def classify_request(request: str) -> ConductorPlan:
     if any(r.engine == "performance_engine" for r in routes):
         caps.append("live_performance_safe")
 
-    # Always suggest starting with Project Brain for complex multi-engine tasks
+    # Notes and guidance
     notes = []
     if len(routes) > 1:
-        notes.append("Multi-engine task — call build_project_brain first for shared state")
+        notes.append("Multi-engine task — start with get_session_kernel for shared state")
     if any(r.engine == "mix_engine" for r in routes):
         notes.append("Mix engine works best with analyzer data — check get_capability_state")
 
+    # V2: Search semantic moves for matching intents
+    semantic_moves = _find_matching_semantic_moves(lower)
+
+    # V2: Infer workflow mode from request language
+    workflow_mode = _infer_workflow_mode(lower)
+
+    # V2: Recommend experiments for exploratory/creative requests
+    experiment_recommended = workflow_mode == "creative_search"
+
+    if semantic_moves:
+        notes.append(
+            f"Semantic moves available: {', '.join(m['move_id'] for m in semantic_moves[:3])}. "
+            "Use apply_semantic_move for intent-level execution."
+        )
+
     return ConductorPlan(
         request=request,
         request_type=primary_type,
         routes=routes,
         capability_requirements=caps,
         notes=notes,
+        semantic_moves=semantic_moves,
+        workflow_mode=workflow_mode,
+        experiment_recommended=experiment_recommended,
     )
 
 

package/mcp_server/tools/analyzer.py

@@ -1,6 +1,6 @@
 """Analyzer MCP tools — real-time spectral analysis and deep LOM access.
 
-29 tools requiring the LivePilot Analyzer M4L device on the master track.
+30 tools requiring the LivePilot Analyzer M4L device on the master track.
 These tools are optional — all core tools work without the device.
 """
 

package/mcp_server/tools/devices.py

@@ -328,6 +328,29 @@ def load_device_by_uri(ctx: Context, track_index: int, uri: str) -> dict:
     return _postflight_loaded_device(ctx, result)
 
 
+@mcp.tool()
+def move_device(
+    ctx: Context,
+    track_index: int,
+    device_index: int,
+    target_index: int,
+    target_track_index: Optional[int] = None,
+) -> dict:
+    """Move a device to a new position on the same or different track.
+    track_index: 0+ for regular tracks, -1/-2/... for return tracks, -1000 for master."""
+    _validate_track_index(track_index)
+    _validate_device_index(device_index)
+    params: dict = {
+        "track_index": track_index,
+        "device_index": device_index,
+        "target_index": target_index,
+    }
+    if target_track_index is not None:
+        _validate_track_index(target_track_index)
+        params["target_track_index"] = target_track_index
+    return _get_ableton(ctx).send_command("move_device", params)
+
+
 @mcp.tool()
 def find_and_load_device(ctx: Context, track_index: int, device_name: str) -> dict:
     """Search the browser for a device by name and load it onto a track.
@@ -335,6 +358,17 @@ def find_and_load_device(ctx: Context, track_index: int, device_name: str) -> di
     _validate_track_index(track_index)
     if not device_name.strip():
         raise ValueError("device_name cannot be empty")
+
+    # Guardrail: bare Drum Rack produces silence (no samples loaded)
+    if device_name.strip().lower() == "drum rack":
+        raise ValueError(
+            "Loading a bare 'Drum Rack' creates an empty rack that produces silence. "
+            "Instead, use search_browser(path='drums') to find a kit preset "
+            "(e.g., '808 Core Kit'), then load it with load_browser_item(). "
+            "Or use DS drum synths (DS Kick, DS Snare, DS HH, DS Tom, DS Clap, "
+            "DS Cymbal) which are self-contained."
+        )
+
     result = _get_ableton(ctx).send_command("find_and_load_device", {
         "track_index": track_index,
         "device_name": device_name,

package/mcp_server/wonder_mode/__init__.py

@@ -0,0 +1,6 @@
+"""Wonder Mode — controlled surprise for creative exploration.
+
+Discovers relevant semantic moves, generates safe / strong / unexpected
+variants with real move differentiation, and ranks by taste + identity +
+novelty + coherence.
+"""

package/mcp_server/wonder_mode/diagnosis.py

@@ -0,0 +1,84 @@
+"""Wonder Mode diagnosis builder — pure computation, zero I/O.
+
+Builds a WonderDiagnosis from stuckness report, SongBrain, action
+ledger, and open creative threads. Each input is optional — the
+builder degrades gracefully.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .session import WonderDiagnosis
+
+
+# ── Problem class -> candidate domains mapping ────────────────────
+
+_DOMAIN_MAP: dict[str, list[str]] = {
+    "overpolished_loop": ["arrangement", "transition"],
+    "identity_unclear": ["sound_design", "mix"],
+    "contrast_needed": ["transition", "arrangement", "sound_design"],
+    "hook_underdeveloped": ["sound_design", "mix"],
+    "too_dense_to_progress": ["mix", "arrangement"],
+    "too_safe_to_progress": ["sound_design", "transition"],
+    "section_missing": ["arrangement", "transition"],
+    "transition_not_earned": ["transition", "arrangement"],
+}
+
+_STUCKNESS_THRESHOLD = 0.2  # Below this, treat as user_request
+
+
+def build_diagnosis(
+    stuckness_report: Optional[dict] = None,
+    song_brain: Optional[dict] = None,
+    action_ledger: Optional[list[dict]] = None,
+) -> WonderDiagnosis:
+    """Build a WonderDiagnosis from available session state.
+
+    Note: open_threads domain prioritization is deferred — not yet implemented.
+    """
+    degraded: list[str] = []
+
+    # 1. Determine trigger reason and problem class from stuckness
+    trigger_reason = "user_request"
+    problem_class = "exploration"
+    confidence = 0.0
+
+    # Check action ledger for repeated undos first
+    if action_ledger:
+        undo_count = sum(1 for a in action_ledger if a.get("kept") is False)
+        if undo_count >= 3:
+            trigger_reason = "repeated_undos"
+
+    if stuckness_report and stuckness_report.get("confidence", 0) >= _STUCKNESS_THRESHOLD:
+        trigger_reason = "stuckness_detected"
+        problem_class = stuckness_report.get("primary_rescue_type", "exploration") or "exploration"
+        confidence = stuckness_report.get("confidence", 0.0)
+
+    # If trigger is repeated_undos but no stuckness, keep problem_class as exploration
+    if trigger_reason == "repeated_undos" and problem_class == "exploration":
+        confidence = max(confidence, 0.3)
+
+    # 2. Read SongBrain
+    current_identity = ""
+    sacred_elements: list[dict] = []
+
+    if song_brain:
+        current_identity = song_brain.get("identity_core", "")
+        sacred_elements = song_brain.get("sacred_elements", [])
+    else:
+        degraded.append("song_brain")
+
+    # 3. Map problem_class to candidate domains
+    candidate_domains = _DOMAIN_MAP.get(problem_class, [])
+
+    return WonderDiagnosis(
+        trigger_reason=trigger_reason,
+        problem_class=problem_class,
+        current_identity=current_identity,
+        sacred_elements=sacred_elements,
+        blocked_dimensions=[],
+        candidate_domains=list(candidate_domains),  # copy
+        confidence=confidence,
+        degraded_capabilities=degraded,
+    )