livepilot 1.14.1 → 1.15.0-beta

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 1.15.0-beta — Live 12.4 replace_sample native (April 21 2026)
+
+First Live 12.4 beta support release. Adds a native fast path for
+SimplerDevice.replace_sample(path) while preserving 100% backward
+compatibility for 12.0-12.3.x users.
+
+**Tool count**: unchanged at 403.
+**Domain count**: unchanged at 52.
+**Tests**: 2503 passed, 1 skipped, 0 regressions (+13 new from this release).
+
+### Added
+- **Live 12.4 support (beta):** `SimplerDevice.replace_sample(path)` native
+  LOM path is now used automatically on Live 12.4+. Handles empty Simplers —
+  fixes the long-standing workaround documented in
+  `feedback_load_browser_item_is_source_of_truth.md`.
+- New capability tier `"collaborative"` (Live 12.4+) exposed via
+  `LiveVersionCapabilities.capability_tier` and `.has_replace_sample_native`.
+- Remote Script: new `replace_sample_native` handler.
+- MCP server: new `_live_caps(ctx)` helper with lazy version-capability
+  caching on the lifespan context.
+- Registered `replace_sample_native` in `mcp_server/runtime/remote_commands.py`
+  REMOTE_COMMANDS (required by the boundary audit contract).
+
+### Changed
+- `replace_simpler_sample` and `load_sample_to_simpler` now route to the
+  native path when available and fall back to the M4L-bridge path
+  otherwise. Tool signatures, argument names, and return shapes unchanged.
+
+### Backward Compatibility
+- Live 12.0–12.3.x: zero behavior change. All routing still goes through
+  the M4L bridge.
+- Live 12.4+: native path preferred; bridge used only on fallback.
+
+### Verification status
+- Full test suite: 2503 passed, 0 failures.
+- Backward compat on Live 12.4: verified in-session — `replace_simpler_sample`
+  and `load_sample_to_simpler` both work via the bridge path on 12.4 (legacy
+  flow intact).
+- Native E2E on Live 12.4 empty-Simpler case: deferred until the plugin
+  swap activates the worktree's MCP code. Unit tests prove the routing
+  logic and the native handler wiring.
+
 ## 1.14.1 — reload_handlers workflow + device/mixing fixes (April 21 2026)
 
 Patch release that lands the post-1.14.0 audit work: one new diagnostics
@@ -13,7 +55,7 @@ tool, three bug fixes, and a new plugin-sync verification script.
 
 - Replaces the manual "toggle Control Surface in Live → Preferences →
   Link/MIDI" step that every Remote Script edit required. New workflow:
-  after `node installer/install.js`, call `reload_handlers` via the MCP
+  after `npx livepilot --install`, call `reload_handlers` via the MCP
   tool. The Remote Script side uses `pkgutil` + `importlib.reload()` to
   re-fire all `@register` decorators in place in <1s, without dropping
   the MCP TCP connection on port 9878.

package/mcp_server/__init__.py

@@ -1,2 +1,2 @@
 """LivePilot MCP Server — bridges MCP protocol to Ableton Live."""
-__version__ = "1.14.1"
+__version__ = "1.15.0-beta"

package/mcp_server/runtime/live_version.py

@@ -79,8 +79,10 @@ class LiveVersionCapabilities:
 
     @property
     def capability_tier(self) -> str:
-        """Human-readable tier: core | enhanced_arrangement | full_intelligence."""
-        if self._version_tuple >= (12, 3, 0):
+        """Human-readable tier: core | enhanced_arrangement | full_intelligence | collaborative."""
+        if self._version_tuple >= (12, 4, 0):
+            return "collaborative"
+        elif self._version_tuple >= (12, 3, 0):
             return "full_intelligence"
         elif self._version_tuple >= (12, 1, 10):
             return "enhanced_arrangement"

package/mcp_server/runtime/remote_commands.py

@@ -117,6 +117,8 @@ REMOTE_COMMANDS: frozenset[str] = frozenset({
     "get_appointed_device",
     # ping (built-in)
     "ping",
+    # Live 12.4+ native Simpler sample replacement (Collaborative tier)
+    "replace_sample_native",
 })
 
 # M4L bridge commands — routed through TCP but handled by livepilot_bridge.js

package/mcp_server/tools/analyzer.py

@@ -64,6 +64,71 @@ def _enrich_slice_response(response: Optional[dict]) -> Optional[dict]:
     return enriched
 
 
+def _live_caps(ctx):
+    """Read (or lazily compute + cache) LiveVersionCapabilities on the context.
+
+    On first call, queries Ableton via get_session_info and caches the
+    result in ``ctx.lifespan_context["_live_caps"]``. Subsequent calls
+    short-circuit to the cache. If Ableton is unreachable, falls back to
+    12.0.0 (conservative — all new-version gates return False).
+
+    This mirrors the on-demand pattern in
+    mcp_server/runtime/capability_probe.py and avoids adding a startup
+    round-trip to the lifespan.
+    """
+    from mcp_server.runtime.live_version import LiveVersionCapabilities
+
+    lsc = ctx.lifespan_context
+    cached = lsc.get("_live_caps")
+    if cached is not None:
+        return cached
+
+    version_str = "12.0.0"
+    ableton = lsc.get("ableton")
+    if ableton is not None:
+        try:
+            info = ableton.send_command("get_session_info") or {}
+            version_str = info.get("live_version", "12.0.0")
+        except Exception:
+            pass
+
+    caps = LiveVersionCapabilities.from_version_string(version_str)
+    lsc["_live_caps"] = caps
+    return caps
+
+
+async def _try_native_replace_sample(ctx, track_index: int, device_index: int,
+                                      file_path: str):
+    """Attempt the Live 12.4+ native SimplerDevice.replace_sample path.
+
+    Returns the remote-script response dict on success, or None if the
+    native path is unavailable (pre-12.4) or failed (caller should fall
+    back to the M4L-bridge path).
+
+    A native "failure" is any of: gate closed, dispatch exception, non-dict
+    response, error field present, or missing sample_loaded flag.
+    """
+    caps = _live_caps(ctx)
+    if not caps.has_replace_sample_native:
+        return None
+    ableton = ctx.lifespan_context["ableton"]
+    try:
+        resp = ableton.send_command("replace_sample_native", {
+            "track_index": track_index,
+            "device_index": device_index,
+            "file_path": file_path,
+        })
+    except Exception:
+        return None
+    if not isinstance(resp, dict):
+        return None
+    if "error" in resp:
+        return None
+    if not resp.get("sample_loaded"):
+        return None
+    return resp
+
+
 @mcp.tool()
 async def reconnect_bridge(ctx: Context) -> dict:
     """Attempt to reconnect the M4L UDP bridge (port 9880).
@@ -350,12 +415,27 @@ async def replace_simpler_sample(
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
     ableton = ctx.lifespan_context["ableton"]
+
+    # Live 12.4+: prefer the native SimplerDevice.replace_sample path.
+    native = await _try_native_replace_sample(
+        ctx, track_index, device_index, file_path
+    )
+    if native is not None:
+        hygiene = await _simpler_post_load_hygiene(
+            bridge, ableton, track_index, device_index, file_path
+        )
+        if not hygiene.get("verified"):
+            return hygiene
+        result = dict(native)
+        result.update(hygiene)
+        result["method"] = "native_12_4"  # preserved in case hygiene ever adds its own key
+        return result
+
+    # Pre-12.4 fallback: M4L bridge path (unchanged behavior).
     result = await bridge.send_command(
         "replace_simpler_sample", track_index, device_index, file_path
     )
 
-    # Validate the response — the bridge may report success even when the
-    # sample silently failed to load (e.g., empty Simpler, bad path)
     if "error" in result:
         return result
     if not result.get("sample_loaded"):
@@ -364,8 +444,6 @@ async def replace_simpler_sample(
             "has a sample loaded — replace_sample silently fails on empty Simplers."
         }
 
-    # Verify by reading back the device name — guards against the silent
-    # failure mode where the bridge reports success but keeps the placeholder.
     hygiene = await _simpler_post_load_hygiene(
         bridge, ableton, track_index, device_index, file_path
     )
@@ -405,9 +483,39 @@ async def load_sample_to_simpler(
     cache = _get_spectral(ctx)
     _require_analyzer(cache)
     bridge = _get_m4l(ctx)
+    ableton = ctx.lifespan_context["ableton"]
+
+    # Live 12.4+: create an empty Simpler via insert_device, then use the
+    # native replace_sample path. Skips the dummy-sample bootstrap entirely.
+    caps = _live_caps(ctx)
+    if caps.has_replace_sample_native:
+        try:
+            ins = ableton.send_command("insert_device", {
+                "track_index": track_index,
+                "device_name": "Simpler",
+            })
+        except Exception:
+            ins = None
+        if isinstance(ins, dict) and "error" not in ins:
+            actual_device_index = ins.get("device_index", device_index)
+            native = await _try_native_replace_sample(
+                ctx, track_index, actual_device_index, file_path
+            )
+            if native is not None:
+                hygiene = await _simpler_post_load_hygiene(
+                    bridge, ableton, track_index, actual_device_index, file_path
+                )
+                if not hygiene.get("verified"):
+                    return hygiene
+                result = dict(native)
+                result.update(hygiene)
+                result["method"] = "native_12_4"
+                result["device_index"] = actual_device_index
+                result["track_index"] = track_index
+                return result
+        # Fall through to the legacy bootstrap path below on any failure.
 
     # Step 1: Load a sample from the browser to create Simpler with content
-    ableton = ctx.lifespan_context["ableton"]
     try:
         search = ableton.send_command("search_browser", {
             "path": "samples",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livepilot",
-  "version": "1.14.1",
+  "version": "1.15.0-beta",
   "mcpName": "io.github.dreamrec/livepilot",
   "description": "Agentic production system for Ableton Live 12 — 403 tools, 52 domains. Device atlas (1305 devices), sample engine (Splice + browser + filesystem), auto-composition, spectral perception, technique memory, creative intelligence (12 engines)",
   "author": "Pilot Studio",

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.14.1"
+__version__ = "1.15.0-beta"
 
 from _Framework.ControlSurface import ControlSurface
 from . import router
@@ -26,6 +26,7 @@ from . import follow_actions    # noqa: F401  — registers follow action handle
 from . import grooves           # noqa: F401  — registers groove pool handlers (11+)
 from . import take_lanes        # noqa: F401  — registers take lane handlers (12.0+ read, 12.2+ write)
 from . import clip_automation   # noqa: F401  — registers clip automation handlers
+from . import simpler_sample    # noqa: F401  — registers replace_sample_native (12.4+)
 from . import version_detect    # noqa: F401  — version detection
 
 

package/remote_script/LivePilot/simpler_sample.py

@@ -0,0 +1,98 @@
+# remote_script/LivePilot/simpler_sample.py
+"""
+LivePilot — Simpler sample replacement via the native Live 12.4 LOM API.
+
+Exposes a ``replace_sample_native`` command that calls
+``SimplerDevice.replace_sample(absolute_path)`` directly on the main thread.
+Unlike the M4L-bridge path, this handler works on empty Simplers (the whole
+reason 12.4 added the native API) and does not require a Max for Live
+device in the Set.
+
+Version-gated on ``replace_sample_native`` (12.4.0+). On earlier versions
+the handler returns a STATE_ERROR; callers (MCP tools) are expected to
+fall back to the bridge path.
+"""
+
+from .router import register
+from .version_detect import has_feature, version_string
+
+
+@register("replace_sample_native")
+def replace_sample_native(song, params):
+    """Replace the sample in a Simpler device using the Live 12.4+ native API.
+
+    params dict keys:
+        track_index (int): 0-based index into song.tracks.
+        device_index (int): 0-based index into the track's devices.
+        file_path (str): absolute path to the audio file to load.
+
+    Returns on success:
+        sample_loaded (bool): True.
+        track_index (int): echoed from input.
+        device_index (int): echoed from input.
+        method (str): "native_12_4".
+        live_version (str): detected Live version at call time.
+
+    Returns on error:
+        error (str): human-readable message.
+        code (str): STATE_ERROR | INDEX_ERROR | INVALID_PARAM | INTERNAL.
+    """
+    if not has_feature("replace_sample_native"):
+        return {
+            "error": (
+                "replace_sample_native requires Live 12.4+. "
+                "Detected: " + version_string() + ". "
+                "Use the M4L-bridge replace_simpler_sample path instead."
+            ),
+            "code": "STATE_ERROR",
+        }
+
+    try:
+        track_index = int(params["track_index"])
+        device_index = int(params["device_index"])
+        file_path = str(params["file_path"])
+    except (KeyError, TypeError, ValueError) as exc:
+        return {
+            "error": "Invalid params: " + str(exc),
+            "code": "INVALID_PARAM",
+        }
+
+    tracks = list(song.tracks)
+    if track_index < 0 or track_index >= len(tracks):
+        return {
+            "error": "track_index " + str(track_index) + " out of range",
+            "code": "INDEX_ERROR",
+        }
+
+    track = tracks[track_index]
+    devices = list(track.devices)
+    if device_index < 0 or device_index >= len(devices):
+        return {
+            "error": "device_index " + str(device_index) + " out of range",
+            "code": "INDEX_ERROR",
+        }
+
+    device = devices[device_index]
+    class_name = getattr(device, "class_name", "")
+    if class_name != "SimplerDevice":
+        return {
+            "error": "Device at [" + str(track_index) + "][" + str(device_index) + "] is "
+                     + class_name + ", not Simpler",
+            "code": "INVALID_PARAM",
+        }
+
+    try:
+        device.replace_sample(file_path)
+    except Exception as exc:
+        return {
+            "error": "SimplerDevice.replace_sample failed: " + str(exc),
+            "code": "INTERNAL",
+        }
+
+    return {
+        "sample_loaded": True,
+        "track_index": track_index,
+        "device_index": device_index,
+        "method": "native_12_4",
+        "live_version": version_string(),
+    }

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/dreamrec/LivePilot",
     "source": "github"
   },
-  "version": "1.14.1",
+  "version": "1.15.0-beta",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "livepilot",
-      "version": "1.14.1",
+      "version": "1.15.0-beta",
       "transport": {
         "type": "stdio"
       }