fix(langfuse): make score readback robust

Author: NeuralEmpowerment

docs/runbooks/langfuse-observability.md

@@ -157,6 +157,42 @@ tailscale up
 tailscale status
 ```
 
+Recommended tailnet policy pattern, matching the HomeLab per-service tag
+convention:
+
+```jsonc
+{
+  "tagOwners": {
+    "tag:langfuse": ["autogroup:owner"],
+    "tag:agents": ["autogroup:owner"]
+  },
+  "grants": [
+    {
+      "src": ["tag:agents"],
+      "dst": ["tag:langfuse"],
+      "ip": ["tcp:3000"]
+    },
+    {
+      "src": ["autogroup:admin"],
+      "dst": ["tag:langfuse"],
+      "ip": ["tcp:3000"]
+    }
+  ]
+}
+```
+
+If the Mac mini already wears other service tags, add `tag:langfuse` to the
+same device. Owner-managed devices can self-advertise this tag when
+`autogroup:owner` is listed in `tagOwners`:
+
+```bash
+sudo tailscale up --advertise-tags=tag:langfuse
+```
+
+Agent VPSs or long-lived agent hosts should wear `tag:agents` if they are not
+operator-admin devices. That keeps LangFuse reachable to agent infrastructure
+without opening the rest of the Mac mini.
+
 Pick one stable address for `LANGFUSE_BASE_URL`:
 
 - MagicDNS name, for example `http://mac-mini.tailnet-name.ts.net:3000`
@@ -173,6 +209,13 @@ reverse proxy and use:
 export LANGFUSE_BASE_URL=https://langfuse.example.com
 ```
 
+Reachability check from each client:
+
+```bash
+LANGFUSE_BASE_URL=http://mac-mini.tailnet-name.ts.net:3000 \
+  scripts/langfuse-local.sh health
+```
+
 ## Client Setup
 
 Run these steps on every MacBook, Mac mini shell, VPS, or long-lived workspace

plugins/observability/mcp/langfuse_server.py

@@ -569,13 +569,16 @@ def _direct_langfuse_scores(self, args: dict[str, Any]) -> dict[str, Any]:
         trace_id = args.get("trace-id") or (langfuse_trace_id_for_run(args["run-id"]) if args.get("run-id") else None)
         base_url = _langfuse_api_base_url(args.get("langfuse-base-url"))
         params: dict[str, Any] = {"limit": int(args.get("limit") or 20), "page": 1}
-        if trace_id:
-            params["traceId"] = trace_id
+        # LangFuse self-host score list filters can under-return when several
+        # filters are combined. Query with one narrowing backend filter and
+        # enforce the full request below in _filter_score_rows.
         if args.get("score-ids"):
             params["scoreIds"] = args["score-ids"]
-        if args.get("name"):
+        elif trace_id:
+            params["traceId"] = trace_id
+        elif args.get("name"):
             params["name"] = args["name"]
-        if args.get("data-type"):
+        elif args.get("data-type"):
             params["dataType"] = str(args["data-type"]).upper()
         endpoint = f"{base_url}/api/public/scores?{parse.urlencode(params)}"
         response = _langfuse_request("GET", endpoint)

providers/workspaces/interactive-tmux/driver-rs/src/langfuse.rs

@@ -2075,16 +2075,16 @@ fn build_langfuse_scores_list_url(
 ) -> String {
     let base = langfuse_api_base_url(base_url);
     let mut params = vec![format!("limit={limit}"), format!("page={page}")];
-    if let Some(trace_id) = non_empty_str(trace_id) {
-        params.push(format!("traceId={}", url_query_encode(trace_id)));
-    }
+    // LangFuse self-host score list filters can under-return when several
+    // filters are combined. Send one narrowing filter to the backend, then
+    // enforce every requested filter in summarize_langfuse_scores_response.
     if let Some(score_ids) = non_empty_str(score_ids) {
         params.push(format!("scoreIds={}", url_query_encode(score_ids)));
-    }
-    if let Some(name) = non_empty_str(name) {
+    } else if let Some(trace_id) = non_empty_str(trace_id) {
+        params.push(format!("traceId={}", url_query_encode(trace_id)));
+    } else if let Some(name) = non_empty_str(name) {
         params.push(format!("name={}", url_query_encode(name)));
-    }
-    if let Some(data_type) = non_empty_str(data_type) {
+    } else if let Some(data_type) = non_empty_str(data_type) {
         params.push(format!("dataType={}", url_query_encode(data_type)));
     }
     format!(
@@ -2347,7 +2347,38 @@ mod tests {
 
         assert_eq!(
             url,
-            "https://langfuse.example.com/api/public/scores?limit=10&page=2&traceId=trace%20id%2Fwith%20spaces&scoreIds=score-a%2Cscore-b&name=agentic.learning_loop_probe&dataType=BOOLEAN"
+            "https://langfuse.example.com/api/public/scores?limit=10&page=2&scoreIds=score-a%2Cscore-b"
+        );
+    }
+
+    #[test]
+    fn langfuse_scores_list_url_uses_single_backend_filter_then_local_filtering() {
+        let trace_and_name = build_langfuse_scores_list_url(
+            "https://langfuse.example.com",
+            Some("trace-wanted"),
+            None,
+            Some("agentic.learning_loop_probe"),
+            Some("BOOLEAN"),
+            20,
+            1,
+        );
+        assert_eq!(
+            trace_and_name,
+            "https://langfuse.example.com/api/public/scores?limit=20&page=1&traceId=trace-wanted"
+        );
+
+        let name_and_type = build_langfuse_scores_list_url(
+            "https://langfuse.example.com",
+            None,
+            None,
+            Some("agentic.learning_loop_probe"),
+            Some("BOOLEAN"),
+            20,
+            1,
+        );
+        assert_eq!(
+            name_and_type,
+            "https://langfuse.example.com/api/public/scores?limit=20&page=1&name=agentic.learning_loop_probe"
         );
     }
 

scripts/langfuse-local.sh

@@ -17,6 +17,7 @@ Commands:
   start|up  Run docker compose up -d from the cloned LangFuse repository
   stop|down Run docker compose down from the cloned LangFuse repository
   status    Run docker compose ps from the cloned LangFuse repository
+  health    Check the configured LangFuse public health endpoint
   smoke     Run the official-plugin setup/readiness check against local env
 
 Environment:
@@ -162,6 +163,11 @@ EOF
   status)
     compose_run ps
     ;;
+  health)
+    load_local_env
+    curl -fsS "$LANGFUSE_BASE_URL/api/public/health"
+    printf '\nLangFuse health check passed for %s\n' "$LANGFUSE_BASE_URL"
+    ;;
   smoke)
     ensure_local_files
     load_local_env