loopctl-mcp-server 2.78.1 → 2.78.2

package/README.md

@@ -329,7 +329,7 @@ it is enforced server-side and a no-op for a non-superadmin key — see below.)
 | `knowledge_agent_usage` | Per-agent knowledge usage: total reads, unique articles, top read articles. Required: exactly one of `api_key_id` (credential) or `agent_id` (logical identity). Optional: `limit`, `since_days`. See Wiki Attribution section. |
 | `knowledge_unused_articles` | Published articles with zero accesses in the window. Optional: `days_unused` (default 30), `limit` (default 50, max 200). |
 | `knowledge_curation_log` | Concise human-readable log of KB CURATION adjustments — novelty-gate decisions (`gate_duplicate`/`gate_draft`/`gate_skip`) and conflict resolutions (`supersede`/`merge`/`dismiss`) — for analyzing the agents'-KB rollout, distinct from the verbose audit log. Each entry: `{at, kind, summary, refs, actor, confidence}`. **RECORDED ONLY when `settings.kb_curation_log` is on** (PATCH `/api/v1/admin/tenants/:id` with `settings:{kb_curation_log:true}`); off by default = no rows. Most recent first. Requires orchestrator role. Optional: `kind`, `since` (ISO8601), `limit` (default 50, max 500), `offset`. |
-| `knowledge_retrieval_metrics` | Daily retrieval-PRECISION time series: for each day, the share of RECORDED surfaced search RESULTS the agent then opened (search → get/context within a window). A proxy for whether retrieval is improving as the corpus is de-duplicated, better navigated (MOCs), and conflict-resolved. **Denominators (#582):** `precision` = `followed_through`/`searched`, where `searched` counts RECORDED surfaced RESULTS — one row per result put in front of the agent, capped at the first 20 per call (cap enforced by `Loopctl.Knowledge.Analytics.max_recorded_search_results/0`) — not search calls (`results_recorded` is the same number named for its unit). That cap makes `precision` precision@20: a call returning more contributes only 20, and an open of a result ranked beyond the cap is in neither term. The per-CALL rate is the separate `search_follow_through` = `searches_with_follow_through`/`searches` (distinct QUERY-BEARING calls — query-less `list`/`list_keyset` enumeration pages are excluded). `results_returned` is the true un-truncated count for those same calls. The four call-level fields are filtered per ROW, not per day, so a day mixing pre-#582 or enumeration rows with real searches reports a PARTIAL figure rather than 0 — and `results_returned` is NOT comparable to `searched`. Zero-result and keyless searches are unrecordable, so both ratios are upper bounds — and both rise when a search returns FEWER results, so never optimise them without the absolute `followed_through`; `search_follow_through` is additionally biased DOWN by the recording cap (opens beyond rank 20 are invisible) and UP by crediting every search in the window that surfaced the opened article. Most recent day first. Requires orchestrator role. Optional: `limit` (default 30, max 365), `offset`. |
+| `knowledge_retrieval_metrics` | Daily retrieval-PRECISION time series: for each day, the share of RECORDED surfaced search RESULTS the agent then opened (search → get/context within a window). A proxy for whether retrieval is improving as the corpus is de-duplicated, better navigated (MOCs), and conflict-resolved. **Denominators (#582):** `precision` = `followed_through`/`searched`, where `searched` counts RECORDED surfaced RESULTS — one row per result put in front of the agent, capped at the first 20 per call (cap enforced by `Loopctl.Knowledge.Analytics.max_recorded_search_results/0`) — not search calls (`results_recorded` is the same number named for its unit). That cap makes `precision` precision@20: a call returning more contributes only 20, and an open of a result ranked beyond the cap is in neither term. The per-CALL rate is the separate `search_follow_through` = `searches_with_follow_through`/`searches` (distinct QUERY-BEARING calls — query-less `list`/`list_keyset` enumeration pages are excluded). `results_returned` is the true un-truncated count for those same calls. The four call-level fields are filtered per ROW, not per day, so a day mixing pre-#582 or enumeration rows with real searches reports a PARTIAL figure rather than 0 — and `results_returned` is NOT comparable to `searched`. Zero-result and keyless searches are unrecordable, so every ratio here is an upper bound. **`precision` ALONE rises when a search returns FEWER results** — its denominator counts surfaced RESULTS, while the two call-level rates divide CALL counts a narrower page does not shrink — so never optimise `precision` without the absolute `followed_through`. Both follow-through rates are biased DOWN by the recording cap (opens beyond rank 20 are invisible) and UP by crediting every search in the window that surfaced the opened article. **WHICH FOLLOW-THROUGH RATE TO QUOTE:** two are published over DIFFERENT populations, and picking the wrong one misstates agent behaviour by roughly 3.4x. `search_follow_through` is over every query-bearing call that survives the infrastructure exclusion — which still INCLUDES the recall hook and the session-start auto-query, channels that cannot follow through by construction — so read it as BLENDED and use it for total traffic. `scored_follow_through` = `searches_scored_with_follow_through`/`searches_scored` is over the calls carrying a session identity AND coming from a channel that can react to a result, and **IT is the rate to quote when asking whether AGENTS are consuming the KB**. It is `null` when nothing was scoreable, never `0.0` — zero would assert agents searched and opened nothing when the truth is the instrument could not see. Measured live for 2026-08-19..29: 10.8% blended against 38.0% scored, because the recall hook alone was 1,234 of that window's 1,708 calls. Most recent day first. Requires orchestrator role. Optional: `limit` (default 30, max 365), `offset`. |
 
 ### Egress / Privacy Tools (US-41.4)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopctl-mcp-server",
-  "version": "2.78.1",
+  "version": "2.78.2",
   "description": "MCP server for loopctl — structural trust for AI development loops",
   "type": "module",
   "main": "index.js",