loopctl-mcp-server 2.78.0 → 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/index.js

@@ -6715,13 +6715,16 @@ const TOOLS = [
       "searched: different row populations, so results_returned < searched is normal on a " +
       "legacy-heavy or browse-heavy day.\n\n" +
       "Caveats: zero-result searches and keyless searches are structurally unrecordable and " +
-      "sit in NO denominator, so both ratios are upper bounds; and both rise if a search " +
-      "simply returns FEWER results, with no better retrieval. Never optimise either alone — " +
-      "read them with the absolute followed_through and the volume fields. " +
-      "search_follow_through carries two further biases pointing OPPOSITE ways: the 20-row " +
+      "sit in NO denominator, so every ratio here is an upper bound; and precision ALONE " +
+      "rises if a search simply returns FEWER results, with no better retrieval — its " +
+      "denominator counts surfaced RESULTS, while the two call-level rates divide CALL " +
+      "counts, which a narrower page does not shrink. Never optimise one alone — read them " +
+      "with the absolute followed_through and the volume fields. BOTH " +
+      "follow-through rates carry two further biases pointing OPPOSITE ways: the 20-row " +
       "recording cap hides opens of results ranked beyond it (DOWN on large pages), while " +
       "one open credits EVERY search in the window that surfaced that article, not just the " +
-      "preceding one (UP when an agent refines and re-searches).\n\n" +
+      "preceding one (UP when an agent refines and re-searches, hardest on " +
+      "scored_follow_through).\n\n" +
       "Exact attribution (unit: READS — not surfaced results, not calls): attributed_opens " +
       "/ cross_key_opens / direct_opens count READ rows by how their originating search was " +
       "established, resolved server-side at write time and never accepted from a caller. " +
@@ -6748,6 +6751,24 @@ const TOOLS = [
       "distilled query per prompt and never see what came back, so they cannot reformulate " +
       "by construction. They stay in every other denominator here, precision included. " +
       "Read searches - searches_scored as n/a, never as zero.\n\n" +
+      "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 — smoke/skill-eval sit in NO denominator here, but the " +
+      "recall hook and the session-start auto-query DO, and neither can follow through by " +
+      "construction. Use it for total traffic through the retrieval path, and read it as " +
+      "BLENDED. scored_follow_through is over searches_scored (a session identity AND 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 this " +
+      "instrument could not see. That nil-for-n/a is THIS field's alone: " +
+      "search_follow_through is non-null and reports 0.0 on a day with no qualifying " +
+      "searches, which is an n/a too — read it beside searches. Measured live for " +
+      "2026-08-19..29: 10.8% blended (185/1,708) against 38.0% scored, because 72% of " +
+      "that blended denominator (1,234/1,708) was recall-hook memory_recall traffic at " +
+      "3.3%; the window's 486 smoke-test calls are in neither figure. Spelled out because " +
+      "leaving the division to the caller already produced one wrong published conclusion " +
+      "while both input columns were documented.\n\n" +
       "COMPARE ROWS ONLY WITHIN A metric_version. Every row carries the version of the " +
       "definition set that produced it. Three changes have already altered what a figure here " +
       "MEANS — searched went from search calls to surfaced results, infrastructure traffic " +

package/package.json

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