loopctl-mcp-server 2.71.0 → 2.72.0

package/README.md

@@ -304,7 +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 — non-destructive, but NOT reversible by any call: `:archived` is terminal and restoring needs a user-role PATCH) 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. **This tool** applies nothing and recomputes nothing — it returns persisted rows. **The pass** it reports on does write: since #608 the nightly run UNPUBLISHES the losers of each `duplicate_capture` group that two consecutive reports both propose. That is its only write to `articles`, it is an unpublish and never an archive (archive is terminal for an article), and it still writes no links or conflict resolutions. 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), `generic_title` (a placeholder title that collides on active-title uniqueness and blocks hub creation). Two classes are **RETIRED** (#605) and no longer produced, though the `class` filter still accepts them so historical reports stay readable: `contradiction_candidate` (the nightly lint judges those pairs itself now) and `stale_entry` (age is not a defect signal — for stale articles call `knowledge_lint`, which computes them with a caller-chosen `stale_days`). **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` are vestigial — nothing reads them to decide anything, there is no approve/reject surface and there will not be one (#605 supersedes #594); auto-apply is gated on reversibility and two-run agreement. They still reset to pending/null whenever the nightly pass re-derives a proposal, so refreshed machine output never inherits an earlier verdict. Requires orchestrator role. Optional: `day` (ISO8601, default most recent report), `class`, `limit` (default 50, max 500), `offset`. |
+| `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. **This tool** applies nothing and recomputes nothing — it returns persisted rows. **The pass** it reports on does write: since #608 the nightly run UNPUBLISHES the losers of each `duplicate_capture` group that two consecutive reports both propose (consecutive meaning the previous report is at most 2 days older, so one skipped nightly run is tolerated and a longer outage is not). That is its only write to `articles`, it is an unpublish and never an archive (archive is terminal for an article), and it still writes no links or conflict resolutions. 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), `generic_title` (a placeholder title that collides on active-title uniqueness and blocks hub creation). Two classes are **RETIRED** (#605) and no longer produced, though the `class` filter still accepts them so historical reports stay readable: `contradiction_candidate` (the nightly lint judges those pairs itself now) and `stale_entry` (age is not a defect signal — for stale articles call `knowledge_lint`, which computes them with a caller-chosen `stale_days`). **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` are vestigial — nothing reads them to decide anything, there is no approve/reject surface and there will not be one (#605 supersedes #594); auto-apply is gated on reversibility and two-run agreement. They still reset to pending/null whenever the nightly pass re-derives a proposal, so refreshed machine output never inherits an earlier verdict. 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. |

package/index.js

@@ -1942,12 +1942,16 @@ async function knowledgeConsolidation({ day, class: klass, limit, offset } = {})
   return toContent(result);
 }
 
-async function knowledgeIngest({ url, content, source_type, project_id, publish }) {
+async function knowledgeIngest({ url, content, source_type, project_id, publish, metadata }) {
   const body = { source_type };
   if (url) body.url = url;
   if (content) body.content = content;
   if (project_id) body.project_id = project_id;
   if (publish) body.publish = true;
+  // Forwarded so `metadata.source_ref` is reachable at all: the server honours it as the
+  // source that article titles are qualified with, and declaring it in the schema above
+  // without forwarding it here would advertise a parameter that silently does nothing.
+  if (metadata && typeof metadata === "object") body.metadata = metadata;
   const result = await apiCall("POST", "/api/v1/knowledge/ingest", body, process.env.LOOPCTL_ORCH_KEY);
   // A keyless tenant gets a 422 (code no_api_key) carrying a remediation — surface it
   // prominently so a first-time agent knows to call set_llm_config before ingesting.
@@ -5492,7 +5496,9 @@ const TOOLS = [
       "the corpus, each naming the articles involved and quoting an excerpt from each as " +
       "evidence. THIS TOOL applies nothing and recomputes nothing — it returns persisted rows. " +
       "The PASS it reports on does write: since #608 the nightly run UNPUBLISHES the losers of " +
-      "each `duplicate_capture` group that two consecutive reports both propose. That is its " +
+      "each `duplicate_capture` group that two consecutive reports both propose — consecutive " +
+      "meaning the previous report is at most 2 days older, so ONE skipped nightly run is " +
+      "tolerated and a longer outage is not. That is its " +
       "only write to articles, it is an unpublish and never an archive (archive is terminal for " +
       "an article), and it still writes no links or conflict resolutions. Requires orchestrator " +
       "role.\n\n" +
@@ -5665,6 +5671,25 @@ const TOOLS = [
           description:
             "Optional: publish extracted articles immediately instead of staging them as drafts (default false).",
         },
+        metadata: {
+          type: "object",
+          description:
+            "Optional metadata map. `source_ref` is the one key with behaviour: it names the " +
+            "SPECIFIC source (a URL, repo, or document name) and is what lets extracted article " +
+            "titles qualify themselves — without it a CHANGELOG file can only become an article " +
+            "titled \"Changelog\", which is indistinguishable from every other document's " +
+            "changelog once it is in the corpus. It overrides the name derived from `url`, and " +
+            "is the ONLY way to name the source of an inline `content` ingest. Its value is " +
+            "included in the extraction prompt POSTed to the tenant's LLM provider (reduced the " +
+            "same way a url is: userinfo and query string stripped, host and path kept). Omit it " +
+            "rather than passing a placeholder — a model will qualify a title WITH it.",
+          properties: {
+            source_ref: {
+              type: "string",
+              description: "The specific source that article titles are qualified with.",
+            },
+          },
+        },
       },
       required: ["source_type"],
     },
@@ -5710,7 +5735,19 @@ const TOOLS = [
               },
               metadata: {
                 type: "object",
-                description: "Optional metadata map.",
+                description:
+                  "Optional metadata map. Set `source_ref` to the SPECIFIC source (URL, repo, " +
+                  "or document name) so extracted titles qualify themselves — without it a " +
+                  "CHANGELOG becomes an article titled \"Changelog\", indistinguishable from " +
+                  "every other document's changelog in the corpus. Overrides the url-derived " +
+                  "name, and is the only way to name an inline `content` item. Sent to the " +
+                  "LLM provider in the extraction prompt. Omit rather than passing a placeholder.",
+                properties: {
+                  source_ref: {
+                    type: "string",
+                    description: "The specific source that article titles are qualified with.",
+                  },
+                },
               },
             },
             required: ["source_type"],

package/package.json

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