loopctl-mcp-server 2.55.0 → 2.57.0

package/README.md

@@ -221,7 +221,7 @@ Epic 39 Repo Coordination Bus — a lightweight, tenant-isolated channel for age
 | `get_cost_summary` | orch | Get cost/token usage summary for a project, optionally broken down by `agent`, `epic`, or `model`. |
 | `get_story_token_usage` | orch | Get all token usage records for a single story. |
 | `get_cost_anomalies` | orch | Get cost anomaly alerts — stories or agents exceeding expected budgets. Optionally filter by project. |
-| `get_ingestion_anomalies` | orch | Get ingestion-health anomalies — capture_silence (a source_type stopped producing articles) and high_reject_rate (writes rejected at high rate, persisting no article row). Check whether knowledge capture is still landing AND being accepted. |
+| `get_ingestion_anomalies` | orch | Get ingestion-health anomalies — capture_silence (a source_type stopped producing articles), high_reject_rate (writes rejected at high rate, persisting no article row), and sweep_stalled (the 30-day channel-post retention sweep is no longer enforcing retention, under the reserved source_type `channel_post_sweep`). Check whether knowledge capture is still landing AND being accepted, and whether coordination-bus retention is still enforced. |
 | `set_token_budget` | orch | Set a token budget (in millicents) for a project, epic, story, or agent scope. Requires orchestrator role. |
 
 ### Knowledge Wiki Tools (agent key)
@@ -240,6 +240,9 @@ Epic 39 Repo Coordination Bus — a lightweight, tenant-isolated channel for age
 | Tool | Description |
 |---|---|
 | `knowledge_index` | Browse/paginate the knowledge wiki catalog grouped by category. **Agent callers see only articles they own or marked `shared`.** Honors `category`, `tags`, `offset`, `limit` with deterministic ordering over the filtered set (`meta.categories` reports per-category totals within visibility). Use `fields` (default `id,title,category`; request `tags`/`status`/`updated_at` explicitly; `id` and `category` are always included) to keep the payload small. Optional: `project_id`, `story_id`, `category`, `tags`, `offset`, `limit`, `fields`. |
+| `embedding_status` | This tenant's embedding-dimension state: active dimension, whether semantic recall is available (and the exact reason when it is not), the instance's supported dimension set, whether the shared system-scoped corpus has been materialized for this tenant, and per-dimension row counts. Call it when semantic search under-returns or reports `fallback_reason: semantic_recall_unavailable`. |
+| `embedding_materialize_system_corpus` | Embed the shared SYSTEM-scoped corpus for THIS tenant at its active dimension with this tenant's own credential (system articles are keyword-only until then). Idempotent, batched. |
+| `embedding_reembed` | Move the tenant's whole corpus (articles, per-tenant system-article materializations and agent memories) onto `target_dimension`. Recall keeps serving at the current dimension throughout; the pin flips and stale rows drop only when everything is present at the target. One-time and cost-bearing; requires `LOOPCTL_ORCH_KEY`. |
 | `knowledge_stats` | Aggregate article counts (`total`, `by_category`, `by_status`) via cheap `COUNT(*) GROUP BY` within agent's visible set — no article metadata loaded. Agent callers see only their own and `shared` articles. Counts span all statuses. Optional: `project_id`. |
 | `knowledge_count` | Count articles matching filters **without returning rows** within agent's visible set. Agent callers see only their own and `shared` articles. Same filters as `knowledge_list` (`category`, `status`, `tags`, `match`, `source_type`, `source_id`, `idempotency_key`, `project_id`). With `tags`+`match: all` (+`status`) → "how many published articles tagged both X and Y (that I can see)". Returns `{ count }`. |
 | `knowledge_facets` | Count articles grouped by **distinct tag** within agent's visible set, no rows. Agent callers see only their own and `shared` articles. `tag_prefix` (e.g. `book-`) gives the distinct count of a tag family plus per-member totals. Returns `{ data: { tag: count }, meta: { distinct_count } }`. Optional: `category`, `status`, `tags`, `match`, `project_id`, `limit`. |

package/index.js

@@ -1101,6 +1101,41 @@ async function knowledgeIndex({ project_id, story_id, category, tags, match, off
   return toContent(result);
 }
 
+// US-41.1 — the per-tenant embedding DIMENSION surface. `status` and the system-corpus
+// materialization are agent-role; the re-embed is ORCHESTRATOR-role because its completion
+// step deletes the stale-dimension rows (loopctl reserves data-removing operations for
+// higher roles), so it deliberately does NOT fall back to the agent key.
+async function embeddingStatus() {
+  const result = await apiCall("GET", "/api/v1/knowledge/embeddings", null, process.env.LOOPCTL_AGENT_KEY);
+  return toContent(result);
+}
+
+async function embeddingMaterializeSystemCorpus() {
+  const result = await apiCall(
+    "POST",
+    "/api/v1/knowledge/embeddings/system-corpus",
+    {},
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
+async function embeddingReembed({ target_dimension }) {
+  if (!Number.isInteger(target_dimension) || target_dimension <= 0) {
+    return {
+      content: [{ type: "text", text: "Error: target_dimension must be a positive integer." }],
+      isError: true,
+    };
+  }
+  const result = await apiCall(
+    "POST",
+    "/api/v1/knowledge/embeddings/reembed",
+    { target_dimension },
+    process.env.LOOPCTL_ORCH_KEY,
+  );
+  return toContent(result);
+}
+
 async function knowledgeStats({ project_id }) {
   if (project_id && !UUID_RE.test(project_id)) {
     return {
@@ -3340,9 +3375,13 @@ const TOOLS = [
     name: "get_ingestion_anomalies",
     description:
       "Get ingestion-health anomalies — capture_silence (a source_type that was producing " +
-      "articles has gone silent) and high_reject_rate (writes attempted but rejected at high " +
-      "rate — 409 title_conflict / validation drops that persist no article row). Use to check " +
-      "whether knowledge capture is still landing AND being accepted. Paginated (page/page_size); " +
+      "articles has gone silent), high_reject_rate (writes attempted but rejected at high " +
+      "rate — 409 title_conflict / validation drops that persist no article row), and " +
+      "sweep_stalled (the 30-day channel-post retention sweep is no longer enforcing " +
+      "retention for this tenant — expired coordination-bus posts are still present well " +
+      "past their expires_at; recorded under the reserved source_type channel_post_sweep). " +
+      "Use to check whether knowledge capture is still landing AND being accepted, and " +
+      "whether coordination-bus retention is still being enforced. Paginated (page/page_size); " +
       "advance `page` to enumerate all. Filter by source_type, anomaly_type, resolved status, or " +
       "include archived.",
     inputSchema: {
@@ -3356,10 +3395,11 @@ const TOOLS = [
           type: "string",
           // Keep in sync with Loopctl.Knowledge.IngestionAnomaly @anomaly_types (the
           // server-side Ecto.Enum + the ingestion_anomalies_anomaly_type_check DB CHECK).
-          enum: ["capture_silence", "high_reject_rate"],
+          enum: ["capture_silence", "high_reject_rate", "sweep_stalled"],
           description:
-            'Optional: filter by anomaly type — "capture_silence" (writes stopped) or ' +
-            '"high_reject_rate" (writes rejected at high rate).',
+            'Optional: filter by anomaly type — "capture_silence" (writes stopped), ' +
+            '"high_reject_rate" (writes rejected at high rate), or "sweep_stalled" ' +
+            '(the channel-post retention sweep is not enforcing the 30-day window).',
         },
         resolved: {
           type: "string",
@@ -3547,6 +3587,49 @@ const TOOLS = [
       required: [],
     },
   },
+  {
+    name: "embedding_status",
+    description:
+      "Report this tenant's EMBEDDING DIMENSION state: the active dimension, whether semantic " +
+      "recall is currently available (and the exact reason when it is not — e.g. a non-default " +
+      "dimension whose side-table reads have not been enabled yet), the instance's supported " +
+      "dimension set, whether the shared SYSTEM-scoped corpus has been materialized for this " +
+      "tenant (until it is, those articles are keyword-only), and per-dimension row counts. " +
+      "Call this when semantic search returns fewer results than expected or reports " +
+      "fallback_reason 'semantic_recall_unavailable' — it tells you WHY instead of leaving an " +
+      "empty result set to be misread as 'nothing relevant'.",
+    inputSchema: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "embedding_materialize_system_corpus",
+    description:
+      "Materialize the shared SYSTEM-scoped article corpus for THIS tenant at its active " +
+      "embedding dimension, using this tenant's own embedding credential. System articles " +
+      "cannot be embedded once for everyone (embeddings are BYO), so until this runs they are " +
+      "matched by keyword only for you. Idempotent and batched; safe to call repeatedly.",
+    inputSchema: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "embedding_reembed",
+    description:
+      "Move this tenant's WHOLE corpus (articles, per-tenant system-article materializations " +
+      "and agent memories) onto target_dimension. Recall keeps serving at the CURRENT " +
+      "dimension for the entire run; the recorded dimension is flipped and the stale-dimension " +
+      "rows dropped only once everything is present at the target. ONE-TIME and COST-BEARING — " +
+      "it re-bills your embedding provider for the entire corpus. Requires an ORCHESTRATOR key " +
+      "(the completion step deletes data). An unsupported dimension is rejected with the " +
+      "supported set named.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target_dimension: {
+          type: "integer",
+          description: "The embedding dimension to move to. Must be in the instance's supported set.",
+        },
+      },
+      required: ["target_dimension"],
+    },
+  },
   {
     name: "knowledge_stats",
     description:
@@ -3780,6 +3863,10 @@ const TOOLS = [
       "a keyword and a semantic sub-search, each capped at 100, so up to ~200), or filtered_set " +
       "(list mode: the full set). Do NOT use a relevance-mode total_count to size the wiki — use " +
       "list mode or knowledge_stats. " +
+      "SCORE: in combined mode each result's `score` is a Reciprocal Rank Fusion weight " +
+      "(~0.008-0.016 at the top), NOT a normalized 0..1 confidence — use it only to compare " +
+      "RANK/order within one response; for an absolute 0..1 confidence use knowledge_hybrid_search " +
+      "(meta.confidence). " +
       "Pass story_id when working on a loopctl story so reads attribute correctly. " +
       "When you knowledge_get a result and it carries `potential_conflicts`, resolve it if it's " +
       "material to your task (see knowledge_get / the conflict-resolution wiki playbook). " +
@@ -5937,6 +6024,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "knowledge_index":
       return await knowledgeIndex(args);
 
+    case "embedding_status":
+      return await embeddingStatus();
+
+    case "embedding_materialize_system_corpus":
+      return await embeddingMaterializeSystemCorpus();
+
+    case "embedding_reembed":
+      return await embeddingReembed(args);
+
     case "knowledge_stats":
       return await knowledgeStats(args);
 

package/package.json

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