livepilot 1.20.2 → 1.21.0

package/mcp_server/affordances/devices/auto-filter.yaml

@@ -0,0 +1,14 @@
+device_slug: auto-filter
+device_class_name: AutoFilter2
+presets:
+  slow-sweep:
+    description: >
+      Slow LFO sweep for return chains. Synced rate (bar-long), moderate
+      resonance, low-pass type. Layers well with dub-cathedral reverb.
+    param_overrides:
+      Filter Type: 0            # LP
+      LFO Amount: 0.60
+      LFO Sync: 1
+      LFO Rate: 4               # bar-long sweep
+      Resonance: 0.25
+    suggested_pairings: ["Echo", "Reverb"]

package/mcp_server/affordances/devices/delay.yaml

@@ -0,0 +1,18 @@
+device_slug: delay
+device_class_name: Delay
+presets:
+  ping-pong-dub:
+    description: >
+      Dotted-eighth ping-pong for dub-techno sends. Moderate feedback,
+      high wet, HP+LP filtered to stay out of the kick's sub and the
+      vocal's top end.
+    param_overrides:
+      Sync: 1
+      16th Note: 6              # dotted 8th
+      Feedback: 0.45
+      Filter On: 1
+      HP Freq: 0.20             # ~100 Hz cut below
+      LP Freq: 0.65             # mid-top rolloff
+      Dry/Wet: 0.55
+    risk_notes: "Feedback above 0.6 self-oscillates; keep the return track's output watchable."
+    suggested_pairings: ["Auto Filter", "Saturator"]

package/mcp_server/affordances/devices/reverb.yaml

@@ -0,0 +1,16 @@
+device_slug: reverb
+device_class_name: Reverb
+presets:
+  dub-cathedral:
+    description: >
+      Basic Channel-adjacent huge-space reverb. Long decay, large room,
+      noticeable predelay, high diffusion. Pairs well with Echo + Auto
+      Filter on a return chain for dub-techno sends.
+    param_overrides:
+      Decay Time: 0.85
+      Room Size: 0.95
+      Dry/Wet: 0.40
+      Predelay: 0.45
+      Diffusion: 0.80
+    risk_notes: "Long decay masks transients; avoid routing percussion here."
+    suggested_pairings: ["Echo", "Auto Filter"]

package/mcp_server/affordances/presets.py

@@ -0,0 +1,74 @@
+"""Preset loader for affordance-device YAML files.
+
+Runtime resolution only — schema validation lives in ``_schema.py`` and
+fires at test-time. The loader is tolerant of malformed files (returns
+None rather than raising) so production code never crashes on a bad
+preset; the schema validator catches those pre-ship.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+
+
+_AFFORDANCES_ROOT = Path(__file__).parent / "devices"
+
+
+def _load_device_yaml(device_slug: str) -> Optional[dict]:
+    """Load and parse a device's YAML file. Returns None on any error."""
+    path = _AFFORDANCES_ROOT / f"{device_slug}.yaml"
+    if not path.exists():
+        return None
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError:
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def resolve_preset(device_slug: str, preset_name: str) -> Optional[dict[str, Any]]:
+    """Return the ``param_overrides`` dict for a named preset, or None.
+
+    Returns None on: missing device file, missing preset, unparseable YAML,
+    or a preset record without ``param_overrides``.
+    """
+    data = _load_device_yaml(device_slug)
+    if data is None:
+        return None
+    preset = data.get("presets", {}).get(preset_name)
+    if not isinstance(preset, dict):
+        return None
+    overrides = preset.get("param_overrides")
+    return dict(overrides) if isinstance(overrides, dict) else None
+
+
+def get_preset_metadata(device_slug: str, preset_name: str) -> Optional[dict]:
+    """Return the full preset record (description + pairings + risk_notes
+    + param_overrides) or None."""
+    data = _load_device_yaml(device_slug)
+    if data is None:
+        return None
+    preset = data.get("presets", {}).get(preset_name)
+    return dict(preset) if isinstance(preset, dict) else None
+
+
+def list_devices() -> list[str]:
+    """Return device slugs with available preset files, sorted."""
+    if not _AFFORDANCES_ROOT.exists():
+        return []
+    return sorted(p.stem for p in _AFFORDANCES_ROOT.glob("*.yaml"))
+
+
+def list_presets(device_slug: str) -> list[str]:
+    """Return preset names for a given device slug, sorted. Empty list
+    on missing device or malformed YAML."""
+    data = _load_device_yaml(device_slug)
+    if data is None:
+        return []
+    presets = data.get("presets", {})
+    if not isinstance(presets, dict):
+        return []
+    return sorted(presets.keys())

package/mcp_server/experiment/tools.py

@@ -630,6 +630,54 @@ def compare_experiments(
     }
 
 
+# v1.21: helpers for commit_experiment's ledger-write block. Mirrors the
+# v1.20 apply_semantic_move pattern (commit 0b3489b) — both writers feed
+# the same SessionLedger, so anti-repetition filters downstream see a
+# unified recency log regardless of which surface executed the move.
+
+_TOOL_TO_FAMILY: dict[str, str] = {
+    # Minimal first-step-tool → family mapping. Used only when a branch
+    # lacks an explicit seed.family. Uncovered tools fall through to
+    # default "mix" (same safe default apply_semantic_move would use).
+    "set_track_volume": "mix",
+    "set_track_pan": "mix",
+    "set_track_send": "mix",
+    "set_device_parameter": "sound_design",
+    "batch_set_parameters": "sound_design",
+    "create_clip": "arrangement",
+    "add_notes": "arrangement",
+    "create_scene": "arrangement",
+    "set_scene_tempo": "arrangement",
+    "create_midi_track": "arrangement",
+    "find_and_load_device": "device_creation",
+    "generate_m4l_effect": "device_creation",
+    "apply_gesture_template": "transition",
+    "set_track_arm": "performance",
+    "load_sample_to_simpler": "sample",
+}
+
+
+def _infer_move_family(target) -> str:
+    """Determine move_class for a commit_experiment ledger entry.
+
+    Priority:
+      1. ``target.seed.family`` — explicit seed classification.
+      2. First compiled_plan step's tool via _TOOL_TO_FAMILY lookup.
+      3. Default "mix" — safe fallback.
+    """
+    seed = getattr(target, "seed", None)
+    if seed is not None and getattr(seed, "family", None):
+        return seed.family
+
+    plan = getattr(target, "compiled_plan", None) or {}
+    steps = plan.get("steps", []) or []
+    if steps:
+        first_tool = steps[0].get("tool", "")
+        return _TOOL_TO_FAMILY.get(first_tool, "mix")
+
+    return "mix"
+
+
 @mcp.tool()
 async def commit_experiment(
     ctx: Context,
@@ -759,6 +807,65 @@ async def commit_experiment(
         ctx=ctx,
     )
 
+    # v1.21: write the committed experiment to the SessionLedger so
+    # get_last_move / anti-repetition can see it. Best-effort — a
+    # ledger write failure is logged but does not fail the commit.
+    ledger_entry_id: Optional[str] = None
+    if isinstance(commit_result, dict) and commit_result.get("committed") is True:
+        try:
+            # store_purpose: writer (v1.21 commit_experiment auto-ledger
+            # write; shape mirrors apply_semantic_move commit 0b3489b).
+            from ..runtime.action_ledger import SessionLedger
+            ledger = ctx.lifespan_context.setdefault(
+                "action_ledger", SessionLedger()
+            )
+            # Engine tag reflects branch SOURCE (not escalation success).
+            # A composer-sourced branch that fell back to scaffold is still
+            # a composer-engine commit; the escalation-success detail is
+            # captured in target.evaluation["composer_escalation"], and
+            # doubling up on the engine tag would be noise for the
+            # anti-repetition filters downstream.
+            engine_tag = (
+                "composer"
+                if (
+                    target.seed is not None
+                    and target.seed.source == "composer"
+                )
+                else "experiment"
+            )
+            move_class = _infer_move_family(target)
+            ledger_entry_id = ledger.start_move(
+                engine=engine_tag,
+                move_class=move_class,
+                intent=(
+                    f"{experiment_id}/{branch_id}: "
+                    f"{target.name or 'committed winner'}"
+                ),
+                undo_scope="micro",
+            )
+            # Actions from the POST-escalation plan (execution_log is the
+            # router's actual execution record — captures the swapped plan
+            # when composer escalation fired successfully).
+            for er in (commit_result.get("execution_log") or []):
+                if er.get("ok"):
+                    ledger.append_action(
+                        ledger_entry_id,
+                        tool_name=er.get("tool", ""),
+                        summary=er.get("tool", "") or "step",
+                    )
+            steps_executed = int(commit_result.get("steps_executed", 0))
+            steps_failed = int(commit_result.get("steps_failed", 0))
+            total = steps_executed + steps_failed
+            ledger.finalize_move(
+                ledger_entry_id,
+                kept=(steps_failed == 0),
+                score=(float(steps_executed) / total) if total else 0.0,
+                memory_candidate=False,
+            )
+        except Exception as exc:  # pragma: no cover — ledger is best-effort
+            logger.warning("commit_experiment ledger write failed: %s", exc)
+            ledger_entry_id = None
+
     # Surface escalation details on the commit response so the caller
     # sees whether a scaffold or resolved plan was applied.
     if escalation_info is not None and isinstance(commit_result, dict):
@@ -770,6 +877,12 @@ async def commit_experiment(
             "warnings": escalation_info.get("warnings", []),
         }
 
+    # Surface ledger_entry_id on the commit response so callers can
+    # correlate their MCP response with the ledger entry for post-hoc
+    # evaluation. Same pattern as apply_semantic_move.
+    if ledger_entry_id is not None and isinstance(commit_result, dict):
+        commit_result["ledger_entry_id"] = ledger_entry_id
+
     return commit_result
 
 

package/mcp_server/memory/tools.py

@@ -55,6 +55,10 @@ def record_anti_preference(
 @mcp.tool()
 def get_promotion_candidates(ctx: Context, limit: int = 10) -> dict:
     """Check the session ledger for entries eligible for memory promotion."""
+    # store_purpose: audit_readonly
+    # Reads the ledger to find entries already flagged as
+    # memory-promotion candidates — an audit/export surface, NOT an
+    # anti-repetition recency read.
     ledger = ctx.lifespan_context.get("action_ledger")
     if ledger is None:
         return {"candidates": [], "count": 0, "note": "no session ledger active"}
@@ -75,6 +79,12 @@ def get_promotion_candidates(ctx: Context, limit: int = 10) -> dict:
 # ── Session Memory ──────────────────────────────────────────────────
 
 
+# store_purpose: mcp_tool_definition
+# get_session_memory is the MCP tool that surfaces session-scoped
+# ephemeral observations/decisions. It is NOT the action ledger and
+# NOT the persistent technique library — use the right tool for
+# recency (SessionLedger.get_recent_moves / get_action_ledger_summary)
+# or for learned techniques (memory_list).
 @mcp.tool()
 def get_session_memory(
     ctx: Context, limit: int = 10, category: str = ""

package/mcp_server/runtime/tools.py

@@ -215,6 +215,13 @@ def get_session_kernel(
     session_mem: list = []
     kernel_warnings: list[str] = []
 
+    # store_purpose: audit_readonly
+    # The world-model kernel builder surfaces ledger state (total moves,
+    # memory candidates, last_move, recent_moves) as diagnostic data for
+    # downstream consumers. Not an anti-repetition reader — it's a
+    # kernel-assembly surface; consumers that want recency should either
+    # call SessionLedger.get_recent_moves directly (annotated as
+    # anti_repetition) or use get_action_ledger_summary.
     try:
         from .action_ledger import SessionLedger
         ledger = ctx.lifespan_context.get("action_ledger")

package/mcp_server/semantic_moves/device_creation_compilers.py

@@ -44,7 +44,33 @@ _MOVE_TO_TEMPLATE: dict[str, str] = {
 
 def _compile_device_creation(move: SemanticMove, kernel: dict) -> CompiledPlan:
     """Map plan_template steps to CompiledStep, injecting Device Forge
-    `gen_code` when the move is in _MOVE_TO_TEMPLATE."""
+    `gen_code` and threading `track_index` through `find_and_load_device`."""
+    # v1.21 parity-gate fix: thread track_index from seed_args into
+    # find_and_load_device steps. Pre-fix, plan_templates emitted the
+    # ergonomic key ``query`` with no track_index — broken at runtime
+    # since pre-v1.20 because the ``remote_command`` backend bypasses
+    # MCP normalization and Ableton's handler requires
+    # ``track_index`` + ``device_name``.
+    seed_args = kernel.get("seed_args") or {}
+    track_index = seed_args.get("track_index")
+    needs_load_step = any(
+        s.get("tool") == "find_and_load_device" for s in move.plan_template
+    )
+    if needs_load_step and track_index is None:
+        return CompiledPlan(
+            move_id=move.move_id,
+            intent=move.intent,
+            steps=[],
+            risk_level=move.risk_level,
+            summary=f"{move.move_id} requires seed_args.track_index",
+            warnings=[
+                f"{move.move_id} requires seed_args.track_index (int) to "
+                "load the generated device onto a track. Example: "
+                f"apply_semantic_move(\"{move.move_id}\", mode=\"explore\", "
+                "args={\"track_index\": 0})"
+            ],
+        )
+
     # Resolve the GenExpr template once per compile (idempotent).
     template_code: str | None = None
     template_id = _MOVE_TO_TEMPLATE.get(move.move_id)
@@ -60,14 +86,22 @@ def _compile_device_creation(move: SemanticMove, kernel: dict) -> CompiledPlan:
     steps: list[CompiledStep] = []
     for step in move.plan_template:
         params = dict(step.get("params") or {})
+        tool = step.get("tool", "")
 
         # Inject gen_code for Device Forge moves. Done BEFORE CompiledStep
         # construction so the step snapshot is correct, not mutated later.
-        if template_code is not None and step.get("tool") == "generate_m4l_effect":
+        if template_code is not None and tool == "generate_m4l_effect":
             params["gen_code"] = template_code
 
+        # v1.21: inject track_index into find_and_load_device. plan_templates
+        # now emit {"device_name": ...} (wire-format key); compiler adds
+        # {"track_index": ...} from seed_args so the remote_command backend
+        # sends a handler-compatible payload.
+        if tool == "find_and_load_device":
+            params["track_index"] = track_index
+
         steps.append(CompiledStep(
-            tool=step.get("tool", ""),
+            tool=tool,
             params=params,
             description=step.get("description", ""),
             verify_after=bool(step.get("verify_after", True)),

package/mcp_server/semantic_moves/device_creation_moves.py

@@ -28,7 +28,7 @@ CREATE_CHAOS_MODULATOR = SemanticMove(
         },
         {
             "tool": "find_and_load_device",
-            "params": {"query": "Wonder Chaos Mod"},
+            "params": {"device_name": "Wonder Chaos Mod"},
             "description": "Load generated device onto target track",
             "backend": "remote_command",
         },
@@ -59,7 +59,7 @@ CREATE_FEEDBACK_RESONATOR = SemanticMove(
         },
         {
             "tool": "find_and_load_device",
-            "params": {"query": "Wonder Resonator"},
+            "params": {"device_name": "Wonder Resonator"},
             "description": "Load resonator onto target track",
             "backend": "remote_command",
         },
@@ -90,7 +90,7 @@ CREATE_WAVEFOLDER_EFFECT = SemanticMove(
         },
         {
             "tool": "find_and_load_device",
-            "params": {"query": "Wonder Wavefolder"},
+            "params": {"device_name": "Wonder Wavefolder"},
             "description": "Load wavefolder onto target track",
             "backend": "remote_command",
         },
@@ -121,7 +121,7 @@ CREATE_BITCRUSHER_EFFECT = SemanticMove(
         },
         {
             "tool": "find_and_load_device",
-            "params": {"query": "Wonder Bitcrusher"},
+            "params": {"device_name": "Wonder Bitcrusher"},
             "description": "Load bitcrusher onto target track",
             "backend": "remote_command",
         },
@@ -152,7 +152,7 @@ CREATE_KARPLUS_STRING = SemanticMove(
         },
         {
             "tool": "find_and_load_device",
-            "params": {"query": "Wonder String"},
+            "params": {"device_name": "Wonder String"},
             "description": "Load string synth onto target track",
             "backend": "remote_command",
         },
@@ -183,7 +183,7 @@ CREATE_STOCHASTIC_TEXTURE = SemanticMove(
         },
         {
             "tool": "find_and_load_device",
-            "params": {"query": "Wonder Stochastic"},
+            "params": {"device_name": "Wonder Stochastic"},
             "description": "Load stochastic texture device onto target track",
             "backend": "remote_command",
         },
@@ -214,7 +214,7 @@ CREATE_FDN_REVERB = SemanticMove(
         },
         {
             "tool": "find_and_load_device",
-            "params": {"query": "Wonder FDN Verb"},
+            "params": {"device_name": "Wonder FDN Verb"},
             "description": "Load FDN reverb onto target track",
             "backend": "remote_command",
         },

package/mcp_server/semantic_moves/device_mutation_compilers.py

@@ -27,14 +27,30 @@ def _empty_plan(move: SemanticMove, warnings: list[str]) -> CompiledPlan:
 
 
 def _compile_configure_device(move: SemanticMove, kernel: dict) -> CompiledPlan:
+    """Compile configure_device.
+
+    v1.20 contract: seed_args.param_overrides (explicit dict of
+    {param_name: value}).
+
+    v1.21 additions (additive — v1.20 callers unaffected):
+      - seed_args.preset: str        — named preset in the affordance library
+      - seed_args.device_slug: str   — required when preset is used; v1.21
+                                       does not auto-infer from class_name
+
+    Merge contract: preset resolves first, then explicit param_overrides
+    entries merge on top (last-write-wins at dict-key granularity).
+    """
     args = kernel.get("seed_args") or {}
     track_index = args.get("track_index")
     device_index = args.get("device_index")
-    overrides = args.get("param_overrides")
+    explicit_overrides = args.get("param_overrides")
+    preset_name = args.get("preset")
+    device_slug = args.get("device_slug")
 
-    if track_index is None or device_index is None or overrides is None:
+    if track_index is None or device_index is None:
         return _empty_plan(move, [
-            "configure_device requires seed_args.track_index + device_index + param_overrides"
+            "configure_device requires seed_args.track_index + device_index "
+            "(plus either param_overrides or a preset+device_slug pair)"
         ])
     if not isinstance(track_index, int) or not isinstance(device_index, int):
         return _empty_plan(move, [
@@ -43,14 +59,49 @@ def _compile_configure_device(move: SemanticMove, kernel: dict) -> CompiledPlan:
         ])
     if device_index < 0:
         return _empty_plan(move, [f"device_index must be non-negative, got {device_index}"])
-    if not isinstance(overrides, dict):
+
+    # explicit param_overrides is now optional (may be None if preset provides
+    # everything), but when present must be a dict.
+    if explicit_overrides is not None and not isinstance(explicit_overrides, dict):
         return _empty_plan(move, [
-            f"param_overrides must be a dict[str, Any], got {type(overrides).__name__}"
+            f"param_overrides must be a dict[str, Any], got "
+            f"{type(explicit_overrides).__name__}"
         ])
-    if not overrides:
+
+    # v1.21: resolve preset if requested
+    preset_overrides: dict = {}
+    if preset_name is not None:
+        if not device_slug:
+            return _empty_plan(move, [
+                "preset seed_arg requires device_slug (v1.21 contract — "
+                "auto-inference from class_name is v1.22 scope). Example: "
+                "args={\"track_index\": -1, \"device_index\": 0, "
+                "\"device_slug\": \"reverb\", \"preset\": \"dub-cathedral\"}"
+            ])
+        # Late import so mcp_server.semantic_moves doesn't hard-depend on
+        # mcp_server.affordances at import time — branch is only taken
+        # when a caller explicitly asks for a preset.
+        from ..affordances import resolve_preset
+        resolved = resolve_preset(device_slug, preset_name)
+        if resolved is None:
+            return _empty_plan(move, [
+                f"No preset {preset_name!r} for device slug {device_slug!r}. "
+                f"Check mcp_server/affordances/devices/{device_slug}.yaml "
+                f"exists and contains the named preset."
+            ])
+        preset_overrides = resolved
+
+    # Merge: preset resolves first, explicit param_overrides merge on top
+    # (last-write-wins at dict-key granularity).
+    merged: dict = dict(preset_overrides)
+    if explicit_overrides:
+        merged.update(explicit_overrides)
+
+    if not merged:
         return _empty_plan(move, [
-            "param_overrides is empty — nothing to configure (delete_device "
-            "is a different move)"
+            "configure_device requires either a non-empty param_overrides "
+            "dict OR a preset+device_slug combination that resolves to "
+            "params. Neither was provided."
         ])
 
     # WIRE-FORMAT NOTE: compiled steps use the remote_command backend,
@@ -61,9 +112,12 @@ def _compile_configure_device(move: SemanticMove, kernel: dict) -> CompiledPlan:
     # exclusively. Emit that key directly.
     parameters = [
         {"name_or_index": str(name), "value": value}
-        for name, value in overrides.items()
+        for name, value in merged.items()
     ]
 
+    preset_suffix = (
+        f" from preset {device_slug}/{preset_name}" if preset_name else ""
+    )
     step = CompiledStep(
         tool="batch_set_parameters",
         params={
@@ -72,9 +126,9 @@ def _compile_configure_device(move: SemanticMove, kernel: dict) -> CompiledPlan:
             "parameters": parameters,
         },
         description=(
-            f"Configure device at track {track_index}, device_index {device_index} — "
-            f"set {len(parameters)} parameter(s): "
-            f"{', '.join(p['name_or_index'] for p in parameters)}"
+            f"Configure device at track {track_index}, device_index "
+            f"{device_index}{preset_suffix} — set {len(parameters)} "
+            f"parameter(s): {', '.join(p['name_or_index'] for p in parameters)}"
         ),
         verify_after=True,
         backend="remote_command",