loopctl-mcp-server 2.87.0 → 2.89.0

package/README.md

@@ -320,7 +320,7 @@ exhausting a paginated walk is not the same as the row being absent.
 | `knowledge_conflicts` | List potential-conflict article pairs — published articles flagged "too similar to comfortably coexist" by the auto-linker / nightly lint sweep, highest-overlap first. The KB only FLAGS the pair; it does NOT decide redundancy-vs-contradiction — that's your call with live context. Each entry has both articles (id/title/status/category) + similarity. Then merge (supersede one, `knowledge_create` the merged article, or PATCH) or reconcile if they genuinely disagree. Paginated with `total_count` in meta. Agent role. Optional: `limit` (default 50, max 1000, clamped), `offset`, `origin` (`system` or `asserted` — asserted rows lead the default ordering, so pass `system` to review machine-flagged pairs alone). |
 | `knowledge_assert_conflict` | **ASSERT** a conflict between two articles the system never flagged — the way to contest an article you just deliberately refuted. `knowledge_resolve_conflict` only reaches pairs the AUTO-LINKER flagged by similarity, which is exactly wrong for a correction: the pair is minutes old (the nightly linker has not run) and a good correction argues about the CONCLUSION, so it may never be similar enough to be flagged at all. The pair then appears in `knowledge_conflicts` with `origin: "asserted"` and your claim attached, and in both articles' `potential_conflicts`. **It retires, hides and down-ranks nothing**, and does not remove either article from curated answers (that still needs a system flag). **And you cannot judge your own assertion** — `knowledge_resolve_conflict` returns `409 self_asserted_conflict` to the asserting key, because you named both ids; another key decides. Idempotent per pair (`created: false` on a re-assert; never overwrites a system flag's provenance). Agent role. Required: `source_article_id`, `target_article_id`, `evidence`. Optional: `classification`, `proposed_authoritative_article_id`. |
 | `knowledge_resolve_conflict` | Record YOUR verdict on a potential-conflict pair (from `knowledge_conflicts`). Dispositions: `dismiss` (false positive, drops from queue), `supersede` (one wins — pass `authoritative_article_id`; nightly executor links + retires loser, only at `confidence:"high"`, reversible/audited), `merge` (at high confidence an LLM synthesizes both into ONE new DRAFT, sources preserved, never auto-published). Non-destructive at agent role — you record intent, the privileged nightly job executes. Only pairs with a real flag are reachable; for a pair that was never flagged, use `knowledge_assert_conflict` first — and note that a DIFFERENT key must then record the verdict. Last-write-wins per pair. **`supersede` is the one disposition that retires an article unattended**, so its `confidence` is capped server-side: an agent-role `"high"` is recorded as `"medium"` (`data.requested_confidence` + `note` say so) and the pair stays in `knowledge_conflicts` until an orchestrator+ key records it at high; a `high` supersede also REQUIRES `evidence` (422 without it). `merge` is never capped. Sent on `LOOPCTL_AGENT_KEY`, so a pair YOU asserted answers `409 self_asserted_conflict` here by design — another principal (a second session, an orchestrator, a human operator) records that verdict. Required: `source_article_id`, `target_article_id`, `disposition`. Optional: `authoritative_article_id`, `classification`, `evidence` (required for a high supersede), `confidence`. |
-| `knowledge_create` | Create a new knowledge article. File findings, document patterns, or record decisions. **Published immediately by default** (visible per `metadata.visibility` — default `owner` for agent authors, only visible to that agent; `shared` for visibility to all agents) — the response `note` says which outcome occurred. Pass `draft: true` to stage it for later review instead (publish afterwards with `knowledge_publish`). Pass `metadata: {visibility: "shared"}` to make the article visible to other agents; higher roles can set visibility and agent_id explicitly. Pass `idempotency_key` for idempotent capture (re-creating with the same key is a no-op returning the existing article — no partial duplicates). RESERVED TAG NAMESPACE: a tag starting with `idem-` must be `idem-<family>-<digest>` (digest = 12 or 40 lowercase hex chars, e.g. `idem-url-7ebe1ca33431`) or the write is rejected 422 — never silently rewritten; put topics outside that prefix and use `idempotency_key` for idempotent capture. Optional: `category`, `tags`, `project_id`, `draft`, `idempotency_key`, `source_type`, `source_id`, `metadata`. |
+| `knowledge_create` | Create a new knowledge article. File findings, document patterns, or record decisions. **Published immediately by default** (visible per `metadata.visibility` — default `owner` for agent authors, only visible to that agent; `shared` for visibility to all agents) — the response `note` says which outcome occurred. Pass `draft: true` to stage it for later review instead (publish afterwards with `knowledge_publish`). Pass `metadata: {visibility: "shared"}` to make the article visible to other agents; higher roles can set visibility and agent_id explicitly. Pass `idempotency_key` for idempotent capture (re-creating with the same key is a no-op returning the existing article — no partial duplicates). A `deduplicated: true` response carries `content_drift` / `title_drift` when the server supports them (an older loopctl omits the keys — absent means UNKNOWN, never false; the keys' presence is the capability signal, there is no server version to compare against): true means the payload you just sent DIFFERED from the returned article and was discarded. Which side moved is not decidable from your end (the stored article may have been curated or machine-retitled since your last capture), so read it first, and use `knowledge_update` on the returned `data.id` only if that row is your own prior capture and your version is still the intended one. When `gate.verdict` is `duplicate` the returned row was matched by SIMILARITY with no self-exclusion — it may be an article you did not write, or your own earlier capture — so PATCH it only if it is your own prior capture, else merge into it or re-send under a DIFFERENT title with `force: true` (the same title answers 409 title_conflict). RESERVED TAG NAMESPACE: a tag starting with `idem-` must be `idem-<family>-<digest>` (digest = 12 or 40 lowercase hex chars, e.g. `idem-url-7ebe1ca33431`) or the write is rejected 422 — never silently rewritten; put topics outside that prefix and use `idempotency_key` for idempotent capture. Optional: `category`, `tags`, `project_id`, `draft`, `idempotency_key`, `source_type`, `source_id`, `metadata`. |
 | `knowledge_update` | Edit an EXISTING article IN PLACE, **preserving its ID** (IDs are load-bearing — cited in project CLAUDE.mds and cross-links). Fold in a new fact, tidy a hub, retag, or reclassify without churning a new row. Send only the fields to change; `tags` REPLACES the whole array. A changed body/tags re-triggers embedding + auto-linking. Agent role — KB-content curation (non-destructive + audited; the in-place edit overwrites the prior body, so it is not reversible either); visibility-scoped, so another agent's private/owner memory 404s. The reserved `idem-` tag namespace applies here too (see `knowledge_create`). Required: `article_id`. Optional: `title`, `body`, `category`, `tags`, `metadata`. |
 | `knowledge_okf_export` | **Requires `LOOPCTL_USER_KEY`.** Export the wiki as a portable OKF (Open Knowledge Format) v0.1 bundle of markdown files. Writes to `out_dir`, or returns `{files, meta}` inline. |
 | `knowledge_okf_import` | **Requires `LOOPCTL_USER_KEY`.** Import an OKF v0.1 bundle from a local directory. Creates or (with `merge`) updates articles; tolerates and preserves unknown frontmatter. |
@@ -384,7 +384,8 @@ 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 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`. |
+| `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`. Every ratio here divides `search_events` / `article_access_events` columns, so a NULL column shrinks a denominator instead of reporting itself — check `knowledge_search_coverage` before reading a figure here as agent behaviour rather than instrumentation. |
+| `knowledge_search_coverage` | Which DECLARED columns of `search_events` are actually being filled, per search surface, over a bounded window. `search_events` shipped correct and nearly blind — 2 of its first 133 rows carried any `client_*` context, discoverable only by an audit nobody was scheduled to run — so a coverage PROFILE per `tool` declares the columns a correctly-instrumented caller should supply, and a surface emitting NOTHING reads as `rows: 0` (which no audit over existing rows can produce). **It cannot prove a PRESENT column is a CORRECT one:** one MCP process serves a session and every agent it dispatches with an environment frozen at spawn, so it labels every search `main` — such a row is 100% covered here and still wrong about the only thing `client_kind` exists to say. **Populations, not one denominator:** each column names the rows that COULD have carried it — `all`, `ran` (excludes `outcome=rejected`, which has no `mode_used`/`duration_ms` by construction), `agent` (rows carrying `client_kind` or `client_session_id`, i.e. rows that really came through the MCP client; the recall hook and smoke tests call the API directly and can never supply `client_*`). `share_missing` is `null`, never `0.0`, on an empty population. **`client_context` is the one to read FIRST:** the `agent` denominator is built from two of the columns it scores, so a client that sends NOTHING empties it and every `client_*` line reads a clean `0/0` — that figure is the same count over `all`, and it is where a fleet gone blind reports itself (a high share on `memory_recall` is the recall hook and expected). **Required vs enrichable:** `required` is fillable at record time so a miss is a defect; `enrichable` (`client_model`, `client_effort`, `agent_id`) is what no client can send and `mix loopctl.enrich_search_events` fills offline on a schedule — read a recent enrichable share as a floor, since a window ending near now measures the enrichment's lag. **Unprofiled:** every `tool` with rows and no profile is listed (`null` included), and `rows_total` covers the whole window, so a new surface cannot be silently dropped. Requires orchestrator role. Optional: `days` (default 30, max 366), `to` (ISO8601 date or datetime, exclusive upper bound; a bare date is read at 00:00:00Z, and an unparseable value is a 400 rather than a silent fallback to now). |
 
 ### Egress / Privacy Tools (US-41.4)
 

package/index.js

@@ -2504,6 +2504,18 @@ async function knowledgeRetrievalMetrics({ limit, offset } = {}) {
   return toContent(result);
 }
 
+async function knowledgeSearchCoverage({ days, to } = {}) {
+  const params = new URLSearchParams();
+  if (days != null) params.set("days", String(days));
+  if (to) params.set("to", to);
+  const qs = params.toString();
+  const path = qs
+    ? `/api/v1/knowledge/analytics/search-coverage?${qs}`
+    : "/api/v1/knowledge/analytics/search-coverage";
+  const result = await apiCall("GET", path, null, process.env.LOOPCTL_ORCH_KEY);
+  return toContent(result);
+}
+
 async function knowledgeCurationLog({ kind, since, limit, offset } = {}) {
   const params = new URLSearchParams();
   if (kind) params.set("kind", kind);
@@ -5255,7 +5267,21 @@ const TOOLS = [
       "existing article with the same title AND an identical body (ignoring surrounding whitespace), the " +
       "server returns that existing article idempotently (HTTP 200) instead of a 422. A same-title create " +
       "with a DIFFERENT body returns 409 title_conflict — do not retry; choose a different title or PATCH " +
-      "the existing article.",
+      "the existing article. CONTENT DRIFT: a `deduplicated: true` response carries " +
+      "`content_drift` / `title_drift` when the server supports them (an older loopctl omits the " +
+      "keys — treat ABSENT as unknown, never as false; presence of the keys IS the capability " +
+      "signal, there is no server version to compare against); true means the payload you just " +
+      "sent DIFFERS from the returned article and was DISCARDED. Which SIDE moved is not decidable " +
+      "from your end — you may have edited, or the stored article may have been curated by someone " +
+      "else or machine-retitled since your last capture — so READ the returned article first " +
+      "(knowledge_get on `data.id`). Only THEN, and only if the returned row is your own prior " +
+      "capture, apply your version with knowledge_update. When the response also carries " +
+      "`gate.verdict: \"duplicate\"` the returned row was matched by SIMILARITY with no " +
+      "self-exclusion, so it may be an article you did not write OR your own earlier capture: read " +
+      "it, PATCH only your own prior capture, else merge into it or re-send under a DIFFERENT " +
+      "title with force: true (the same title answers 409 title_conflict). Sending `body` as " +
+      "null or a non-string also reports content_drift: the dedup short-circuits before validation, " +
+      "so that is how a broken extraction surfaces instead of reading as in-sync.",
     inputSchema: {
       type: "object",
       properties: {
@@ -5314,7 +5340,10 @@ const TOOLS = [
           description:
             "Optional: stable per-article key for idempotent capture (max 255). Re-creating " +
             "with the same key is a no-op that returns a reference to the existing article " +
-            "(deduplicated; id only, not its body) instead of a partial duplicate. Use a " +
+            "(deduplicated; id only, not its body) instead of a partial duplicate — a changed " +
+            "body is NOT applied and NOT refused, but IS reported as content_drift so a " +
+            "re-running sourcer keeps working while a genuine edit is not lost silently (read the " +
+            "stored article before overwriting it — the other side may have moved). Use a " +
             "HIGH-ENTROPY value (e.g. a content hash) — it is a per-tenant lookup key, not a " +
             "secret, so a guessable key lets another agent in your tenant probe which keys " +
             "exist. Distinct from source_type/source_id (which mark a shared source).",
@@ -6935,6 +6964,11 @@ const TOOLS = [
       "within a window). A proxy for whether retrieval is improving — watch it trend up as " +
       "the corpus is de-duplicated, better navigated (MOCs), and conflict-resolved. Most " +
       "recent day first. Requires orchestrator role.\n\n" +
+      "Every ratio here divides columns of search_events / article_access_events, so a " +
+      "NULL column silently shrinks a denominator rather than reporting itself. " +
+      "knowledge_search_coverage is the companion that says which of those columns are " +
+      "actually being filled, per surface — check it before treating a figure here as " +
+      "a measurement of agent behaviour rather than of instrumentation.\n\n" +
       // The cap is enforced by Loopctl.Knowledge.Analytics.max_recorded_search_results/0
       // (Elixir); this JS string cannot interpolate it, so change both together.
       "Denominators (#582): precision = followed_through / searched, and `searched` counts " +
@@ -7033,6 +7067,69 @@ const TOOLS = [
       required: [],
     },
   },
+  {
+    name: "knowledge_search_coverage",
+    description:
+      "Report which DECLARED columns of search_events are actually being filled, per search " +
+      "surface, over a bounded window. Requires orchestrator role.\n\n" +
+      "WHY IT EXISTS: search_events shipped correct and nearly blind — 2 of its first 133 " +
+      "rows carried any client_* context, and that was discoverable only by an audit nobody " +
+      "was scheduled to run. A declared coverage PROFILE per tool names the columns a " +
+      "correctly-instrumented caller is expected to supply, so a surface emitting NOTHING " +
+      "shows up as rows: 0, which no audit over existing rows can produce. Prior art: " +
+      "MemoRizz v0.8.0 declares the evidence stages a task type must emit and reports the " +
+      "missing stage instead of leaving it to an audit.\n\n" +
+      "WHAT IT CANNOT PROVE: that a PRESENT column is a CORRECT one. client_kind is the " +
+      "worked example — one MCP process serves a session and every agent it dispatches with " +
+      "an environment frozen at spawn, so it labels every search 'main'. Such a row is 100% " +
+      "covered here and still wrong about the only thing that column exists to say; the " +
+      "offline enrichment is what refines it. It also cannot see a search path that records " +
+      "NO row at all.\n\n" +
+      "POPULATIONS, NOT ONE DENOMINATOR: each column names the rows that COULD have carried " +
+      "it, reported as scope/population beside every count. 'all' is every row; 'ran' " +
+      "excludes outcome=rejected (a rejected call never ran, so it has no mode_used and no " +
+      "duration_ms by construction); 'agent' is rows carrying client_kind or " +
+      "client_session_id, i.e. rows that really came through the MCP client — the recall " +
+      "hook and smoke tests call the API directly and can never supply client_*, so scoring " +
+      "them would measure loopctl's own automation. share_missing is null, never 0.0, on an " +
+      "empty population.\n\n" +
+      "CLIENT_CONTEXT: the 'agent' denominator is built from two of the columns it scores, " +
+      "so a client that sends NOTHING empties it and every client_* line then reads a clean " +
+      "0/0. Each profile therefore also carries client_context, scored over 'all', whose " +
+      "missing is the rows that carried NO client context at all — that is where a fleet gone " +
+      "blind reports itself. A high share on memory_recall is the recall hook and expected; a " +
+      "high share on knowledge_search is not.\n\n" +
+      "REQUIRED vs ENRICHABLE: required is what a client or the server can fill at record " +
+      "time, so a miss is a defect. enrichable (client_model, client_effort, agent_id) is " +
+      "what no client can send — the first two do not exist in the MCP server's spawn " +
+      "environment and are filled offline by mix loopctl.enrich_search_events, and agent_id " +
+      "is server-derived from a key that may own no agent. That enrichment runs on a " +
+      "schedule, so a window ending near now measures its LAG: read a recent enrichable " +
+      "share as a floor.\n\n" +
+      "UNPROFILED: every tool value with rows and no declared profile is listed with its row " +
+      "count, null included. rows_total counts the whole window, so rows_total minus the sum " +
+      "of profile rows is exactly the unprofiled traffic — a new surface cannot be silently " +
+      "dropped from the accounting.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        days: {
+          type: "integer",
+          description: "Window length in days back from `to` (default 30, max 366). Clamped, never rejected.",
+          minimum: 1,
+          maximum: 366,
+        },
+        to: {
+          type: "string",
+          description:
+            "ISO8601 date or datetime, exclusive upper bound. Default now. A bare date is " +
+            "read at 00:00:00Z. The window is [from, to). Rejected with 400 when it cannot " +
+            "be parsed — never silently replaced with now.",
+        },
+      },
+      required: [],
+    },
+  },
   {
     name: "knowledge_analytics_top",
     description:
@@ -8225,6 +8322,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "knowledge_retrieval_metrics":
       return await knowledgeRetrievalMetrics(args);
 
+    case "knowledge_search_coverage":
+      return await knowledgeSearchCoverage(args);
+
     case "knowledge_analytics_top":
       return await knowledgeAnalyticsTop(args);
 

package/package.json

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