livepilot 1.16.0 → 1.17.0

package/mcp_server/sample_engine/tools.py

@@ -205,6 +205,7 @@ async def search_samples(
     max_results: int = 10,
     free_only: bool = False,
     q: Optional[str] = None,
+    collection_uuid: str = "",
 ) -> dict:
     """Search for samples across Splice library, Ableton browser, and local filesystem.
 
@@ -224,6 +225,9 @@ async def search_samples(
     key: prefer samples in this key (e.g., "Cm", "F#")
     bpm_range: "min-max" BPM range (e.g., "120-130")
     source: "splice", "browser", "filesystem", or None for all
+    collection_uuid: scope Splice results to a user collection (Likes,
+      bass, keys, etc.). Obtain via splice_list_collections. When set,
+      browser/filesystem sources are skipped — this is taste-scoped search.
     max_results: maximum results to return (default 10)
     free_only: if True, only return samples that cost nothing to license
       (IsPremium=False or Price=0). Under the Ableton Live plan these
@@ -247,6 +251,11 @@ async def search_samples(
             except ValueError:
                 pass
 
+    # When scoped to a Splice collection, force source=splice and skip
+    # browser/filesystem since those don't carry collection metadata.
+    if collection_uuid and source is None:
+        source = "splice"
+
     # Splice search — prefer gRPC online catalog when available, fall back
     # to local SQLite index. See docs/2026-04-14-bugs-discovered.md — P0-2.
     if source in (None, "splice"):
@@ -267,6 +276,7 @@ async def search_samples(
                     per_page=max_results,
                     page=1,
                     purchased_only=False,
+                    collection_uuid=collection_uuid,
                 )
                 for s in grpc_result.samples[:max_results]:
                     if free_only and not s.is_free:
@@ -782,11 +792,15 @@ async def get_splice_credits(ctx: Context) -> dict:
         gating = "credit_floor"
         can_download = remaining > CREDIT_HARD_FLOOR
 
+    from ..splice_client.client import _read_plan_kind_override
+    plan_override_active = _read_plan_kind_override()
+
     return {
         "connected": True,
         "username": info.username,
         "plan_raw": info.plan,
         "plan_kind": plan.value,
+        "plan_kind_override": plan_override_active,
         "sounds_plan_id": info.sounds_plan_id,
         "features": info.features,
         "user_uuid": info.user_uuid,
@@ -1091,16 +1105,34 @@ async def splice_preview_sample(
     if client is None or not getattr(client, "connected", False):
         return {"ok": False, "error": "Splice gRPC not connected"}
 
+    # Two-stage lookup: SampleInfo is the fast path but only returns
+    # full metadata (including the signed PreviewURL) for downloaded or
+    # purchased samples. For un-downloaded catalog items, fall back to
+    # SearchSamples(FileHash=...) which hits the catalog index and always
+    # returns PreviewURL. Observed live 2026-04-22.
     sample = None
     try:
         sample = await client.get_sample_info(file_hash)
     except Exception as exc:
-        return {"ok": False, "error": f"SampleInfo failed: {exc}"}
+        logger.debug("SampleInfo lookup failed, falling back to search: %s", exc)
+
+    if sample is None or not sample.preview_url:
+        try:
+            search = await client.search_samples(file_hash=file_hash, per_page=1)
+            if search.samples:
+                sample = search.samples[0]
+        except Exception as exc:
+            return {"ok": False, "error": f"PreviewURL lookup failed: {exc}"}
 
     if sample is None or not sample.preview_url:
         return {
             "ok": False,
-            "error": "No preview URL available for this sample",
+            "error": (
+                "No preview URL available for this sample. Splice may "
+                "require the sample to be in a public catalog index. "
+                "Try splice_catalog_hunt first to obtain a fresh "
+                "preview_url from the search result directly."
+            ),
             "file_hash": file_hash,
         }
 
@@ -1410,9 +1442,23 @@ async def splice_pack_info(ctx: Context, pack_uuid: str) -> dict:
         return err
     if not pack_uuid:
         return {"ok": False, "error": "pack_uuid is required"}
-    pack = await client.get_pack_info(pack_uuid)
+    # Pass the UUID through unchanged — Splice uses two valid UUID formats
+    # (canonical 36-char and extended 43-char with longer last group). The
+    # client tries BOTH forms during ListSamplePacks matching. An earlier
+    # revision pre-truncated to 36 chars here, which incorrectly discarded
+    # part of a legitimate extended UUID (observed 2026-04-22 live: pack
+    # "1170db75-0ce1-5280-bb61-887a0dd7f26bf5a3951" is an owned pack but
+    # pre-truncation made the client look for a UUID that didn't exist in
+    # ListSamplePacks' response).
+    submitted = pack_uuid.strip()
+    pack, err_msg = await client.get_pack_info(submitted)
     if pack is None:
-        return {"ok": False, "error": "Pack not found or gRPC call failed"}
+        return {
+            "ok": False,
+            "error": err_msg or "Pack not found",
+            "pack_uuid_submitted": submitted,
+            "pack_uuid_original": pack_uuid,
+        }
     return {"ok": True, "pack": pack.to_dict()}
 
 
@@ -1450,23 +1496,29 @@ async def splice_describe_sound(
     bpm: Optional[int] = None,
     key: Optional[str] = None,
     limit: int = 20,
+    rephrase: bool = True,
 ) -> dict:
     """Natural-language sample search — the Sounds Plugin's "Describe a Sound".
 
     Splice's AI matches free-form descriptions like "dark ambient pad with
-    shimmer" or "tight 90s house hi-hat" to catalog samples. This is NOT
-    on the local gRPC — the bridge proxies to api.splice.com using your
-    session token.
+    shimmer" or "tight 90s house hi-hat" to catalog samples. Hits the
+    GraphQL `SamplesSearch` operation on `surfaces-graphql.splice.com`
+    with `semantic=1` + `rephrase=true` enabled.
 
-    **Status: scaffolding complete, endpoint pending real-traffic capture.**
-    Until `SPLICE_DESCRIBE_ENDPOINT` env var is set (or
-    `SPLICE_ALLOW_UNVERIFIED_ENDPOINTS=1`), this tool returns a structured
-    ENDPOINT_NOT_CONFIGURED error with actionable setup steps.
+    **Status: LIVE** as of 2026-04-22. Endpoint captured via mitmproxy
+    against Splice desktop 5.4.9 + Sounds Plugin.
 
     description: free-text prompt ("warm analog bass under 80bpm")
     bpm:         optional BPM filter
     key:         optional musical key ("Dm", "F#")
     limit:       max results (default 20)
+    rephrase:    let Splice's ML rephrase the query for better matches
+                 (default True). Returned as `rephrased_query_string`.
+
+    Returns `{ok, query, samples[], total_hits, rephrased_query_string,
+    tag_summary[], ...}`. Each sample has uuid/name/bpm/key/duration/
+    instrument/tags/pack_name/files. Use the uuid with
+    `splice_download_sample(uuid)` to pull the audio file.
     """
     bridge, err = _build_http_bridge(ctx)
     if err:
@@ -1478,95 +1530,161 @@ async def splice_describe_sound(
         result = await bridge.describe_sound(
             description=description.strip(),
             bpm=bpm, key=key, limit=int(limit),
+            rephrase=bool(rephrase),
         )
     except SpliceHTTPError as exc:
         return exc.to_dict()
     except Exception as exc:
         return {"ok": False, "error": f"describe_sound failed: {exc}"}
-    return {"ok": True, "query": description, **(result if isinstance(result, dict) else {"raw": result})}
+    # Don't expose the full GraphQL `raw` dict in the user-facing response
+    # unless they asked — it adds ~270KB noise per call. Keep it for
+    # power users via an explicit future flag.
+    out = dict(result) if isinstance(result, dict) else {"raw": result}
+    out.pop("raw", None)
+    return {"ok": True, "query": description, **out}
 
 
 @mcp.tool()
 async def splice_generate_variation(
     ctx: Context,
-    file_hash: str,
-    target_key: Optional[str] = None,
-    target_bpm: Optional[int] = None,
-    count: int = 1,
+    uuid: str,
+    is_legacy: bool = True,
 ) -> dict:
-    """Generate AI variations of a Splice sample — the Sounds Plugin's "Variations".
-
-    Splice's AI produces unique re-keyed / re-tempo'd versions of any
-    sample. Costs additional credits per variation (on top of the base
-    license). NOT on the local gRPC — bridged via api.splice.com.
-
-    **Status: scaffolding complete, endpoint pending real-traffic capture.**
-    Until `SPLICE_VARIATION_ENDPOINT` env var is set (or
-    `SPLICE_ALLOW_UNVERIFIED_ENDPOINTS=1`), this tool returns a structured
-    ENDPOINT_NOT_CONFIGURED error with actionable setup steps.
-
-    file_hash:  sample identifier (from search results)
-    target_key: desired key (e.g. "Am")
-    target_bpm: desired tempo
-    count:      number of variations to generate (1-5)
-
-    WARNING: this WILL spend credits when the endpoint is live.
-    Consider previewing the source sample with splice_preview_sample first.
+    """Find catalog samples similar to a given Splice sample — the "Variations" feature.
+
+    Splice's right-click "Variations" menu item surfaces other catalog
+    samples with similar sonic character. The GraphQL operation name
+    is `AssetSimilarSoundsQuery`. Up to 10 results per call. No credit
+    cost (this is a recommender lookup, not AI audio synthesis — the
+    original naming in the handoff was aspirational).
+
+    **Status: LIVE** as of 2026-04-22. Endpoint captured via mitmproxy
+    against Splice desktop v5.4.9.
+
+    uuid:       source sample's catalog uuid (from `splice_describe_sound`
+                results or any other Splice metadata call)
+    is_legacy:  match how Splice's own client sets it — default True is
+                correct for all mainstream catalog samples; set False only
+                if working with post-catalog-v2 assets
+
+    Returns `{ok, uuid, similar_samples[], count}`. Each entry has the
+    same flat shape as a describe_sound sample (uuid/name/bpm/key/
+    duration/tags/pack_name/files). Use the uuid of any result with
+    `splice_download_sample()` to pull the audio.
     """
     bridge, err = _build_http_bridge(ctx)
     if err:
         return err
     from ..splice_client.http_bridge import SpliceHTTPError
-    if not file_hash or not file_hash.strip():
-        return {"ok": False, "error": "file_hash is required"}
-    if count < 1 or count > 5:
-        return {"ok": False, "error": "count must be 1-5"}
+    if not uuid or not uuid.strip():
+        return {"ok": False, "error": "uuid is required"}
     try:
         result = await bridge.generate_variation(
-            file_hash=file_hash.strip(),
-            target_key=target_key,
-            target_bpm=target_bpm,
-            count=int(count),
+            uuid=uuid.strip(),
+            is_legacy=bool(is_legacy),
         )
     except SpliceHTTPError as exc:
         return exc.to_dict()
     except Exception as exc:
         return {"ok": False, "error": f"generate_variation failed: {exc}"}
-    return {"ok": True, "file_hash": file_hash, **(result if isinstance(result, dict) else {"raw": result})}
+    out = dict(result) if isinstance(result, dict) else {"raw": result}
+    out.pop("raw", None)  # drop verbose debug payload
+    return {"ok": True, "uuid": uuid, **out}
 
 
-@mcp.tool()
-async def splice_search_with_sound(
-    ctx: Context,
-    audio_path: str,
-    limit: int = 20,
-) -> dict:
-    """Reference-audio search — the Sounds Plugin's "Search with Sound".
+# NOTE: splice_search_with_sound was removed 2026-04-22 — user does this
+# in-Splice manually. If someone wants to resurrect it, the capture recipe
+# is still at docs/2026-04-22-splice-https-capture-recipe.md.
 
-    Uploads a local audio file to Splice's AI and returns catalog samples
-    with similar character. Complements `splice_describe_sound` (text)
-    and `search_samples` (keyword).
 
-    **Status: scaffolding complete, wiring pending real-traffic capture
-    (multipart upload shape is the most uncertain part of the bridge).**
-    Until `SPLICE_SEARCH_WITH_SOUND_ENDPOINT` is set, returns a structured
-    NOT_YET_IMPLEMENTED error.
+@mcp.tool()
+async def splice_http_diagnose(ctx: Context) -> dict:
+    """Diagnose the Splice HTTPS bridge configuration and readiness.
 
-    audio_path: absolute path to a local audio file (.wav, .mp3, .flac)
-    limit:      max results (default 20)
+    Reports which endpoints are configured, whether a session token is
+    reachable from the gRPC client, and what the next step is to unblock
+    `splice_describe_sound` and `splice_generate_variation`.
+
+    Use this BEFORE calling either tool if you want a clear readout of
+    "what's missing, and how do I fix it" instead of per-tool
+    ENDPOINT_NOT_CONFIGURED errors.
     """
-    bridge, err = _build_http_bridge(ctx)
-    if err:
-        return err
-    from ..splice_client.http_bridge import SpliceHTTPError
-    if not audio_path or not os.path.isfile(audio_path):
-        return {"ok": False, "error": f"audio_path not found: {audio_path}"}
+    from ..splice_client.http_bridge import SpliceHTTPConfig
+
+    cfg = SpliceHTTPConfig.from_env()
+    endpoints = {
+        "describe": cfg.describe_endpoint,
+        "variation": cfg.variation_endpoint,
+    }
+    verified = {
+        "describe": cfg.describe_verified,
+        "variation": cfg.variation_verified,
+    }
+    unverified = [name for name, ok in verified.items() if not ok]
+    configured_count = sum(1 for v in endpoints.values() if v not in (None, ""))
+
+    # Try to read the session token via the gRPC client the SAME way
+    # the real tools do — reach into ctx.lifespan_context["splice_client"]
+    # and actually attempt a GetSession fetch. Walking a different
+    # engine-nested path (earlier mistake) reported "token unavailable"
+    # while the bridge's real request path succeeded — a misleading
+    # diagnostic is worse than no diagnostic.
+    session_token_available = False
+    session_token_error = None
+    grpc_client = None
     try:
-        result = await bridge.search_with_sound(
-            audio_path=audio_path, limit=int(limit),
+        grpc_client = ctx.lifespan_context.get("splice_client")
+    except AttributeError:
+        pass
+    if grpc_client is None or not getattr(grpc_client, "connected", False):
+        session_token_error = "Splice gRPC not connected"
+    else:
+        # Connection is up; confirm a token actually comes back.
+        from ..splice_client.http_bridge import fetch_session_token
+        try:
+            token = await fetch_session_token(grpc_client)
+            if token:
+                session_token_available = True
+            else:
+                session_token_error = (
+                    "GetSession RPC returned no token — user may be "
+                    "logged out or gRPC schema drifted"
+                )
+        except Exception as exc:
+            session_token_error = f"GetSession call failed: {exc}"
+
+    next_steps: list = []
+    if "describe" in unverified:
+        next_steps.append(
+            "Describe endpoint unverified — reset config to defaults "
+            "(delete ~/.livepilot/splice.json or unset env vars) so the "
+            "captured surfaces-graphql.splice.com/graphql endpoint is used."
         )
-    except SpliceHTTPError as exc:
-        return exc.to_dict()
-    except Exception as exc:
-        return {"ok": False, "error": f"search_with_sound failed: {exc}"}
-    return {"ok": True, "audio_path": audio_path, **(result if isinstance(result, dict) else {"raw": result})}
+    if "variation" in unverified:
+        next_steps.append(
+            "Variation GraphQL operation not yet captured. Right-click "
+            "a Splice sample and click Variations with mitmproxy running. "
+            "See docs/2026-04-22-splice-https-capture-recipe.md."
+        )
+    if not session_token_available:
+        next_steps.append(
+            "Splice desktop app is not reachable — the bridge reads the "
+            "session token via gRPC GetSession RPC. Ensure the app is "
+            "running and logged in."
+        )
+    if not next_steps:
+        next_steps.append("Bridge fully ready — test with splice_describe_sound.")
+
+    return {
+        "ok": True,
+        "base_url": cfg.base_url,
+        "endpoints": endpoints,
+        "verified": verified,
+        "configured_count": configured_count,
+        "unverified_endpoints": unverified,
+        "is_user_configured": cfg.is_user_configured,
+        "session_token_available": session_token_available,
+        "session_token_error": session_token_error,
+        "next_steps": next_steps,
+        "docs": "docs/2026-04-22-splice-https-capture-recipe.md",
+    }

package/mcp_server/server.py

@@ -378,11 +378,21 @@ def _get_all_tools():
             "_local_provider._tools",
             lambda: list(mcp._local_provider._tools.values()),
         ),
-        # Public-API future path (what we're asking for in the upstream FR);
-        # harmless to probe now so that once it ships we can lift the ceiling
-        # without touching this function again.
-        ("list_tools", lambda: list(mcp.list_tools())),
+        # NB: mcp.list_tools() IS the public API, but it's a coroutine —
+        # can't be iterated in a sync context. We skip it here and rely on
+        # the internal probes. When FastMCP exposes a sync view we'll add
+        # it back. (Earlier form tried `list(mcp.list_tools())` which
+        # raised `RuntimeWarning: coroutine was never awaited` at every
+        # module import — removed 2026-04-22.)
     ]
+    # Observation 2026-04-22: some FastMCP 3.x builds keep BOTH the legacy
+    # `_tool_manager._tools` dict AND the newer `_local_provider._components`
+    # registry populated at the same time — but the legacy one lags the
+    # newer one (385 vs 422 during a recent startup). Returning the FIRST
+    # non-empty probe accidentally picked the stale view. Instead, collect
+    # every working probe and return the LARGEST view (the registry with
+    # the most tools is the authoritative one).
+    best: list = []
     for label, fn in probes:
         try:
             tools = fn()
@@ -390,8 +400,10 @@ def _get_all_tools():
             continue
         except Exception:  # noqa: BLE001 — any error from an internal probe means "skip"
             continue
-        if tools:
-            return tools
+        if tools and len(tools) > len(best):
+            best = tools
+    if best:
+        return best
 
     # All probes empty. Surface fastmcp version + attempted paths so the
     # breakage is diagnosable without re-reading the code.

package/mcp_server/splice_client/client.py

@@ -119,6 +119,30 @@ def _try_import_protos():
         return None, None
 
 
+def _read_plan_kind_override() -> Optional[str]:
+    """Read `plan_kind_override` from ~/.livepilot/splice.json, if present.
+
+    Lets the user pin their Splice plan_kind when gRPC data is ambiguous.
+    Example config:
+        {"plan_kind_override": "ableton_live"}
+    Returns None silently on any I/O or JSON error.
+    """
+    import json
+    path = os.path.expanduser("~/.livepilot/splice.json")
+    if not os.path.isfile(path):
+        return None
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        if isinstance(data, dict):
+            value = data.get("plan_kind_override")
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+    except (OSError, json.JSONDecodeError):
+        pass
+    return None
+
+
 class SpliceGRPCClient:
     """Async gRPC client for Splice desktop's App service."""
 
@@ -486,10 +510,15 @@ class SpliceGRPCClient:
                 int(user.SoundsPlan) if hasattr(user, "SoundsPlan") else 0
             )
             uuid_str = str(user.UUID) if hasattr(user, "UUID") else ""
+            # Read optional plan_kind_override from ~/.livepilot/splice.json.
+            # Users who know their Splice plan can pin the classification
+            # here when the gRPC data is ambiguous. See models.classify_plan.
+            override = _read_plan_kind_override()
             plan_kind = classify_plan(
                 sounds_status=user.SoundsStatus,
                 sounds_plan=sounds_plan,
                 features=features,
+                override=override,
             )
             creds = SpliceCredits(
                 credits=user.Credits,
@@ -658,28 +687,71 @@ class SpliceGRPCClient:
 
     # ── Packs ───────────────────────────────────────────────────────
 
-    async def get_pack_info(self, pack_uuid: str) -> Optional[SplicePack]:
-        """Fetch metadata for a single sample pack."""
+    async def get_pack_info(
+        self, pack_uuid: str, max_pages: int = 5,
+    ) -> tuple[Optional[SplicePack], Optional[str]]:
+        """Fetch metadata for a single sample pack.
+
+        Splice's gRPC `App` service does NOT expose a per-UUID
+        `SamplePackInfo` RPC (only `ListSamplePacks` is published in the
+        service definition — the `SamplePackInfoRequest` / `...Response`
+        messages exist in the descriptor but no RPC binds them). So this
+        implementation paginates `ListSamplePacks` and matches client-side.
+
+        Only finds packs the user has engaged with (owned / downloaded /
+        in their library). Catalog-only packs return None with an
+        explanatory error.
+
+        Returns (pack, error) — `error` is a user-readable string when the
+        lookup didn't find a match.
+        """
         if not self.connected:
-            return None
+            return None, "Splice gRPC not connected"
         pb2 = self._pb2
+        target = pack_uuid.strip()
+        # Splice uses two UUID formats: canonical 36-char and an "extended"
+        # form with a longer last group (observed 43 chars, e.g.
+        # "1170db75-0ce1-5280-bb61-887a0dd7f26bf5a3951"). Both variants
+        # appear in sounds.db and search results. We match BOTH when the
+        # caller submits one form — the other form might be the one the
+        # server returns for the same pack. Observed 2026-04-22.
+        canonical = target[:36] if len(target) > 36 else target
+        targets = {target, canonical}
+        next_token = 0
         try:
-            response = await self.stub.SamplePackInfo(
-                pb2.SamplePackInfoRequest(UUID=pack_uuid),
-                timeout=INFO_TIMEOUT,
-            )
-            p = response.Pack
-            return SplicePack(
-                uuid=p.UUID,
-                name=p.Name,
-                cover_url=p.CoverURL,
-                genre=p.Genre,
-                permalink=p.Permalink,
-                provider_name=p.ProviderName,
-            )
+            for _page in range(max(1, int(max_pages))):
+                response = await self.stub.ListSamplePacks(
+                    pb2.ListSamplePacksRequest(NextToken=next_token),
+                    timeout=INFO_TIMEOUT,
+                )
+                for p in response.SamplePacks:
+                    p_uuid = p.UUID
+                    p_canonical = p_uuid[:36] if len(p_uuid) > 36 else p_uuid
+                    if p_uuid in targets or p_canonical in targets:
+                        return SplicePack(
+                            uuid=p_uuid,
+                            name=p.Name,
+                            cover_url=p.CoverURL,
+                            genre=p.Genre,
+                            permalink=p.Permalink,
+                            provider_name=p.ProviderName,
+                        ), None
+                # If no next-page token, we've exhausted the list.
+                new_token = int(response.NextToken)
+                if new_token == 0 or new_token == next_token:
+                    break
+                next_token = new_token
         except Exception as exc:
-            logger.warning(f"SamplePackInfo failed: {exc}")
-            return None
+            msg = f"ListSamplePacks gRPC call failed: {type(exc).__name__}: {exc}"
+            logger.warning(msg)
+            return None, msg
+        return None, (
+            f"Pack '{target}' not found in the user's library. "
+            "Splice's gRPC only lists packs the user has engaged with "
+            "(owned/downloaded/in library). Catalog-only packs can't be "
+            "looked up via this RPC. Use the Splice website or Desktop app "
+            "to browse un-engaged packs."
+        )
 
     # ── Presets ─────────────────────────────────────────────────────