livepilot 1.16.1 → 1.17.1

package/mcp_server/sample_engine/tools.py

@@ -259,14 +259,10 @@ async def search_samples(
     # 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"):
-        grpc_client = None
-        try:
-            grpc_client = ctx.lifespan_context.get("splice_client")
-        except AttributeError:
-            grpc_client = None
+        grpc_client = await _ensure_splice_client_connected(ctx)
 
         used_grpc = False
-        if grpc_client is not None and getattr(grpc_client, "connected", False):
+        if grpc_client is not None:
             try:
                 grpc_result = await grpc_client.search_samples(
                     query=query,
@@ -712,6 +708,43 @@ _SPLICE_USER_LIB_DEST = "~/Music/Ableton/User Library/Samples/Splice"
 _SPLICE_PREVIEW_CACHE = "~/Library/Caches/LivePilot/splice_previews"
 
 
+def _get_splice_client_from_context(ctx: Context):
+    """Return the shared Splice client from lifespan context when present."""
+    try:
+        return ctx.lifespan_context.get("splice_client")
+    except AttributeError:
+        return None
+
+
+async def _ensure_splice_client_connected(ctx: Context):
+    """Reconnect the shared Splice client on demand.
+
+    The MCP server creates one long-lived client during startup. If that
+    first handshake races or Splice launches later, the old behavior kept
+    every tool stuck in a disconnected state until the whole MCP server
+    restarted. Re-check here so tool results reflect current desktop state.
+    """
+    client = _get_splice_client_from_context(ctx)
+    if client is None:
+        return None
+    if getattr(client, "connected", False):
+        return client
+
+    connect = getattr(client, "connect", None)
+    if connect is None:
+        return None
+
+    try:
+        await connect()
+    except Exception as exc:
+        logger.debug("Splice reconnect failed: %s", exc)
+        return None
+
+    if getattr(client, "connected", False):
+        return client
+    return None
+
+
 @mcp.tool()
 async def get_splice_credits(ctx: Context) -> dict:
     """Get the user's current Splice plan, credits, and daily sample quota.
@@ -745,15 +778,10 @@ async def get_splice_credits(ctx: Context) -> dict:
     from ..splice_client.models import PlanKind
     from ..splice_client.quota import get_tracker
 
-    client = None
-    try:
-        client = ctx.lifespan_context.get("splice_client")
-    except AttributeError:
-        pass
-
     quota_summary = get_tracker().summary()
+    client = await _ensure_splice_client_connected(ctx)
 
-    if client is None or not getattr(client, "connected", False):
+    if client is None:
         return {
             "connected": False,
             "username": "",
@@ -857,13 +885,8 @@ async def splice_catalog_hunt(
     Each sample entry contains `file_hash` which you can pass to
     `splice_download_sample` to trigger a download.
     """
-    client = None
-    try:
-        client = ctx.lifespan_context.get("splice_client")
-    except AttributeError:
-        pass
-
-    if client is None or not getattr(client, "connected", False):
+    client = await _ensure_splice_client_connected(ctx)
+    if client is None:
         return {
             "connected": False,
             "error": "Splice gRPC not connected",
@@ -970,13 +993,8 @@ async def splice_download_sample(
     """
     import shutil
 
-    client = None
-    try:
-        client = ctx.lifespan_context.get("splice_client")
-    except AttributeError:
-        pass
-
-    if client is None or not getattr(client, "connected", False):
+    client = await _ensure_splice_client_connected(ctx)
+    if client is None:
         return {
             "ok": False,
             "error": "Splice gRPC not connected",
@@ -1096,13 +1114,8 @@ async def splice_preview_sample(
     import urllib.request
     import urllib.error
 
-    client = None
-    try:
-        client = ctx.lifespan_context.get("splice_client")
-    except AttributeError:
-        pass
-
-    if client is None or not getattr(client, "connected", False):
+    client = await _ensure_splice_client_connected(ctx)
+    if client is None:
         return {"ok": False, "error": "Splice gRPC not connected"}
 
     # Two-stage lookup: SampleInfo is the fast path but only returns
@@ -1184,14 +1197,10 @@ async def splice_preview_sample(
 # ────────────────────────────────────────────────────────────────────────
 
 
-def _require_splice_client(ctx: Context) -> tuple[object, Optional[dict]]:
+async def _require_splice_client(ctx: Context) -> tuple[object, Optional[dict]]:
     """Fetch the Splice client from context, or return an error dict."""
-    client = None
-    try:
-        client = ctx.lifespan_context.get("splice_client")
-    except AttributeError:
-        pass
-    if client is None or not getattr(client, "connected", False):
+    client = await _ensure_splice_client_connected(ctx)
+    if client is None:
         return None, {"ok": False, "error": "Splice gRPC not connected"}
     return client, None
 
@@ -1215,7 +1224,7 @@ async def splice_list_collections(
       ],
     }
     """
-    client, err = _require_splice_client(ctx)
+    client, err = await _require_splice_client(ctx)
     if err:
         return err
     total, collections = await client.list_collections(
@@ -1244,7 +1253,7 @@ async def splice_search_in_collection(
     `splice_catalog_hunt` — you can feed them straight into
     `splice_preview_sample` or `splice_download_sample`.
     """
-    client, err = _require_splice_client(ctx)
+    client, err = await _require_splice_client(ctx)
     if err:
         return err
     total, samples = await client.collection_samples(
@@ -1271,7 +1280,7 @@ async def splice_add_to_collection(
     and web UI immediately. Use this to let LivePilot "save for later"
     items it finds during composition work.
     """
-    client, err = _require_splice_client(ctx)
+    client, err = await _require_splice_client(ctx)
     if err:
         return err
     if not file_hashes:
@@ -1289,7 +1298,7 @@ async def splice_remove_from_collection(
     ctx: Context, collection_uuid: str, file_hashes: list[str],
 ) -> dict:
     """Remove one or more samples from a user Collection (server-side)."""
-    client, err = _require_splice_client(ctx)
+    client, err = await _require_splice_client(ctx)
     if err:
         return err
     if not file_hashes:
@@ -1307,7 +1316,7 @@ async def splice_remove_from_collection(
 @mcp.tool()
 async def splice_create_collection(ctx: Context, name: str) -> dict:
     """Create a new user Collection. Returns the new UUID on success."""
-    client, err = _require_splice_client(ctx)
+    client, err = await _require_splice_client(ctx)
     if err:
         return err
     name = (name or "").strip()
@@ -1347,7 +1356,7 @@ async def splice_list_presets(
       ],
     }
     """
-    client, err = _require_splice_client(ctx)
+    client, err = await _require_splice_client(ctx)
     if err:
         return err
     total, presets = await client.list_purchased_presets(
@@ -1371,7 +1380,7 @@ async def splice_preset_info(
     plugin_name: str = "",
 ) -> dict:
     """Fetch metadata for a single preset (uuid, file_hash, or plugin_name)."""
-    client, err = _require_splice_client(ctx)
+    client, err = await _require_splice_client(ctx)
     if err:
         return err
     if not (uuid or file_hash or plugin_name):
@@ -1394,7 +1403,7 @@ async def splice_download_preset(ctx: Context, uuid: str) -> dict:
     """
     from ..splice_client.client import CREDIT_HARD_FLOOR
 
-    client, err = _require_splice_client(ctx)
+    client, err = await _require_splice_client(ctx)
     if err:
         return err
     if not uuid:
@@ -1437,7 +1446,7 @@ async def splice_pack_info(ctx: Context, pack_uuid: str) -> dict:
     Useful for discovering related samples by pack, or surfacing pack-level
     genre/provider info that search results omit.
     """
-    client, err = _require_splice_client(ctx)
+    client, err = await _require_splice_client(ctx)
     if err:
         return err
     if not pack_uuid:
@@ -1469,19 +1478,15 @@ async def splice_pack_info(ctx: Context, pack_uuid: str) -> dict:
 # ────────────────────────────────────────────────────────────────────────
 
 
-def _build_http_bridge(ctx: Context):
+async def _build_http_bridge(ctx: Context):
     """Construct the HTTPS bridge with the current gRPC client attached.
 
     Returns (bridge, err_dict). On success err_dict is None.
     """
     from ..splice_client.http_bridge import SpliceHTTPBridge
 
-    client = None
-    try:
-        client = ctx.lifespan_context.get("splice_client")
-    except AttributeError:
-        pass
-    if client is None or not getattr(client, "connected", False):
+    client = await _ensure_splice_client_connected(ctx)
+    if client is None:
         return None, {
             "ok": False,
             "error": "Splice gRPC not connected — session token unreachable",
@@ -1496,25 +1501,31 @@ 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)
+    bridge, err = await _build_http_bridge(ctx)
     if err:
         return err
     from ..splice_client.http_bridge import SpliceHTTPError
@@ -1524,95 +1535,157 @@ 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)
+    bridge, err = await _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).
+@mcp.tool()
+async def splice_http_diagnose(ctx: Context) -> dict:
+    """Diagnose the Splice HTTPS bridge configuration and readiness.
 
-    **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.
+    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`.
 
-    audio_path: absolute path to a local audio file (.wav, .mp3, .flac)
-    limit:      max results (default 20)
+    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}"}
-    try:
-        result = await bridge.search_with_sound(
-            audio_path=audio_path, limit=int(limit),
+    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 = await _ensure_splice_client_connected(ctx)
+    if grpc_client is None:
+        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",
+    }