loopctl-mcp-server 2.54.0 → 2.56.0

package/README.md

@@ -16,6 +16,14 @@ Or run directly with npx:
 npx loopctl-mcp-server
 ```
 
+### Requirements
+
+- **Node.js >= 20.6.0.** The server makes all outbound HTTPS calls through Node's
+  global `fetch` (undici). Node 20.6.0 is the first release where that transport
+  honors `NODE_EXTRA_CA_CERTS` (the setting used for a custom/self-signed loopctl
+  CA -- see Troubleshooting below). On older runtimes that env var is silently
+  ignored, so the floor is enforced via `engines` in `package.json`.
+
 ## Configuration
 
 Add to your `.mcp.json` (Claude Code) or equivalent MCP config:
@@ -121,7 +129,7 @@ REST endpoint (`PATCH /api/v1/tenants/me/llm-config`), and the docs — so you (
 autonomous agent) can self-remediate without a human. Full agent-tenant lifecycle:
 [`docs/onboarding-agent-tenant.md`](../docs/onboarding-agent-tenant.md).
 
-## Tools (109)
+## Tools
 
 > Plus **per-tenant generated Context Retriever tools** (`cr_*`) appended
 > dynamically at runtime — see [Dynamic per-tenant Context Retriever
@@ -232,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`. |
@@ -324,6 +335,8 @@ nothing changes until a scope opts in.
 | `declare_trusted_endpoint` | Declare a host you attest is YOUR OWN so a `local_only` scope can reach it. **This is an unverified tenant attestation, not network locality** — labelled as such everywhere. Three enforced constraints: PUBLIC addresses only (write time AND pin time), PURPOSE-SCOPED (`inference` / `webhook` / `ingest`), vendor hosts excluded. Carves nothing out of the SSRF denylist. Requires **user** key. |
 | `revoke_trusted_endpoint` | Revoke a declaration. Invalidation is IMMEDIATE and cluster-wide — a revoked declaration does not keep working for the remainder of the pin TTL. Requires **user** key. |
 | `egress_repin` | Recover from a `:pin_stale` error (your box got a new DHCP lease and the pinned address set changed — DISTINCT from `egress_blocked`). Re-resolves and re-pins the host. **Agent** key by design: requiring a human user-role write to recover would contradict loopctl's agent-native, no-UI design. |
+| `custody_claim` | The recorded **egress custody claim** for one article or memory row: the append-only sequence of per-operation postures (create, each embed, each re-embed, each classification, each merge) with the endpoints resolved for THAT operation and their verdicts, plus the aggregate. Rides the existing hash-chained audit log + signed tree heads — each entry carries a `chain_position` and the leaf's `chain_entry_hash`, so `GET /api/v1/audit/sth/{tenant_id}/inclusion/{position}` proves inclusion of *that* leaf, and the leaf's payload names this row by a recomputable `posture_digest`. THREE states, only one an attestation: `no_claim_recorded`, `claim_pending`, `claim_recorded` (`complete` / `partial_history` / `incomplete`). Completeness is measured against a persisted per-row high-water mark, so losing the tail of a sequence is a gap, not a clean claim. `third_party_egress_on_covered_paths` is `false` only for NETWORK-local endpoints; a tenant-declared (unverified) endpoint yields `"tenant_declared_unverified"`. Attests ONLY to the endpoints loopctl called on the paths in `coverage` — never to what those endpoints did afterwards. **Agent** key. |
+| `custody_failures` | Custody posture entries whose chain append was DROPPED after exhausting retries, plus `stale_pending` entries stranded by a flush that died outside its own final-attempt branch. Surfaced rather than silently absent: each `data` entry degrades its row's claim to `incomplete`, and a stranded entry would otherwise read as an in-flight claim forever. **Agent** key. |
 
 ### Discovery Tools
 
@@ -519,7 +532,8 @@ clean one-time bootstrap (no cross-key collision).
 
 - Verify `LOOPCTL_SERVER` is set and reachable
 - Check that the server URL includes the protocol (`https://`)
-- If using a self-signed certificate, set `NODE_TLS_REJECT_UNAUTHORIZED=0` in your environment (not recommended for production)
+- If your loopctl server uses a custom or self-signed CA, set `NODE_EXTRA_CA_CERTS=/path/to/ca.pem` in your environment so Node trusts that CA while keeping TLS certificate verification enabled. This requires **Node >= 20.6.0** (or the >= 18.19.0 backport): this server issues all requests through Node's global `fetch` (undici), which only began honoring `NODE_EXTRA_CA_CERTS` in those releases. On older runtimes the variable is silently ignored and you will still see `unable to verify the first certificate` / self-signed-cert errors -- upgrade Node rather than disabling verification.
+- Do NOT set `NODE_TLS_REJECT_UNAUTHORIZED=0` -- it disables certificate verification for the entire Node process (all outbound TLS), exposing every connection to MITM, not just the loopctl one
 
 ### Authentication errors (401)
 

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 {
@@ -1902,6 +1937,33 @@ async function egressPosture() {
   return toContent(result);
 }
 
+// --- US-41.7: witnessed custody claim ---------------------------------------
+//
+// A READ, at agent role for the same reason egress_posture is: verifying a
+// harvest AFTER the fact must work with the key an agent already holds.
+async function custodyClaim({ subject_type, subject_id } = {}) {
+  if (!subject_type || !subject_id) {
+    throw new Error("subject_type and subject_id are required");
+  }
+  const result = await apiCall(
+    "GET",
+    `/api/v1/custody/claims/${encodeURIComponent(subject_type)}/${encodeURIComponent(subject_id)}`,
+    null,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
+async function custodyFailures() {
+  const result = await apiCall(
+    "GET",
+    "/api/v1/custody/failures",
+    null,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
 async function setLocalOnly({ project_id, acknowledge } = {}) {
   const body = {};
   if (project_id != null) body.project_id = project_id;
@@ -3520,6 +3582,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:
@@ -3753,6 +3858,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). " +
@@ -4962,7 +5071,8 @@ const TOOLS = [
     name: "egress_posture",
     description:
       "VERIFY BEFORE YOU HARVEST. Reports this instance's egress posture for YOUR tenant: " +
-      "the resolved embedding and chat endpoints, a locality VERDICT for each " +
+      "the resolved embedding and chat endpoints, EVERY webhook destination " +
+      "(webhook_destinations), a locality VERDICT for each " +
       "(network-local / 'tenant-declared (unverified attestation), not network-local' / " +
       "non-local), your declared trusted endpoints with their purposes, per-scope " +
       "local_only status, and any named posture defects. Endpoints are shown; KEYS NEVER " +
@@ -4971,10 +5081,70 @@ const TOOLS = [
       "key you already have. NOTE the deployment allowlist CONTENTS are operator " +
       "infrastructure and are NOT disclosed at agent role: you get only a boolean per " +
       "endpoint saying whether its verdict came from the allowlist (contents at user+). " +
+      "Webhook destinations follow the same split: HOST plus verdict plus " +
+      "blocked_by_local_only at agent role, the FULL destination URL (endpoint) only at " +
+      "user+ — a webhook path is frequently the credential. " +
       "SCOPE OF THE GUARANTEE: fail-closed enforcement covers every outbound HTTP call " +
-      "made by loopctl application code on the MODEL-PROVIDER path. Webhook delivery is " +
-      "not covered yet (US-41.5), and HTTP performed inside a dependency, plus this " +
-      "separate mcp-server codebase, are outside the static chokepoint check.",
+      "made by loopctl application code on every CONTENT-CARRYING path — model-provider " +
+      "calls, the ingestion fetch, and webhook delivery (US-41.5). HTTP performed inside " +
+      "a dependency, plus this separate mcp-server codebase, are outside the static " +
+      "chokepoint check; the remaining non-content outbound paths are triaged in " +
+      "docs/egress-guard.md.",
+    inputSchema: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "custody_claim",
+    description:
+      "The recorded EGRESS CUSTODY CLAIM for one article or memory row: the append-only " +
+      "sequence of per-operation postures (create, each embedding, each re-embed, each " +
+      "classification/merge) with the endpoint loopctl resolved for THAT operation and its " +
+      "locality verdict, plus the aggregate over them. Each claim rides the existing " +
+      "hash-chained audit log and its signed tree heads — every recorded entry carries the " +
+      "chain_position you can fetch an inclusion proof for at " +
+      "GET /api/v1/audit/sth/{tenant_id}/inclusion/{position} and check against the public " +
+      "STH with the tenant's published audit key. THREE STATES, and only one of them is an " +
+      "attestation: 'no_claim_recorded' (no operation sequence was ever assigned — the row " +
+      "predates recording or its scope is not marked local_only; this asserts NOTHING in " +
+      "either direction), 'claim_pending' (sequences assigned, batch append not yet " +
+      "flushed), and 'claim_recorded', itself 'complete', 'partial_history' or " +
+      "'incomplete'. An INCOMPLETE sequence (a gap, a lost tail, or a dropped append) is " +
+      "never reported as no-third-party-egress: an unrecorded operation may have called " +
+      "any endpoint. Completeness is measured against a PERSISTED per-row high-water mark, " +
+      "not against the rows that happen to survive, so truncating the sequence cannot " +
+      "restore a satisfied claim. 'partial_history' means operation 0 is not this row's " +
+      "creation — recording began after the row already existed (typically the scope was " +
+      "marked local_only later), so loopctl has no record of how it was produced. " +
+      "third_party_egress_on_covered_paths is `false` ONLY when every recorded endpoint " +
+      "was NETWORK-LOCAL; when the sequence leans on a TENANT-DECLARED endpoint (a public " +
+      "host the tenant merely attested is its own, which loopctl never verified) the value " +
+      "is the string 'tenant_declared_unverified', not false. " +
+      "SCOPE, precisely: the claim attests ONLY to the endpoints loopctl called for the " +
+      "recorded operations on this row, on the egress paths enumerated in the `coverage` " +
+      "field. It makes NO statement about what those endpoints did with the data " +
+      "afterwards, and none about a path listed as uncovered. READ tool, AGENT role.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        subject_type: {
+          type: "string",
+          enum: ["article", "memory"],
+          description: "The kind of row the claim is bound to.",
+        },
+        subject_id: { type: "string", description: "The row's UUID." },
+      },
+      required: ["subject_type", "subject_id"],
+    },
+  },
+  {
+    name: "custody_failures",
+    description:
+      "Custody posture entries whose audit-chain append was DROPPED after exhausting " +
+      "retries, plus (under `stale_pending`) entries that have been in flight longer than " +
+      "the stale window. A recording failure is surfaced here rather than silently absent, " +
+      "because a missing claim must never read as a satisfied one: every entry under " +
+      "`data` degrades its row's claim to 'incomplete', and a stranded `stale_pending` " +
+      "entry is one a flush stamped and then died on — it would otherwise read as an " +
+      "in-flight claim indefinitely. READ tool, AGENT role.",
     inputSchema: { type: "object", properties: {}, required: [] },
   },
   {
@@ -4985,10 +5155,13 @@ const TOOLS = [
       "everywhere; nothing changes until a scope opts in. Scope resolution is " +
       "MOST-RESTRICTIVE-WINS (project OR tenant) and a project can NEVER relax a tenant " +
       "marking. MANDATORY PRE-FLIGHT: the call is REFUSED with 409 would_block_endpoints, " +
-      "naming every endpoint that would become egress_blocked, unless you pass " +
+      "naming every endpoint that would become egress_blocked — including every WEBHOOK " +
+      "SUBSCRIPTION whose destination would be refused (kind: 'webhook', US-41.5) — " +
+      "unless you pass " +
       "acknowledge: true — because on a tenant still using vendor default endpoints this " +
       "instantly stops embedding, extraction, classification and merge, and only a " +
-      "human user-role key can undo it. Requires an ORCHESTRATOR key: tightening is safe " +
+      "human user-role key can undo it. Subscriptions are never silently disabled: they " +
+      "are either the reason for the refusal, or reported back to you on acknowledgement. Requires an ORCHESTRATOR key: tightening is safe " +
       "to automate. CLEARING is a different tool (clear_local_only) and is user-only.",
     inputSchema: {
       type: "object",
@@ -5846,6 +6019,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);
 
@@ -5975,6 +6157,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "egress_posture":
       return await egressPosture();
 
+    // US-41.7 — witnessed custody claim
+    case "custody_claim":
+      return await custodyClaim(args);
+
+    case "custody_failures":
+      return await custodyFailures();
+
     case "set_local_only":
       return await setLocalOnly(args);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopctl-mcp-server",
-  "version": "2.54.0",
+  "version": "2.56.0",
   "description": "MCP server for loopctl \u2014 structural trust for AI development loops",
   "type": "module",
   "main": "index.js",
@@ -30,7 +30,7 @@
   "license": "MIT",
   "exports": "./index.js",
   "engines": {
-    "node": ">=18"
+    "node": ">=20.6.0"
   },
   "files": [
     "index.js",