livepilot 1.17.1 → 1.17.2

package/mcp_server/runtime/capability_state.py

@@ -155,6 +155,9 @@ def build_capability_state(
     )
 
     # ── web ──────────────────────────────────────────────────────────
+    # Server-side outbound HTTP capability.  True when the MCP host can
+    # reach an arbitrary public URL.  Does NOT imply curated research
+    # corpora are installed — see the ``research`` domain below.
     web_reasons: list[str] = []
     if not web_ok:
         web_reasons.append("web_unavailable")
@@ -166,6 +169,21 @@ def build_capability_state(
         reasons=web_reasons,
     )
 
+    # ── flucoma ──────────────────────────────────────────────────────
+    # Optional dependency (the ``flucoma`` Python package).  Emitted
+    # unconditionally so consumers can distinguish "probed and missing"
+    # from "probe not run yet".
+    flucoma_reasons: list[str] = []
+    if not flucoma_ok:
+        flucoma_reasons.append("flucoma_not_installed")
+    domains["flucoma"] = CapabilityDomain(
+        name="flucoma",
+        available=flucoma_ok,
+        confidence=0.9 if flucoma_ok else 0.0,
+        mode="available" if flucoma_ok else "unavailable",
+        reasons=flucoma_reasons,
+    )
+
     # ── research (composite) ────────────────────────────────────────
     research_reasons: list[str] = []
     research_sources = 0

package/mcp_server/runtime/degradation.py

@@ -0,0 +1,62 @@
+"""Explicit degradation signalling for engines that fall back to synthesized data.
+
+Before PR-B, several engines silently substituted defaults when a data
+source failed — ``song_brain`` injected ``tempo=120.0, track_count=0``
+on session-fetch failure, and ``preview_studio`` compiled variants
+against an empty-but-valid kernel when the caller didn't supply one.
+Downstream consumers had no way to tell synthesized data from real
+data, so polished outputs were returned as if they were real.
+
+``DegradationInfo`` is the shared payload engines attach to their
+responses whenever they substitute fallback values. Consumers can
+inspect ``is_degraded``, ``reasons``, and ``substituted_fields`` to
+decide whether to trust the response or re-try the operation.
+
+Usage::
+
+    from mcp_server.runtime.degradation import DegradationInfo
+
+    deg = DegradationInfo()
+    try:
+        data = fetch_real_data()
+    except Exception:
+        data = FALLBACK_DATA
+        deg = DegradationInfo(
+            is_degraded=True,
+            reasons=["data_source_unreachable"],
+            substituted_fields=["tempo", "track_count"],
+        )
+    return {..., "degradation": deg.to_dict()}
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class DegradationInfo:
+    """A structured signal that an engine substituted fallback data.
+
+    Attributes:
+        is_degraded: True when any field in the response was substituted
+            with a synthesized/default value. False means the response
+            is fully backed by real data sources.
+        reasons: Short machine-readable tokens describing why degradation
+            happened (e.g., ``"session_fetch_failed"``,
+            ``"empty_kernel_fallback"``). Intentionally open-ended — the
+            set grows as new fallback paths get flagged.
+        substituted_fields: Names of top-level response fields whose
+            values came from the fallback path, not the real source.
+    """
+
+    is_degraded: bool = False
+    reasons: list[str] = field(default_factory=list)
+    substituted_fields: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "is_degraded": self.is_degraded,
+            "reasons": list(self.reasons),
+            "substituted_fields": list(self.substituted_fields),
+        }

package/mcp_server/runtime/tools.py

@@ -7,6 +7,9 @@ Tools:
 
 from __future__ import annotations
 
+import importlib.util
+import logging
+import urllib.request
 from typing import Optional
 
 from fastmcp import Context
@@ -14,13 +17,55 @@ from fastmcp import Context
 from ..server import mcp
 from ..memory.technique_store import TechniqueStore
 from .capability_state import build_capability_state
-import logging
 
 logger = logging.getLogger(__name__)
 
 _memory_store = TechniqueStore()
 
 
+# ── Capability probes ──────────────────────────────────────────────────
+#
+# These helpers are module-level so tests can monkeypatch them directly.
+
+
+def _probe_web(timeout: float = 0.5) -> bool:
+    """Server-side outbound HTTP probe.
+
+    True when the MCP host can reach an arbitrary public URL. Does NOT
+    imply curated research corpora are installed — see the ``research``
+    domain for that.
+
+    Implementation: a ``timeout``-second HEAD request to
+    ``https://api.github.com`` using stdlib ``urllib.request``. Any
+    exception (DNS failure, TLS error, socket timeout, proxy block,
+    non-2xx response) collapses to False so the probe is safe to call
+    from any code path.
+    """
+    req = urllib.request.Request("https://api.github.com", method="HEAD")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            status = getattr(resp, "status", None)
+            return status is not None and 200 <= status < 400
+    except Exception as exc:  # noqa: BLE001 — swallow everything to False
+        logger.debug("_probe_web failed: %s", exc)
+        return False
+
+
+def _probe_flucoma() -> bool:
+    """Check whether the ``flucoma`` Python package is importable.
+
+    Uses ``importlib.util.find_spec`` so no import side-effects fire
+    (matching the pattern already used for optional capability probes
+    elsewhere in the codebase). Returns False if the package is missing
+    or if the spec lookup itself raises.
+    """
+    try:
+        return importlib.util.find_spec("flucoma") is not None
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("_probe_flucoma failed: %s", exc)
+        return False
+
+
 @mcp.tool()
 def get_capability_state(ctx: Context) -> dict:
     """Probe the runtime and return a capability state snapshot.
@@ -59,9 +104,13 @@ def get_capability_state(ctx: Context) -> dict:
         logger.debug("get_capability_state failed: %s", exc)
         memory_ok = False
 
-    # ── Web / FluCoMa — not probed live, default to False ───────────
-    web_ok = False
-    flucoma_ok = False
+    # ── Web — actually probe outbound HTTP egress ───────────────────
+    # Scoped to server-side outbound HTTP reachability; does NOT imply
+    # a curated research corpus is installed (see ``research`` domain).
+    web_ok = _probe_web()
+
+    # ── FluCoMa — optional import via find_spec (no side effects) ───
+    flucoma_ok = _probe_flucoma()
 
     state = build_capability_state(
         session_ok=session_ok,

package/mcp_server/song_brain/tools.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 from fastmcp import Context
 
+from ..runtime.degradation import DegradationInfo
 from ..server import mcp
 from . import builder
 from .models import SongBrain
@@ -55,6 +56,12 @@ def _fetch_session_data(ctx: Context) -> dict:
     - composition_analysis: from musical intelligence section inference
     - role_graph: from semantic move resolvers (track role inference)
     - recent_moves: from session-scoped action ledger
+
+    On session-fetch failure the fallback session_info shape is injected
+    (``tempo=120.0, track_count=0``) and a ``DegradationInfo`` is attached
+    under the ``_degradation`` key so callers can tell synthesized data
+    from real data. ``_fetch_session_data`` never raises — it always
+    returns a dict with the expected keys.
     """
     ableton = _get_ableton(ctx)
     data: dict = {
@@ -66,12 +73,19 @@ def _fetch_session_data(ctx: Context) -> dict:
         "role_graph": {},
         "recent_moves": [],
     }
+    degradation = DegradationInfo()
 
     try:
         data["session_info"] = ableton.send_command("get_session_info", {})
     except Exception as exc:
         logger.debug("_fetch_session_data failed: %s", exc)
         data["session_info"] = {"tempo": 120.0, "track_count": 0}
+        degradation.is_degraded = True
+        if "session_fetch_failed" not in degradation.reasons:
+            degradation.reasons.append("session_fetch_failed")
+        for fld in ("tempo", "track_count"):
+            if fld not in degradation.substituted_fields:
+                degradation.substituted_fields.append(fld)
 
     try:
         matrix = ableton.send_command("get_scene_matrix")
@@ -135,6 +149,10 @@ def _fetch_session_data(ctx: Context) -> dict:
     except Exception as exc:
         logger.debug("_fetch_session_data failed: %s", exc)
 
+    # Attach the degradation signal so build_song_brain can surface it.
+    # Under a reserved key (leading underscore) so it never collides with
+    # a real session data field.
+    data["_degradation"] = degradation
     return data
 
 
@@ -180,10 +198,15 @@ def build_song_brain(ctx: Context) -> dict:
     )
     _set_brain(ctx, brain)
 
+    # Surface the degradation payload so callers can distinguish a
+    # tempo=120 / track_count=0 synthesized response from a real one.
+    degradation = data.get("_degradation") or DegradationInfo()
+
     return {
         **brain.to_dict(),
         "summary": brain.summary,
         "capability": cap.to_dict(),
+        "degradation": degradation.to_dict(),
     }
 
 

package/mcp_server/synthesis_brain/timbre.py

@@ -19,12 +19,16 @@ from .models import TimbralFingerprint
 
 # ── Band-based brightness / warmth mapping ──────────────────────────────
 #
-# The M4L analyzer returns an 8-band spectrum by default. When a full
-# spectrum dict is passed, we look for these band keys in order. If the
-# raw {freq: magnitude} shape is passed instead, we fall back to a coarser
-# low/mid/high split.
+# Two upstream producers feed this extractor with different band schemas:
+#   1. get_master_spectrum (M4L analyzer)   — v1.16+: 9 bands (sub_low,
+#      sub, low, low_mid, mid, high_mid, high, presence, air);
+#      pre-v1.16: 8 bands (no sub_low).
+#   2. analyze_spectrum_offline             — 8 bands with legacy names
+#      (sub, low, low_mid, mid, high_mid, high, very_high, ultra).
+# We index the union of both name sets below; `_band_energy` uses dict.get
+# so missing bands simply return 0 without complaint.
 
-_BANDS = ("sub", "low", "low_mid", "mid", "high_mid", "high", "very_high", "ultra")
+_BANDS = ("sub_low", "sub", "low", "low_mid", "mid", "high_mid", "high", "presence", "air", "very_high", "ultra")
 
 
 def _band_energy(spectrum: Optional[dict], band: str) -> float:
@@ -55,9 +59,11 @@ def extract_timbre_fingerprint(
     Inputs are all optional — the function degrades gracefully when only
     some dimensions are measurable.
 
-      spectrum: either {sub, low, low_mid, mid, high_mid, high, very_high, ultra}
-        or {"bands": {...}} — the 8-band shape returned by get_master_spectrum /
-        analyze_spectrum_offline. Missing bands default to 0.
+      spectrum: either the 9-band shape from get_master_spectrum
+        ({sub_low, sub, low, low_mid, mid, high_mid, high, presence, air}),
+        the legacy 8-band shape from analyze_spectrum_offline
+        ({sub, low, low_mid, mid, high_mid, high, very_high, ultra}),
+        or {"bands": {...}} wrapping either. Missing bands default to 0.
       loudness: {"rms": float, "peak": float, "lufs": float, "lra": float} —
         output shape from analyze_loudness.
       spectral_shape: FluCoMa descriptors when available — {"centroid", "flatness",

package/mcp_server/tools/_agent_os_engine/__init__.py

@@ -35,6 +35,12 @@ from .taste import (
     compute_taste_fit,
     get_taste_profile,
 )
+from .iteration import (
+    iterate_toward_goal_engine,
+    iterate_toward_goal_engine_async,
+    IterationResult,
+    IterationStep,
+)
 
 __all__ = [
     "QUALITY_DIMENSIONS", "MEASURABLE_PROXIES",
@@ -49,4 +55,8 @@ __all__ = [
     "analyze_outcome_history",
     "compute_taste_fit",
     "get_taste_profile",
+    "iterate_toward_goal_engine",
+    "iterate_toward_goal_engine_async",
+    "IterationResult",
+    "IterationStep",
 ]

package/mcp_server/tools/_agent_os_engine/iteration.py

@@ -0,0 +1,344 @@
+"""Iteration engine — closes the evaluation loop by running experiments
+repeatedly against a compiled GoalVector until threshold or timeout.
+
+Pure-python: takes callables for experiment create/run/commit/discard so
+tests can substitute in-memory fakes without an Ableton connection. The
+callables may be sync or async — the engine uses `iterate_toward_goal_engine`
+(sync) for the former and `iterate_toward_goal_engine_async` for the latter.
+"""
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, Optional, Union
+
+
+@dataclass
+class IterationStep:
+    """One iteration of the outer loop — one experiment's worth of work."""
+    iteration: int
+    experiment_id: str
+    winner_branch_id: Optional[str]
+    winner_score: float
+    threshold_met: bool
+    note: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "iteration": self.iteration,
+            "experiment_id": self.experiment_id,
+            "winner_branch_id": self.winner_branch_id,
+            "winner_score": self.winner_score,
+            "threshold_met": self.threshold_met,
+            "note": self.note,
+        }
+
+
+@dataclass
+class IterationResult:
+    """Final result of iterate_toward_goal.
+
+    status:
+      - "committed" — a winner hit threshold, was committed permanently
+      - "exhausted" — max_iterations reached, committed best-so-far (on_timeout=commit_best)
+      - "timeout_no_commit" — max_iterations reached, no commit (on_timeout=discard_on_timeout)
+      - "no_candidates" — caller provided empty candidate_move_sets
+      - "error" — unrecoverable error; see reason
+    """
+    status: str
+    iterations_run: int
+    committed_experiment_id: Optional[str]
+    committed_branch_id: Optional[str]
+    final_score: float
+    steps: list[IterationStep] = field(default_factory=list)
+    reason: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "status": self.status,
+            "iterations_run": self.iterations_run,
+            "committed_experiment_id": self.committed_experiment_id,
+            "committed_branch_id": self.committed_branch_id,
+            "final_score": self.final_score,
+            "steps": [s.to_dict() for s in self.steps],
+            "reason": self.reason,
+        }
+
+
+def iterate_toward_goal_engine(
+    candidate_move_sets: list,
+    threshold: float,
+    max_iterations: int,
+    create_experiment_fn: Callable[[list], str],
+    run_experiment_fn: Callable[[str], Any],
+    commit_fn: Callable[[str, str], dict],
+    discard_fn: Callable[[str], dict],
+    on_timeout: str = "commit_best",
+) -> IterationResult:
+    """Run experiments repeatedly until winner_score >= threshold or timeout.
+
+    Pure orchestration — all I/O happens through the injected callbacks. The
+    run/commit/discard callbacks may be sync or async; coroutines will be
+    awaited when reached. This keeps the engine reusable by both the
+    sync test suite and the async MCP tool wrapper.
+
+    See module docstring for full contract. Invariant: never issues raw
+    undo calls — per-branch undo is the responsibility of run_experiment_fn.
+    This loop only chooses commit vs discard.
+    """
+    import asyncio
+
+    async def _as_async():
+        return await _iterate_async_core(
+            candidate_move_sets=candidate_move_sets,
+            threshold=threshold,
+            max_iterations=max_iterations,
+            create_experiment_fn=create_experiment_fn,
+            run_experiment_fn=run_experiment_fn,
+            commit_fn=commit_fn,
+            discard_fn=discard_fn,
+            on_timeout=on_timeout,
+        )
+
+    # If any callback is a coroutine function, run via asyncio. Otherwise
+    # execute the sync path directly to avoid event-loop overhead in tests.
+    any_async = any(
+        inspect.iscoroutinefunction(fn)
+        for fn in (create_experiment_fn, run_experiment_fn, commit_fn, discard_fn)
+    )
+    if any_async:
+        return asyncio.run(_as_async())
+
+    return _iterate_sync_core(
+        candidate_move_sets=candidate_move_sets,
+        threshold=threshold,
+        max_iterations=max_iterations,
+        create_experiment_fn=create_experiment_fn,
+        run_experiment_fn=run_experiment_fn,
+        commit_fn=commit_fn,
+        discard_fn=discard_fn,
+        on_timeout=on_timeout,
+    )
+
+
+async def iterate_toward_goal_engine_async(
+    candidate_move_sets: list,
+    threshold: float,
+    max_iterations: int,
+    create_experiment_fn: Callable[[list], Any],
+    run_experiment_fn: Callable[[str], Any],
+    commit_fn: Callable[[str, str], Any],
+    discard_fn: Callable[[str], Any],
+    on_timeout: str = "commit_best",
+) -> IterationResult:
+    """Async variant — used by the MCP tool wrapper which has async callbacks."""
+    return await _iterate_async_core(
+        candidate_move_sets=candidate_move_sets,
+        threshold=threshold,
+        max_iterations=max_iterations,
+        create_experiment_fn=create_experiment_fn,
+        run_experiment_fn=run_experiment_fn,
+        commit_fn=commit_fn,
+        discard_fn=discard_fn,
+        on_timeout=on_timeout,
+    )
+
+
+# ── Internal cores ─────────────────────────────────────────────────────────
+
+def _iterate_sync_core(
+    candidate_move_sets,
+    threshold,
+    max_iterations,
+    create_experiment_fn,
+    run_experiment_fn,
+    commit_fn,
+    discard_fn,
+    on_timeout,
+) -> IterationResult:
+    if not candidate_move_sets:
+        return IterationResult(
+            status="no_candidates",
+            iterations_run=0,
+            committed_experiment_id=None,
+            committed_branch_id=None,
+            final_score=0.0,
+            reason="candidate_move_sets is empty",
+        )
+
+    steps: list[IterationStep] = []
+    best_score = -1.0
+    best_exp_id: Optional[str] = None
+    best_branch_id: Optional[str] = None
+    n = min(max_iterations, len(candidate_move_sets))
+
+    for i in range(n):
+        move_ids = candidate_move_sets[i]
+        exp_id = create_experiment_fn(move_ids)
+        winner_branch_id, winner_score = run_experiment_fn(exp_id)
+
+        met = winner_score >= threshold and winner_branch_id is not None
+        steps.append(IterationStep(
+            iteration=i,
+            experiment_id=exp_id,
+            winner_branch_id=winner_branch_id,
+            winner_score=winner_score,
+            threshold_met=met,
+            note=(
+                f"committed on iteration {i}" if met
+                else f"below threshold (need {threshold}, got {winner_score})"
+            ),
+        ))
+
+        if met:
+            # Discard any prior best-so-far before committing the new winner —
+            # otherwise the old non-winning experiment leaks in the store.
+            if best_exp_id is not None and best_exp_id != exp_id:
+                discard_fn(best_exp_id)
+            commit_fn(exp_id, winner_branch_id)
+            return IterationResult(
+                status="committed",
+                iterations_run=i + 1,
+                committed_experiment_id=exp_id,
+                committed_branch_id=winner_branch_id,
+                final_score=winner_score,
+                steps=steps,
+                reason=f"threshold {threshold} met on iteration {i}",
+            )
+
+        if winner_branch_id is not None and winner_score > best_score:
+            # Supersede previous best-so-far. It's now stale, free the slot.
+            if best_exp_id is not None:
+                discard_fn(best_exp_id)
+            best_score = winner_score
+            best_exp_id = exp_id
+            best_branch_id = winner_branch_id
+        else:
+            discard_fn(exp_id)
+
+    if on_timeout == "commit_best" and best_exp_id and best_branch_id:
+        commit_fn(best_exp_id, best_branch_id)
+        return IterationResult(
+            status="exhausted",
+            iterations_run=n,
+            committed_experiment_id=best_exp_id,
+            committed_branch_id=best_branch_id,
+            final_score=best_score,
+            steps=steps,
+            reason=(
+                f"max_iterations={n} reached, threshold {threshold} never met; "
+                f"committed best-so-far with score {best_score}"
+            ),
+        )
+
+    if best_exp_id:
+        discard_fn(best_exp_id)
+    return IterationResult(
+        status="timeout_no_commit",
+        iterations_run=n,
+        committed_experiment_id=None,
+        committed_branch_id=None,
+        final_score=max(best_score, 0.0),
+        steps=steps,
+        reason=f"max_iterations={n} reached, policy={on_timeout}, no commit issued",
+    )
+
+
+async def _iterate_async_core(
+    candidate_move_sets,
+    threshold,
+    max_iterations,
+    create_experiment_fn,
+    run_experiment_fn,
+    commit_fn,
+    discard_fn,
+    on_timeout,
+) -> IterationResult:
+    if not candidate_move_sets:
+        return IterationResult(
+            status="no_candidates",
+            iterations_run=0,
+            committed_experiment_id=None,
+            committed_branch_id=None,
+            final_score=0.0,
+            reason="candidate_move_sets is empty",
+        )
+
+    async def _maybe_await(value):
+        if inspect.isawaitable(value):
+            return await value
+        return value
+
+    steps: list[IterationStep] = []
+    best_score = -1.0
+    best_exp_id: Optional[str] = None
+    best_branch_id: Optional[str] = None
+    n = min(max_iterations, len(candidate_move_sets))
+
+    for i in range(n):
+        move_ids = candidate_move_sets[i]
+        exp_id = await _maybe_await(create_experiment_fn(move_ids))
+        winner_branch_id, winner_score = await _maybe_await(run_experiment_fn(exp_id))
+
+        met = winner_score >= threshold and winner_branch_id is not None
+        steps.append(IterationStep(
+            iteration=i,
+            experiment_id=exp_id,
+            winner_branch_id=winner_branch_id,
+            winner_score=winner_score,
+            threshold_met=met,
+            note=(
+                f"committed on iteration {i}" if met
+                else f"below threshold (need {threshold}, got {winner_score})"
+            ),
+        ))
+
+        if met:
+            if best_exp_id is not None and best_exp_id != exp_id:
+                await _maybe_await(discard_fn(best_exp_id))
+            await _maybe_await(commit_fn(exp_id, winner_branch_id))
+            return IterationResult(
+                status="committed",
+                iterations_run=i + 1,
+                committed_experiment_id=exp_id,
+                committed_branch_id=winner_branch_id,
+                final_score=winner_score,
+                steps=steps,
+                reason=f"threshold {threshold} met on iteration {i}",
+            )
+
+        if winner_branch_id is not None and winner_score > best_score:
+            if best_exp_id is not None:
+                await _maybe_await(discard_fn(best_exp_id))
+            best_score = winner_score
+            best_exp_id = exp_id
+            best_branch_id = winner_branch_id
+        else:
+            await _maybe_await(discard_fn(exp_id))
+
+    if on_timeout == "commit_best" and best_exp_id and best_branch_id:
+        await _maybe_await(commit_fn(best_exp_id, best_branch_id))
+        return IterationResult(
+            status="exhausted",
+            iterations_run=n,
+            committed_experiment_id=best_exp_id,
+            committed_branch_id=best_branch_id,
+            final_score=best_score,
+            steps=steps,
+            reason=(
+                f"max_iterations={n} reached, threshold {threshold} never met; "
+                f"committed best-so-far with score {best_score}"
+            ),
+        )
+
+    if best_exp_id:
+        await _maybe_await(discard_fn(best_exp_id))
+    return IterationResult(
+        status="timeout_no_commit",
+        iterations_run=n,
+        committed_experiment_id=None,
+        committed_branch_id=None,
+        final_score=max(best_score, 0.0),
+        steps=steps,
+        reason=f"max_iterations={n} reached, policy={on_timeout}, no commit issued",
+    )