livepilot 1.20.2 → 1.20.3

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 1.20.3 — Automated analyzer pre-flight (April 24 2026)
+
+Micro-release closing one class of operator error that broke the v1.20.1
+five-project live-test campaign: the LLM operator had a clear memory
+instruction to load `LivePilot_Analyzer` on master at the start of a
+fresh Ableton session but missed it in 5 of 5 projects — producing
+basic mixes instead of the intended mix-polish outcomes because every
+analyzer-gated move (`tighten_low_end`, `sculpt_midrange`,
+`balance_stereo_image`, etc.) silently degraded. Fixed forward with a
+new idempotent pre-flight tool + Director skill wiring.
+
+### Added
+
+**New tool: `ensure_analyzer_on_master`** (`mcp_server/tools/analyzer.py`).
+Idempotent pre-flight that loads `LivePilot_Analyzer.amxd` on master
+when missing, no-ops when already loaded. Returns one of:
+- `already_loaded` (with `is_last_on_master`, `duplicate_count`)
+- `loaded` (first-time load from Ableton browser)
+- `install_required` (device not in browser — actionable hint points at
+  `install_m4l_device`)
+- `failed` (any other error)
+
+Post-load report surfaces the CLAUDE.md invariant "LivePilot_Analyzer
+must be LAST on master" via `is_last_on_master: bool` and warns when
+violated. Duplicate-count warning covers the edge case of multiple
+analyzers on the master chain.
+
+Safe to call every turn — subsequent calls short-circuit via one
+`get_master_track` read. Tool count: 429 → 430. 6 new contract tests
+covering already-loaded, missing-loads, install-required,
+duplicate-handling, is-last warning, and two-call idempotence.
+
+### Changed
+
+**Director Phase 1** (`livepilot-creative-director/SKILL.md`). Added
+`ensure_analyzer_on_master` at the top of the "Ground" reads as a
+REQUIRED call, ahead of `get_session_info`. Wording explicitly connects
+the step to the failure it prevents so future agents don't rationalize
+skipping it: "Skipping it is how the v1.20.1 live-test campaign
+produced basic mixes — the analyzer-gated moves degrade silently when
+there's no master spectrum to read."
+
+### Notes
+
+No breaking changes. Calling code that assumed the analyzer was loaded
+continues to work; the new tool adds an explicit pre-flight path.
+`install_m4l_device` contract unchanged.
+
+---
+
 ## 1.20.2 — 5 bugs + 1 race condition from the live-test campaign (April 24 2026)
 
 Patch release fixing every issue surfaced during the v1.20.1 five-project

package/README.md

@@ -17,7 +17,7 @@
 
 <p align="center">
   An agentic production system for Ableton Live 12.<br>
-  429 tools. 53 domains. Device atlas. Plan-aware Splice integration. Auto-composition. Spectral perception. Technique memory. Drum-rack pad builder. Live dead-device detection.
+  430 tools. 53 domains. Device atlas. Plan-aware Splice integration. Auto-composition. Spectral perception. Technique memory. Drum-rack pad builder. Live dead-device detection.
 </p>
 
 <br>
@@ -80,7 +80,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 │         └─────────────────┼──────────────────┘                       │
 │                           ▼                                          │
 │                  ┌─────────────────┐                                  │
-│                  │   429 MCP Tools  │                                  │
+│                  │   430 MCP Tools  │                                  │
 │                  │   53 domains     │                                  │
 │                  └────────┬────────┘                                  │
 │                           │                                          │
@@ -121,7 +121,7 @@ Most MCP servers are tool collections — they execute commands. LivePilot is an
 
 ## The Intelligence Layer
 
-12 engines sit on top of the 429 tools. They give the AI musical judgment, not just musical execution.
+12 engines sit on top of the 430 tools. They give the AI musical judgment, not just musical execution.
 
 ### SongBrain — What the Song Is
 
@@ -173,7 +173,7 @@ Every engine follows: **measure before → act → measure after → compare**.
 
 ## Tools
 
-429 tools across 53 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
+430 tools across 53 domains. Highlights below — [full catalog here](docs/manual/tool-catalog.md).
 
 <br>
 
@@ -362,7 +362,7 @@ The V2 intelligence layer. These tools analyze, diagnose, plan, evaluate, and le
 | Creative Constraints | 5 | constraint activation, reference-inspired variants |
 | Preview Studio | 5 | variant creation, preview rendering, comparison, commit |
 
-> **[View all 429 tools →](docs/manual/tool-catalog.md)**
+> **[View all 430 tools →](docs/manual/tool-catalog.md)**
 
 <br>
 
@@ -589,7 +589,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for architecture details, code guidelines
 
 | Document | What's inside |
 |----------|---------------|
-| [Manual](docs/manual/index.md) | Complete reference: architecture, all 429 tools, workflows |
+| [Manual](docs/manual/index.md) | Complete reference: architecture, all 430 tools, workflows |
 | [Intelligence Layer](docs/manual/intelligence.md) | How the 12 engines connect — conductor, moves, preview, evaluation |
 | [Device Atlas](docs/manual/device-atlas.md) | 1305 devices indexed — search, suggest, chain building |
 | [Samples & Slicing](docs/manual/samples.md) | 3-source search, fitness critics, slice workflows |

package/m4l_device/livepilot_bridge.js

@@ -34,7 +34,7 @@ outlets = 2; // 0: to udpsend (responses), 1: to buffer~/status
 // Single source of truth for the bridge version — bumped alongside the
 // rest of the release manifest. Surfaced in the UI via messnamed("livepilot_version", ...)
 // so the frozen .amxd visibly reports which build it was last exported from.
-var VERSION = "1.20.2";
+var VERSION = "1.20.3";
 
 // ── State ──────────────────────────────────────────────────────────────────
 

package/mcp_server/__init__.py

@@ -1,2 +1,2 @@
 """LivePilot MCP Server — bridges MCP protocol to Ableton Live."""
-__version__ = "1.20.2"
+__version__ = "1.20.3"

package/mcp_server/tools/analyzer.py

@@ -1913,3 +1913,128 @@ async def compressor_set_sidechain(
         params["source_channel"] = str(source_channel)
     ableton = ctx.lifespan_context["ableton"]
     return ableton.send_command("set_compressor_sidechain", params)
+
+
+# ──────────────────────────────────────────────────────────────────────
+# v1.20.3 — ensure_analyzer_on_master
+#
+# Motivated by the v1.20.1 live-test campaign operator-error (see
+# ~/Desktop/DREAM AI/demo Project/REPORT.md). The LLM operator had a
+# clear global-memory instruction to load LivePilot_Analyzer on master
+# proactively on a fresh session, and missed it — leaving analyzer-
+# gated moves brittle. This tool closes that class of error by making
+# the load idempotent + automatable.
+
+_ANALYZER_DEVICE_NAME = "LivePilot_Analyzer"
+
+
+def _load_analyzer_impl(ctx, track_index: int, device_name: str,
+                        allow_duplicate: bool = False) -> dict:
+    """Indirection so tests can monkeypatch the load call without having
+    to fake the full find_and_load_device MCP-tool machinery. Production
+    calls straight through to the existing tool."""
+    from .devices import find_and_load_device
+    return find_and_load_device(
+        ctx,
+        track_index=track_index,
+        device_name=device_name,
+        allow_duplicate=allow_duplicate,
+    )
+
+
+@mcp.tool()
+def ensure_analyzer_on_master(ctx: Context) -> dict:
+    """Idempotent pre-flight: load LivePilot_Analyzer on master if missing.
+
+    Safe to call at the start of any session or before any move that
+    declares analyzer dependency. Calling it repeatedly is cheap —
+    subsequent calls short-circuit via a single get_master_track read.
+
+    CLAUDE.md invariant: "LivePilot_Analyzer must be LAST on master."
+    This tool reports whether the invariant holds via ``is_last_on_master``;
+    it does NOT move the device (that's a user action in Ableton's GUI).
+
+    Return shape:
+    - status: one of {"already_loaded", "loaded", "install_required", "failed"}
+    - device_index: int  — position of the analyzer on master (when present)
+    - is_last_on_master: bool — True when analyzer is the last device
+    - duplicate_count: int — 2+ when multiple analyzers exist (shouldn't)
+    - warning: str | None — surfaces last-on-master violations
+    - hint: str — actionable next step when status != "already_loaded"/"loaded"
+    - error: str | None — present on status="failed"
+    """
+    ableton = ctx.lifespan_context["ableton"]
+
+    # 1. Inspect the master chain for an existing analyzer.
+    try:
+        master = ableton.send_command("get_master_track")
+    except Exception as exc:
+        return {
+            "status": "failed",
+            "error": f"Could not read master track: {exc}",
+            "hint": "Verify MCP connection to Ableton; retry with get_session_info first.",
+        }
+
+    devices = (master or {}).get("devices") or []
+    matches = [d for d in devices if d.get("name") == _ANALYZER_DEVICE_NAME]
+
+    if matches:
+        # 2. Already loaded — build a status report without side effects.
+        first = matches[0]
+        device_index = first.get("index")
+        is_last = False
+        if devices:
+            last_name = devices[-1].get("name")
+            is_last = (last_name == _ANALYZER_DEVICE_NAME)
+
+        result: dict = {
+            "status": "already_loaded",
+            "device_index": device_index,
+            "is_last_on_master": is_last,
+            "duplicate_count": len(matches),
+        }
+        if len(matches) > 1:
+            result["warning"] = (
+                f"{len(matches)} instances of {_ANALYZER_DEVICE_NAME} on master — "
+                "only one is needed. Remove extras in Ableton's GUI."
+            )
+        elif not is_last:
+            result["warning"] = (
+                f"{_ANALYZER_DEVICE_NAME} is not the LAST device on master. "
+                "CLAUDE.md invariant requires it to come after ALL effects so "
+                "it reads the final output, not pre-effect signal. "
+                "Move it to the end of the master chain in Ableton's GUI."
+            )
+        return result
+
+    # 3. Not on master — try loading from the Ableton browser.
+    try:
+        loaded = _load_analyzer_impl(
+            ctx,
+            track_index=-1000,  # master convention
+            device_name=_ANALYZER_DEVICE_NAME,
+            allow_duplicate=False,
+        )
+    except Exception as exc:
+        # Typical path: device not in browser (user hasn't installed via
+        # install_m4l_device yet).
+        return {
+            "status": "install_required",
+            "error": str(exc),
+            "hint": (
+                "LivePilot_Analyzer not found in Ableton's browser. Install "
+                "first with install_m4l_device(source_path="
+                "\"<repo>/m4l_device/LivePilot_Analyzer.amxd\") — that copies "
+                "the .amxd into ~/Music/Ableton/User Library/Presets/Audio "
+                "Effects/Max Audio Effect/. Then call ensure_analyzer_on_master "
+                "again to complete the load."
+            ),
+        }
+
+    device_index = (loaded or {}).get("device_index")
+    return {
+        "status": "loaded",
+        "device_index": device_index,
+        "is_last_on_master": True,  # fresh load always lands at the end
+        "duplicate_count": 1,
+    }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "livepilot",
-  "version": "1.20.2",
+  "version": "1.20.3",
   "mcpName": "io.github.dreamrec/livepilot",
-  "description": "Agentic production system for Ableton Live 12 — 429 tools, 53 domains. Device atlas (1305 devices), sample engine (Splice + browser + filesystem), auto-composition, spectral perception, technique memory, creative intelligence (12 engines)",
+  "description": "Agentic production system for Ableton Live 12 — 430 tools, 53 domains. Device atlas (1305 devices), sample engine (Splice + browser + filesystem), auto-composition, spectral perception, technique memory, creative intelligence (12 engines)",
   "author": "Pilot Studio",
   "license": "BSL-1.1",
   "type": "commonjs",

package/remote_script/LivePilot/__init__.py

@@ -5,7 +5,7 @@ Entry point for the ControlSurface. Ableton calls create_instance(c_instance)
 when this script is selected in Preferences > Link, Tempo & MIDI.
 """
 
-__version__ = "1.20.2"
+__version__ = "1.20.3"
 
 from _Framework.ControlSurface import ControlSurface
 from . import router

package/server.json

@@ -1,17 +1,17 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.dreamrec/livepilot",
-  "description": "429-tool agentic MCP production system for Ableton Live 12 — device atlas, sample engine, composer",
+  "description": "430-tool agentic MCP production system for Ableton Live 12 — device atlas, sample engine, composer",
   "repository": {
     "url": "https://github.com/dreamrec/LivePilot",
     "source": "github"
   },
-  "version": "1.20.2",
+  "version": "1.20.3",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "livepilot",
-      "version": "1.20.2",
+      "version": "1.20.3",
       "transport": {
         "type": "stdio"
       }