loopctl-mcp-server 2.67.0 → 2.69.0

package/README.md

@@ -304,6 +304,7 @@ it is enforced server-side and a no-op for a non-superadmin key — see below.)
 | `knowledge_bulk_delete` | **Requires `LOOPCTL_USER_KEY`.** Bulk archive (default, reversible) or IRREVERSIBLE hard-delete by selector. Provide exactly one selector: `article_ids` (list), `source_type`+`source_id` (every active article from a source), or `tag`+`confirm:true` (every active article with the tag — high blast radius). Default = set-based soft archive (idempotent; `meta.count`=archived, `meta.counts`/`meta.results` give the breakdown; ≤5000). **Dry-run** (`dry_run:true`) mutates nothing, returns `meta.would_affect` (with `hard:true` also a single-use `meta.token`, or `meta.confirm_hash` for oversized selectors). **Hard delete** (irreversible): dry-run with `hard:true` for a token, then call again with `hard:true`+`token` to FK-correctly delete the frozen id-set (links first, access events cascade). |
 | `knowledge_drafts` | List draft (unpublished) knowledge articles with pagination. Optional: `limit` (default 20, max 1000 — over-max → 400, no silent clamp), `offset` (default 0), `project_id`. Returns `meta.total_count`. |
 | `knowledge_lint` | Run a lint check on the knowledge wiki to identify stale or low-coverage articles. Optional: `project_id`, `stale_days`, `min_coverage`, `max_per_category` (default 50, max 500). True totals returned in `summary.total_per_category`. |
+| `knowledge_consolidation` | Read the nightly consolidation ("dream") report: NUMBERED proposals for reconciling the corpus, each naming the articles involved and quoting an excerpt from each as evidence. **REPORT ONLY** — the pass writes no articles, links or conflict resolutions; every proposal is `pending` and this tool applies nothing. Classes: `duplicate_capture` (titles that collide once case/punctuation normalize away, or idempotency keys that collide under the same normalization while differing verbatim — capture tag-format drift, which the novelty gate does not catch because novelty scoring and idempotency are separate paths), `contradiction_candidate` (a SYSTEM-flagged `potential_conflict` pair of PUBLISHED articles with no recorded verdict — record one with `knowledge_resolve_conflict`, which accepts exactly these pairs), `generic_title` (a placeholder title that collides on active-title uniqueness and blocks hub creation), `stale_entry`. **Denominators:** `corpus_size` = PUBLISHED articles owned by the tenant at scan time, not its total article count; `proposal_count` = the TRUE pre-cap count of PROPOSALS, not of articles (one duplicate group of three articles is ONE proposal, and one article can appear in proposals of several classes); `persisted_count` = proposal ROWS the report carries, lower than `proposal_count` exactly when a class hit `max_per_class` (`truncated` flags which); `meta.total_count` counts persisted proposals matching the `class` filter, so it is bounded by `persisted_count`, never `proposal_count`. `review_status`/`reviewed_by`/`reviewed_at` reset to pending/null whenever the nightly pass re-derives a proposal — refreshed machine output never inherits an approval. Requires orchestrator role. Optional: `day` (ISO8601, default most recent report), `class`, `limit` (default 50, max 500), `offset`. |
 | `knowledge_export` | Export all knowledge articles as an OKF v0.1 bundle (gzipped tar archive, unbounded, bounded-memory streaming, fail-closed). Returns a curl command for direct download — **the download requires `LOOPCTL_USER_KEY`** (an orchestrator key would 403). Pass `format=json` for buffered in-memory JSON (convenience tool for file writers; capped at `export_max_buffered_export_articles` — returns 413 if over-cap). Optional: `project_id`, `format` (`tar.gz` default or `json`). |
 | `knowledge_ingest` | Submit a URL or raw content for knowledge extraction. Enqueues an Oban job. Extracted articles are **drafts by default** (lower-trust LLM output); pass `publish: true` to publish on extraction. **BYO:** runs on the tenant's own Anthropic key — a keyless tenant gets a 422 whose result leads with an `ACTION REQUIRED` notice pointing at `set_llm_config` (see [First-time setup](#first-time-setup--provision-your-byo-llm-keys)). Required: `source_type`. One of: `url` or `content`. Optional: `project_id`, `publish`. |
 | `knowledge_ingest_batch` | Submit up to 50 ingestion items in a single request. Each item has the same shape as `knowledge_ingest` (incl. `publish`). Returns per-item results. Required: `items`. Optional: batch-level `project_id` / `publish` defaults. |
@@ -326,7 +327,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 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. 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 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`. |
 
 ### Egress / Privacy Tools (US-41.4)
 

package/index.js

@@ -1927,6 +1927,20 @@ async function knowledgeLint({ project_id, stale_days, min_coverage, max_per_cat
   return toContent(result);
 }
 
+async function knowledgeConsolidation({ day, class: klass, limit, offset } = {}) {
+  const params = new URLSearchParams();
+  if (day) params.set("day", String(day));
+  if (klass) params.set("class", String(klass));
+  if (limit != null) params.set("limit", String(limit));
+  if (offset != null) params.set("offset", String(offset));
+  const qs = params.toString();
+  const path = qs
+    ? `/api/v1/knowledge/consolidation?${qs}`
+    : "/api/v1/knowledge/consolidation";
+  const result = await apiCall("GET", path, null, process.env.LOOPCTL_ORCH_KEY);
+  return toContent(result);
+}
+
 async function knowledgeIngest({ url, content, source_type, project_id, publish }) {
   const body = { source_type };
   if (url) body.url = url;
@@ -5447,6 +5461,63 @@ const TOOLS = [
       required: [],
     },
   },
+  {
+    name: "knowledge_consolidation",
+    description:
+      "Read the nightly consolidation (\"dream\") report: NUMBERED proposals for reconciling " +
+      "the corpus, each naming the articles involved and quoting an excerpt from each as " +
+      "evidence. REPORT ONLY — the pass writes no articles, links or conflict resolutions, " +
+      "every proposal is `pending`, and this tool applies nothing. Requires orchestrator role.\n\n" +
+      "Classes: `duplicate_capture` (titles that collide once case/punctuation normalize away, " +
+      "or idempotency keys that collide under the same normalization while differing verbatim — " +
+      "capture tag-format drift, which the novelty gate does not catch because novelty scoring " +
+      "and idempotency are separate paths); `contradiction_candidate` (a SYSTEM-flagged " +
+      "potential_conflict pair of PUBLISHED articles with no recorded verdict — record one via " +
+      "knowledge_resolve_conflict, which accepts exactly these pairs; this report writes " +
+      "none); `generic_title` (a placeholder title that collides on active-title uniqueness and " +
+      "blocks hub creation); `stale_entry` (past the lint staleness threshold, never reconciled).\n\n" +
+      "Denominators: `corpus_size` counts PUBLISHED articles owned by the tenant at scan time, " +
+      "not its total article count. `proposal_count` is the TRUE pre-cap count of PROPOSALS, not " +
+      "of articles — one duplicate group of three articles is ONE proposal, and one article can " +
+      "appear in proposals of several classes. `persisted_count` is how many proposal ROWS the " +
+      "report carries, lower than `proposal_count` exactly when a class hit `max_per_class` " +
+      "(`truncated` flags which). `meta.total_count` counts persisted proposals matching the " +
+      "`class` filter, so it is bounded by `persisted_count`, never by `proposal_count`.\n\n" +
+      "Review state (`review_status`/`reviewed_by`/`reviewed_at`) RESETS to pending/null whenever " +
+      "the nightly pass re-derives a proposal: refreshed machine output never inherits an approval.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        day: {
+          type: "string",
+          description:
+            "Optional ISO8601 date (YYYY-MM-DD, UTC) of the report to read. Defaults to the most recent report.",
+        },
+        class: {
+          type: "string",
+          enum: [
+            "duplicate_capture",
+            "contradiction_candidate",
+            "generic_title",
+            "stale_entry",
+          ],
+          description: "Optional: return only proposals of this class.",
+        },
+        limit: {
+          type: "integer",
+          description: "Proposals per page. Default 50, max 500 (clamped, never rejected).",
+          default: 50,
+          minimum: 1,
+        },
+        offset: {
+          type: "integer",
+          description: "Proposals to skip. Default 0.",
+          minimum: 0,
+        },
+      },
+      required: [],
+    },
+  },
   {
     name: "knowledge_export",
     description:
@@ -6042,10 +6113,36 @@ const TOOLS = [
     name: "knowledge_retrieval_metrics",
     description:
       "Return the daily retrieval-PRECISION time series (agents' KB #3): for each day, the " +
-      "share of search results the agent then opened (search → get/context 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.",
+      "share of RECORDED surfaced search RESULTS the agent then opened (search → get/context " +
+      "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" +
+      // 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 " +
+      "RECORDED surfaced RESULTS — one row per result put in front of the agent, capped at " +
+      "the first 20 per call — not search calls (`results_recorded` is the same number, " +
+      "named for its unit). Because of that cap precision is precision@20: a call returning " +
+      "more results contributes only 20 to `searched`, and an open of a result ranked beyond " +
+      "the cap is in neither term. The per-CALL rate is separate: `search_follow_through` = " +
+      "searches_with_follow_through / searches — the share of QUERY-BEARING SEARCHES that " +
+      "led to an open. `results_returned` is the true un-truncated result count for those " +
+      "same calls, so it exceeds the rows those calls wrote whenever a page hit the cap.\n\n" +
+      "Call-level population: the four call-level fields are filtered per ROW, not per day " +
+      "— a row counts only if it carries a search identity (nothing recorded before #582 " +
+      "does) and is not a query-less enumeration page (list / list_keyset; browsing is not " +
+      "searching). A day that mixes qualifying and non-qualifying rows reports a PARTIAL " +
+      "searches / results_returned, not 0. Do NOT compare results_returned against " +
+      "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 " +
+      "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).",
     inputSchema: {
       type: "object",
       properties: {
@@ -6873,6 +6970,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "knowledge_lint":
       return await knowledgeLint(args);
 
+    case "knowledge_consolidation":
+      return await knowledgeConsolidation(args);
+
     case "knowledge_export":
       return await knowledgeExport(args);
 

package/package.json

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