livepilot 1.9.13 → 1.9.15

package/mcp_server/runtime/action_ledger_models.py

@@ -0,0 +1,84 @@
+"""Data models for the Action Ledger — semantic move tracking.
+
+Classes:
+  LedgerEntry — one semantic move with intent, scope, actions, evaluation
+  UndoGroup   — group of entries sharing an undo scope
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# Module-level counter for auto-generating IDs.
+_counter: int = 0
+
+
+def _next_id() -> str:
+    global _counter
+    _counter += 1
+    return f"move_{_counter:04d}"
+
+
+@dataclass
+class LedgerEntry:
+    """One semantic move in the session ledger."""
+
+    engine: str
+    move_class: str
+    intent: str
+    undo_scope: str = "micro"
+
+    # Auto-generated
+    id: str = field(default_factory=_next_id)
+    timestamp_ms: int = field(default_factory=lambda: int(time.time() * 1000))
+
+    # Scope — which tracks / clips / devices are affected
+    scope: dict = field(default_factory=dict)
+
+    # Low-level tool calls within this move
+    actions: list[dict] = field(default_factory=list)
+
+    # Snapshot references
+    before_refs: dict = field(default_factory=dict)
+    after_refs: dict = field(default_factory=dict)
+
+    # Evaluation
+    evaluation: dict = field(default_factory=dict)
+    kept: Optional[bool] = None
+    score: float = 0.0
+    memory_candidate: bool = False
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "timestamp_ms": self.timestamp_ms,
+            "engine": self.engine,
+            "move_class": self.move_class,
+            "intent": self.intent,
+            "scope": self.scope,
+            "actions": list(self.actions),
+            "before_refs": dict(self.before_refs),
+            "after_refs": dict(self.after_refs),
+            "evaluation": dict(self.evaluation),
+            "kept": self.kept,
+            "score": self.score,
+            "undo_scope": self.undo_scope,
+            "memory_candidate": self.memory_candidate,
+        }
+
+
+@dataclass
+class UndoGroup:
+    """A group of ledger entries sharing an undo scope."""
+
+    scope: str
+    entry_ids: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "scope": self.scope,
+            "entry_ids": list(self.entry_ids),
+        }

package/mcp_server/runtime/action_tools.py

@@ -0,0 +1,57 @@
+"""MCP tool wrappers for the Action Ledger.
+
+Tools:
+  get_action_ledger_summary — recent moves, counts, memory candidates
+  get_last_move             — most recent semantic move
+"""
+
+from __future__ import annotations
+
+from fastmcp import Context
+
+from ..server import mcp
+from .action_ledger import SessionLedger
+
+
+def _get_ledger(ctx: Context) -> SessionLedger:
+    """Return the session-scoped ledger singleton."""
+    return ctx.lifespan_context.setdefault(
+        "action_ledger", SessionLedger()
+    )
+
+
+@mcp.tool()
+def get_action_ledger_summary(
+    ctx: Context, limit: int = 10, engine: str = ""
+) -> dict:
+    """Return a summary of recent semantic moves from the action ledger.
+
+    Includes move count, last move, recent moves (newest first),
+    and number of memory promotion candidates.
+    """
+    ledger = _get_ledger(ctx)
+    eng = engine if engine else None
+    recent = ledger.get_recent_moves(limit=limit, engine=eng)
+    last = ledger.get_last_move()
+    candidates = ledger.get_memory_candidates()
+
+    return {
+        "total_moves": len(ledger._entries),
+        "memory_candidate_count": len(candidates),
+        "last_move": last.to_dict() if last else None,
+        "recent_moves": [e.to_dict() for e in recent],
+    }
+
+
+@mcp.tool()
+def get_last_move(ctx: Context) -> dict:
+    """Return the most recent semantic move from the action ledger.
+
+    Returns the full ledger entry including intent, scope, actions,
+    evaluation, and undo scope.  Returns an empty dict if no moves exist.
+    """
+    ledger = _get_ledger(ctx)
+    entry = ledger.get_last_move()
+    if entry is None:
+        return {}
+    return entry.to_dict()

package/mcp_server/runtime/capability_state.py

@@ -0,0 +1,218 @@
+"""Capability State v1 — unified runtime capability model.
+
+Defines the shared data model that tells engines what can and can't be
+trusted right now.  Pure Python, zero I/O — all probing happens in the
+MCP tool wrapper (runtime/tools.py).
+
+Design: docs/specs/v2-engine-specs/CAPABILITY_STATE_V1.md
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import asdict, dataclass, field
+from typing import Optional
+
+
+# ── Domain Model ────────────────────────────────────────────────────────
+
+@dataclass
+class CapabilityDomain:
+    """A single capability domain's runtime status."""
+
+    name: str
+    available: bool
+    confidence: float  # 0.0–1.0
+    freshness_ms: Optional[int] = None
+    mode: str = "unavailable"
+    reasons: list[str] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if not 0.0 <= self.confidence <= 1.0:
+            raise ValueError(f"confidence must be 0.0–1.0, got {self.confidence}")
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── Capability State ────────────────────────────────────────────────────
+
+@dataclass
+class CapabilityState:
+    """Snapshot of all capability domains at a point in time."""
+
+    generated_at_ms: int
+    overall_mode: str  # normal | measured_degraded | judgment_only | read_only
+    domains: dict[str, CapabilityDomain] = field(default_factory=dict)
+
+    # ── Query helpers ───────────────────────────────────────────────
+
+    def can_use_measured_evaluation(self) -> bool:
+        """True when analyzer data is available and fresh enough to trust."""
+        analyzer = self.domains.get("analyzer")
+        if analyzer is None:
+            return False
+        return analyzer.available and analyzer.confidence >= 0.5
+
+    def can_run_research(self, mode: str = "targeted") -> bool:
+        """Check if the requested research mode is available.
+
+        - 'targeted' — always true if session or memory is up
+        - 'deep' — requires web access
+        """
+        if mode == "targeted":
+            session = self.domains.get("session_access")
+            memory = self.domains.get("memory")
+            if session and session.available:
+                return True
+            if memory and memory.available:
+                return True
+            return False
+
+        if mode == "deep":
+            web = self.domains.get("web")
+            return web is not None and web.available
+
+        return False
+
+    def to_dict(self) -> dict:
+        return {
+            "capability_state": {
+                "generated_at_ms": self.generated_at_ms,
+                "overall_mode": self.overall_mode,
+                "domains": {
+                    name: domain.to_dict()
+                    for name, domain in self.domains.items()
+                },
+            }
+        }
+
+
+# ── Builder ─────────────────────────────────────────────────────────────
+
+def build_capability_state(
+    *,
+    session_ok: bool = False,
+    analyzer_ok: bool = False,
+    analyzer_fresh: bool = False,
+    memory_ok: bool = False,
+    web_ok: bool = False,
+    flucoma_ok: bool = False,
+) -> CapabilityState:
+    """Build a CapabilityState from simple boolean probes.
+
+    Pure function — no I/O.  The caller is responsible for probing
+    Ableton, the analyzer bridge, memory store, etc.
+    """
+    domains: dict[str, CapabilityDomain] = {}
+
+    # ── session_access ──────────────────────────────────────────────
+    session_reasons: list[str] = []
+    if not session_ok:
+        session_reasons.append("session_unreachable")
+    domains["session_access"] = CapabilityDomain(
+        name="session_access",
+        available=session_ok,
+        confidence=1.0 if session_ok else 0.0,
+        mode="healthy" if session_ok else "unavailable",
+        reasons=session_reasons,
+    )
+
+    # ── analyzer ────────────────────────────────────────────────────
+    analyzer_reasons: list[str] = []
+    if not analyzer_ok:
+        analyzer_reasons.append("analyzer_offline")
+    elif not analyzer_fresh:
+        analyzer_reasons.append("analyzer_stale")
+    analyzer_available = analyzer_ok and analyzer_fresh
+    if analyzer_available:
+        analyzer_conf = 0.9
+        analyzer_mode = "measured"
+    elif analyzer_ok:
+        analyzer_conf = 0.4
+        analyzer_mode = "stale"
+    else:
+        analyzer_conf = 0.0
+        analyzer_mode = "unavailable"
+    domains["analyzer"] = CapabilityDomain(
+        name="analyzer",
+        available=analyzer_available,
+        confidence=analyzer_conf,
+        mode=analyzer_mode,
+        reasons=analyzer_reasons,
+    )
+
+    # ── memory ──────────────────────────────────────────────────────
+    memory_reasons: list[str] = []
+    if not memory_ok:
+        memory_reasons.append("memory_unavailable")
+    domains["memory"] = CapabilityDomain(
+        name="memory",
+        available=memory_ok,
+        confidence=1.0 if memory_ok else 0.0,
+        mode="available" if memory_ok else "unavailable",
+        reasons=memory_reasons,
+    )
+
+    # ── web ──────────────────────────────────────────────────────────
+    web_reasons: list[str] = []
+    if not web_ok:
+        web_reasons.append("web_unavailable")
+    domains["web"] = CapabilityDomain(
+        name="web",
+        available=web_ok,
+        confidence=0.7 if web_ok else 0.0,
+        mode="available" if web_ok else "unavailable",
+        reasons=web_reasons,
+    )
+
+    # ── research (composite) ────────────────────────────────────────
+    research_reasons: list[str] = []
+    research_sources = 0
+    if session_ok:
+        research_sources += 1
+    else:
+        research_reasons.append("session_unavailable")
+    if memory_ok:
+        research_sources += 1
+    else:
+        research_reasons.append("memory_unavailable")
+    if web_ok:
+        research_sources += 1
+    else:
+        research_reasons.append("web_unavailable")
+
+    if research_sources >= 3:
+        research_mode = "full"
+        research_conf = 1.0
+    elif research_sources >= 1:
+        research_mode = "targeted_only"
+        research_conf = 0.5 + 0.2 * research_sources
+    else:
+        research_mode = "unavailable"
+        research_conf = 0.0
+
+    domains["research"] = CapabilityDomain(
+        name="research",
+        available=research_sources >= 1,
+        confidence=round(research_conf, 2),
+        mode=research_mode,
+        reasons=research_reasons,
+    )
+
+    # ── Overall mode ────────────────────────────────────────────────
+    if session_ok and analyzer_ok and analyzer_fresh:
+        overall_mode = "normal"
+    elif session_ok and not analyzer_ok:
+        overall_mode = "measured_degraded"
+    elif session_ok:
+        # session_ok, analyzer_ok but not fresh
+        overall_mode = "judgment_only"
+    else:
+        overall_mode = "read_only"
+
+    return CapabilityState(
+        generated_at_ms=int(time.time() * 1000),
+        overall_mode=overall_mode,
+        domains=domains,
+    )

package/mcp_server/runtime/safety_kernel.py

@@ -0,0 +1,339 @@
+"""Safety Kernel — policy enforcement layer for LivePilot.
+
+Pure Python, zero I/O.  Validates proposed actions against policies
+before they execute.  MCP tool wrappers call ``check_action_safety``
+before executing mutations.
+
+Policies
+--------
+* **Blocked** — bulk-destructive operations that are never safe to run
+  automatically (delete_all_tracks, clear_all_automation, …).
+* **Confirm required** — single-item destructive ops where the user
+  should be prompted before proceeding.
+* **Scope check** — mutations affecting more than 5 tracks at once
+  are flagged as *caution*.
+* **Capability gating** — when the runtime is in *read_only* mode,
+  all mutations are blocked.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+from typing import Optional
+
+
+# ── Data types ─────────────────────────────────────────────────────
+
+@dataclass
+class SafetyCheck:
+    """Result of evaluating a proposed action against safety policies."""
+
+    action: str                       # what was proposed
+    allowed: bool                     # can it proceed?
+    risk_level: str                   # "safe", "caution", "blocked"
+    reason: str                       # why blocked / cautioned
+    requires_confirmation: bool       # should we ask the user first?
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+# ── Policy sets ────────────────────────────────────────────────────
+
+BLOCKED_ACTIONS: set[str] = {
+    "delete_all_tracks",
+    "delete_all_clips",
+    "delete_all_scenes",
+    "clear_all_automation",
+    "reset_all_devices",
+}
+
+CONFIRM_REQUIRED_ACTIONS: set[str] = {
+    "delete_track",
+    "delete_clip",
+    "delete_scene",
+    "flatten_track",
+    "replace_simpler_sample",
+}
+
+# Read-only prefixes — any action starting with one of these is a read.
+_READ_ONLY_PREFIXES = (
+    "get_",
+    "analyze_",
+    "identify_",
+    "detect_",
+    "check_",
+    "search_",
+    "compare_",
+    "read_",
+    "classify_",
+    "find_",
+    "walk_",
+    "list_",
+    "export_",
+    "extract_",
+    "build_world_model",
+    "compile_goal_vector",
+    "evaluate_",
+    "memory_list",
+    "memory_get",
+    "memory_recall",
+)
+
+# Explicit safe actions (full list for fast-path lookup).
+SAFE_ACTIONS: set[str] = {
+    "get_session_info",
+    "get_track_info",
+    "get_notes",
+    "get_device_parameters",
+    "get_master_spectrum",
+    "get_master_rms",
+    "get_detected_key",
+    "get_clip_info",
+    "get_scenes_info",
+    "get_arrangement_clips",
+    "get_arrangement_notes",
+    "get_clip_automation",
+    "get_automation_recipes",
+    "get_browser_tree",
+    "get_browser_items",
+    "get_return_tracks",
+    "get_master_track",
+    "get_mix_snapshot",
+    "get_track_routing",
+    "get_track_meters",
+    "get_master_meters",
+    "get_device_info",
+    "get_device_presets",
+    "get_rack_chains",
+    "get_freeze_status",
+    "get_scene_matrix",
+    "get_playing_clips",
+    "get_cue_points",
+    "get_hidden_parameters",
+    "get_automation_state",
+    "get_display_values",
+    "get_warp_markers",
+    "get_clip_file_path",
+    "get_simpler_slices",
+    "get_spectral_shape",
+    "get_mel_spectrum",
+    "get_chroma",
+    "get_onsets",
+    "get_novelty",
+    "get_momentary_loudness",
+    "get_recent_actions",
+    "get_session_diagnostics",
+    "get_plugin_parameters",
+    "get_plugin_presets",
+    "analyze_harmony",
+    "analyze_composition",
+    "analyze_loudness",
+    "analyze_spectrum_offline",
+    "analyze_midi_file",
+    "analyze_for_automation",
+    "analyze_outcomes",
+    "identify_scale",
+    "detect_theory_issues",
+    "compare_to_reference",
+    "read_audio_metadata",
+    "check_flucoma",
+    "search_browser",
+    "classify_progression",
+    "find_voice_leading_path",
+    "walk_device_tree",
+    "build_world_model",
+    "compile_goal_vector",
+    "evaluate_move",
+    "evaluate_composition_move",
+    "memory_list",
+    "memory_get",
+    "memory_recall",
+    "extract_piano_roll",
+    "export_clip_midi",
+    "get_section_graph",
+    "get_phrase_grid",
+    "get_harmony_field",
+    "get_transition_analysis",
+    "get_section_outcomes",
+    "get_motif_graph",
+    "get_technique_card",
+    "get_emotional_arc",
+    "get_style_tactics",
+    "research_technique",
+    "get_capability_state",
+    "get_action_ledger_summary",
+    "get_last_move",
+    "get_taste_profile",
+    "evaluate_with_fabric",
+    "get_anti_preferences",
+    "get_promotion_candidates",
+    "analyze_mix",
+    "get_mix_issues",
+    "get_mix_summary",
+    "get_masking_report",
+    "analyze_sound_design",
+    "get_sound_design_issues",
+    "get_patch_model",
+    "analyze_transition",
+    "score_transition",
+    "build_reference_profile",
+    "analyze_reference_gaps",
+    "check_translation",
+    "get_translation_issues",
+    "get_performance_state",
+    "get_performance_safe_moves",
+    "get_project_brain_summary",
+}
+
+
+# ── Scope limits per capability mode ──────────────────────────────
+
+_MAX_SCOPE: dict[str, dict] = {
+    "normal":             {"max_tracks": 0},        # 0 = unlimited
+    "measured_degraded":  {"max_tracks": 3},
+    "judgment_only":      {"max_tracks": 1},
+    "read_only":          {"max_tracks": 0},        # mutations blocked entirely
+}
+
+_WIDE_SCOPE_THRESHOLD = 5   # tracks
+
+
+# ── Public API ─────────────────────────────────────────────────────
+
+def is_read_only_action(action: str) -> bool:
+    """Return True if *action* is a non-mutating read/query."""
+    if action in SAFE_ACTIONS:
+        return True
+    return action.startswith(_READ_ONLY_PREFIXES)
+
+
+def get_max_safe_scope(capability_mode: str) -> dict:
+    """Return the maximum allowed scope for *capability_mode*.
+
+    Keys:
+      max_tracks — 0 means unlimited.
+    """
+    return dict(_MAX_SCOPE.get(capability_mode, _MAX_SCOPE["normal"]))
+
+
+def check_action_safety(
+    action: str,
+    scope: Optional[dict] = None,
+    capability_state: Optional[dict] = None,
+) -> SafetyCheck:
+    """Validate a proposed action against safety policies.
+
+    Parameters
+    ----------
+    action:
+        Tool / command name (e.g. ``"delete_track"``).
+    scope:
+        Optional dict describing what the action will affect.
+        Recognised key: ``track_count`` (int).
+    capability_state:
+        Optional dict with at least a ``"mode"`` key
+        (``"normal"``, ``"read_only"``, …).
+
+    Returns
+    -------
+    SafetyCheck
+    """
+    scope = scope or {}
+    capability_state = capability_state or {}
+    mode = capability_state.get("mode", "normal")
+
+    # 1. Blocked actions — always refused.
+    if action in BLOCKED_ACTIONS:
+        return SafetyCheck(
+            action=action,
+            allowed=False,
+            risk_level="blocked",
+            reason=f"'{action}' is a bulk-destructive operation and is blocked by policy.",
+            requires_confirmation=False,
+        )
+
+    # 2. Capability gating — read_only blocks all mutations.
+    if mode == "read_only" and not is_read_only_action(action):
+        return SafetyCheck(
+            action=action,
+            allowed=False,
+            risk_level="blocked",
+            reason="System is in read_only mode — mutations are not allowed.",
+            requires_confirmation=False,
+        )
+
+    # 3. Scope-based gating for degraded modes.
+    track_count = scope.get("track_count", 1)
+    max_scope = get_max_safe_scope(mode)
+    max_tracks = max_scope["max_tracks"]
+    if max_tracks > 0 and track_count > max_tracks and not is_read_only_action(action):
+        return SafetyCheck(
+            action=action,
+            allowed=False,
+            risk_level="blocked",
+            reason=(
+                f"Scope ({track_count} tracks) exceeds limit for "
+                f"'{mode}' mode (max {max_tracks})."
+            ),
+            requires_confirmation=False,
+        )
+
+    # 4. Wide-scope caution (normal mode).
+    if track_count > _WIDE_SCOPE_THRESHOLD and not is_read_only_action(action):
+        return SafetyCheck(
+            action=action,
+            allowed=True,
+            risk_level="caution",
+            reason=(
+                f"Action affects {track_count} tracks (> {_WIDE_SCOPE_THRESHOLD}). "
+                "Proceed with caution."
+            ),
+            requires_confirmation=True,
+        )
+
+    # 5. Confirm-required actions.
+    if action in CONFIRM_REQUIRED_ACTIONS:
+        return SafetyCheck(
+            action=action,
+            allowed=True,
+            risk_level="caution",
+            reason=f"'{action}' is destructive — user confirmation recommended.",
+            requires_confirmation=True,
+        )
+
+    # 6. Explicitly safe / read-only.
+    if is_read_only_action(action):
+        return SafetyCheck(
+            action=action,
+            allowed=True,
+            risk_level="safe",
+            reason="Read-only action — always safe.",
+            requires_confirmation=False,
+        )
+
+    # 7. Default — allow but note it's a mutation.
+    return SafetyCheck(
+        action=action,
+        allowed=True,
+        risk_level="safe",
+        reason="Action permitted by policy.",
+        requires_confirmation=False,
+    )
+
+
+def check_batch_safety(actions: list[dict]) -> list[SafetyCheck]:
+    """Check a batch of proposed actions.
+
+    Each element should be a dict with at least an ``"action"`` key,
+    plus optional ``"scope"`` and ``"capability_state"`` keys.
+
+    Returns one :class:`SafetyCheck` per input, in the same order.
+    """
+    results: list[SafetyCheck] = []
+    for entry in actions:
+        action = entry.get("action", "")
+        scope = entry.get("scope")
+        cap = entry.get("capability_state")
+        results.append(check_action_safety(action, scope, cap))
+    return results