loopctl-mcp-server 2.90.0 → 2.91.1

package/README.md

@@ -342,7 +342,7 @@ it is enforced server-side and a no-op for a non-superadmin key — see below.)
 | `memory_list` | List your own long-term memories, newest first, paginated with `meta.total_count/limit/offset` (the true scoped count, never silently capped by `limit`). Optional: `limit`, `offset`, `include_superseded`, `all_subjects` (superadmin only; ignored for non-superadmin keys). |
 | `memory_forget` | Delete one of your own long-term memories by id. A foreign-subject, foreign-tenant, or unknown id returns 404 (no existence leak). Required: `id`. |
 | `memory_promote` | Call at session end to compile this session's short-term (`session`-tier) memory into durable `long_term` memory — unlike `memory_remember` (a single explicit write), this compiles the whole session in one shot; fire it once at session end, not per turn. Returns 202 with `{session_id, status: "enqueued"}` — promotion runs asynchronously, so the resulting memory is recallable via `memory_recall` only after the worker drains. You can only promote your own sessions (scope resolved server-side from your key). Required: `session_id`. |
-| `recall_context` | ONE round-trip returning the re-ranked `global ∪ active-project` union of long-term MEMORY **and** KNOWLEDGE for `query` — what you previously assembled by calling `memory_recall` and `knowledge_search` separately. Pass `project_id` (from `resolve_project`) to merge global with that project on both sides; absent → global-only. The knowledge half is combined-search *summaries* (not full bodies — use `knowledge_context` for those). Response carries merged `results` (each tagged `source: memory\|knowledge`) plus the untouched per-source `memory`/`knowledge` envelopes; `meta.degraded?` flags a one-sided degrade (the other side is still returned — never a 500). Each per-source envelope's `meta.ann_iterative_scan` describes only THAT half's vector read, and the two are resolved independently, so they may differ. A blank query, or one over 500 chars, is a `422` up front. Required: `query`. Optional: `project_id`, `limit`. The top-level `meta.outcome` classifies the whole endpoint and the `memory` envelope carries its own; `meta.degraded_reason` names the strongest-remedy half when both degrade, and `meta.search_mode` names the lane that half actually served (`keyword_only`) or is `null` when it served nothing. Response also carries a SELECTION LEDGER: per item `rank`, `selection_reason` (`keyword`\|`semantic`\|`keyword+semantic`\|`keyword_fallback` for knowledge, `semantic`\|`ilike_fallback` for memory) and `tokens_estimate` (bytes/4, an estimate); in `meta`, `recall_id`, `candidates_considered`, `selected_count`, `tokens_selected`, `tokens_candidates`, `tokens_saved_vs_candidates`. The merged order is deterministic (score DESC, then source, then id), so an unchanged corpus renders a byte-identical `data` array — cache that, not the whole response, since `meta.recall_id` is new on every call. Keep `meta.recall_id` for `recall_referenced`. |
+| `recall_context` | ONE round-trip returning the re-ranked `global ∪ active-project` union of long-term MEMORY **and** KNOWLEDGE for `query` — what you previously assembled by calling `memory_recall` and `knowledge_search` separately. Pass `project_id` (from `resolve_project`) to merge global with that project on both sides; absent → global-only. The knowledge half is combined-search *summaries* (not full bodies — use `knowledge_context` for those). Response carries merged `results` (each tagged `source: memory\|knowledge`) plus the untouched per-source `memory`/`knowledge` envelopes; `meta.degraded?` flags a one-sided degrade (the other side is still returned — never a 500). Each per-source envelope's `meta.ann_iterative_scan` describes only THAT half's vector read, and the two are resolved independently, so they may differ. A blank query, or one over 500 chars, is a `422` up front. Required: `query`. Optional: `project_id`, `limit`. The top-level `meta.outcome` classifies the whole endpoint and the `memory` envelope carries its own; `meta.degraded_reason` names the strongest-remedy half when both degrade, and `meta.search_mode` names the lane that half actually served (`keyword_only`) or is `null` when it served nothing. Response also carries a SELECTION LEDGER: per item `rank`, `selection_reason` (`keyword`\|`semantic`\|`keyword+semantic`\|`keyword_fallback` for knowledge, `semantic`\|`ilike_fallback` for memory) and `tokens_estimate` (bytes/4, an estimate); in `meta`, `recall_id`, `candidates_considered`, `selected_count`, `tokens_selected`, `tokens_candidates`, `tokens_saved_vs_candidates`. The merged order is deterministic (score DESC, then source, then id), so an unchanged corpus renders a byte-identical `data` array — cache that, not the whole response, since `meta.recall_id` is new on every call. Keep `meta.recall_id` for `recall_referenced`. DIVERSITY (#792): the knowledge half is over-fetched and then reduced, so two near-copies cannot spend two of your slots — an article already shown to this `session_id` is skipped, exact content-hash duplicates collapse, a candidate too similar to one already SELECTED is dropped, and every freed slot is REFILLED rather than left empty. `meta.diversity` reports each count; `meta.candidates_considered.knowledge` is the over-fetched pool and `meta.knowledge_count` is what survived. Selection changes WHAT you get, never the order. Optional `session_id`: an opaque per-session token (max 200 bytes) — pass the same value on every recall in a session to get containment-in-history; it is not an isolation boundary and a miss just re-surfaces an article. |
 | `recall_referenced` | Record which of the articles a recall SURFACED you actually USED — the third funnel stage (surfaced -> opened -> referenced), and the only one nothing else records. Pass the `meta.recall_id` from a `recall_context` response plus the ids you referenced -- the `article.id` of the `source: knowledge` items, since a `memory` item's id is not an article and is not referenceable; call it once, after writing your answer. Only ids THAT recall surfaced, in your own tenant, are accepted — anything else is `422` `not_surfaced` and NOTHING is written. Your key is stamped server-side, at most 50 ids per call, and repeats cannot inflate the metric (it counts distinct `(recall, article)` pairs). These rows are deliberately not reads: they never feed the heat index or any ranking. Required: `recall_id`, `article_ids`. Optional: `project_id`. |
 | `memory_graduate` | Graduate ONE of your long-term memories into a durable Knowledge Wiki article — the explicit, on-demand version of the hourly graduation sweep. Use when a private memory has proven valuable enough to become durable knowledge. **Visibility**: the graduated article stays **owner-visible** (`metadata.visibility: "owner"`, keyed to your subject) — discoverable by YOU, NOT peer-readable (graduation does not share a memory to teammates; `re_scope: "global"` widens only the project scope, not visibility). Scope is key-derived (you can only graduate your OWN memory; a foreign/unknown `memory_id` → 404). DEDUPED by the novelty gate: `data.verdict` is `created` (novel → published) or `gated_to_draft` (near-dup → review draft) with a new article (**201**), or `duplicate`/`deduplicated` (already represented → canonical article, nothing created) (**200**). By default the article inherits the memory's project scope; pass `re_scope: "global"` to promote a PROJECT memory to a tenant-wide article — only valid on its FIRST graduation, and only if the hourly sweep hasn't graduated it project-scoped first (`409` `already_graduated` otherwise). An already-graduated global memory re-graduates idempotently (**200**). `503` `gate_unavailable` if the embedding backend is down — retry later. Required: `memory_id`. Optional: `re_scope` (`inherit`\|`global`). |
 

package/index.js

@@ -43,6 +43,7 @@ import {
   GENERATED_TOOL_PREFIX,
 } from "./lib/generated-tools.js";
 import { createHandoff } from "./lib/handoff.js";
+import { readPayloadFile } from "./lib/payload-path.js";
 
 // Single source of truth for the server version: the package.json this file
 // ships with (npm always includes package.json in the published tarball).
@@ -967,13 +968,7 @@ async function importStories({ project_id, payload, payload_path, merge }) {
 
 // Reads JSON payload from either an inline object or an absolute file path.
 // Returns the object on success, or an { error, body } shape on failure.
-//
-// Security: `payload_path` is read with the MCP process's filesystem
-// privileges. Because agents can set this argument via prompt injection,
-// we validate aggressively:
-//   * require absolute path
-//   * reject /proc, /dev, /sys (pseudo-filesystems that could DoS or leak)
-//   * stat first and cap at 5 MiB (server also enforces a body size limit)
+// The file path is validated in lib/payload-path.js (see its security notes).
 async function resolvePayload(inline, payloadPath) {
   if (inline && typeof inline === "object") return inline;
   if (!payloadPath) {
@@ -983,53 +978,7 @@ async function resolvePayload(inline, payloadPath) {
       body: "Must provide either `payload` (object) or `payload_path` (absolute JSON file path).",
     };
   }
-
-  const nodePath = await import("node:path");
-  if (!nodePath.isAbsolute(payloadPath)) {
-    return {
-      error: true,
-      status: 0,
-      body: `payload_path must be absolute (got '${payloadPath}').`,
-    };
-  }
-
-  const blockedPrefixes = ["/proc/", "/dev/", "/sys/", "/proc", "/dev", "/sys"];
-  if (blockedPrefixes.some((p) => payloadPath === p.replace(/\/$/, "") || payloadPath.startsWith(p))) {
-    return {
-      error: true,
-      status: 0,
-      body: `payload_path refused: '${payloadPath}' targets a pseudo-filesystem path.`,
-    };
-  }
-
-  const MAX_PAYLOAD_BYTES = 5 * 1024 * 1024;
-  const fs = await import("node:fs/promises");
-
-  try {
-    const stat = await fs.stat(payloadPath);
-    if (!stat.isFile()) {
-      return {
-        error: true,
-        status: 0,
-        body: `payload_path '${payloadPath}' is not a regular file.`,
-      };
-    }
-    if (stat.size > MAX_PAYLOAD_BYTES) {
-      return {
-        error: true,
-        status: 0,
-        body: `payload_path '${payloadPath}' is ${stat.size} bytes, exceeds max ${MAX_PAYLOAD_BYTES}.`,
-      };
-    }
-    const raw = await fs.readFile(payloadPath, "utf8");
-    return JSON.parse(raw);
-  } catch (err) {
-    return {
-      error: true,
-      status: 0,
-      body: `Could not read payload_path '${payloadPath}': ${err.message}`,
-    };
-  }
+  return readPayloadFile(payloadPath);
 }
 
 // --- Story Tools ---
@@ -1928,7 +1877,7 @@ async function memoryRecall({ query, limit, include_superseded }) {
   return withRemediationNotice(result);
 }
 
-async function recallContext({ query, project_id, limit }) {
+async function recallContext({ query, project_id, limit, session_id }) {
   // Merged recall (#411 Gap 2): ONE round-trip returning the re-ranked
   // global ∪ active-project union of long-term MEMORY and KNOWLEDGE. Scope
   // (tenant_id/subject_id) is derived server-side from the agent key; project_id is
@@ -1936,6 +1885,10 @@ async function recallContext({ query, project_id, limit }) {
   const payload = { query };
   if (project_id) payload.project_id = project_id;
   if (limit != null) payload.limit = limit;
+  // #792: the containment-in-history key. Opaque and client-chosen; the server keys its
+  // shown-set on (tenant, subject, session, article) — both server-derived halves of the
+  // memory scope ahead of the token — so it is never an isolation boundary.
+  if (session_id) payload.session_id = session_id;
 
   const result = await apiCall(
     "POST",
@@ -3923,7 +3876,7 @@ const TOOLS = [
         payload_path: {
           type: "string",
           description:
-            "Absolute path to a JSON file with the import payload. Avoids inline size limits for large epics. Ignored if `payload` is also passed.",
+            "Absolute path to a .json file holding the import payload (an object with an `epics` array). Avoids inline size limits for large epics. Ignored if `payload` is also passed.",
         },
         merge: {
           type: "boolean",
@@ -5643,7 +5596,13 @@ const TOOLS = [
       "the whole response, since `meta.recall_id` is new on every call. KEEP " +
       "`meta.recall_id`: after you " +
       "answer, pass it to recall_referenced with the ids you actually used — that is the " +
-      "third funnel stage and nothing else records it.",
+      "third funnel stage and nothing else records it. DIVERSITY (#792): the knowledge " +
+      "half is over-fetched and then reduced, so two near-copies cannot spend two of your " +
+      "slots — an article already shown to this `session_id` is skipped, exact " +
+      "content-hash duplicates collapse, a candidate too similar to one already selected " +
+      "is dropped, and every freed slot is REFILLED rather than left empty. " +
+      "`meta.diversity` reports each count. Selection changes WHAT you get, never the " +
+      "order, so the deterministic `data` array above still holds.",
     inputSchema: {
       type: "object",
       properties: {
@@ -5663,6 +5622,19 @@ const TOOLS = [
           description:
             "Optional: overall merged page size, clamped to [1, 50] (default 10).",
         },
+        session_id: {
+          type: "string",
+          description:
+            "Optional: an opaque token for THIS session (max 200 bytes). Pass the same " +
+            "value on every recall in a session and the server skips articles it already " +
+            "showed you, refilling the freed slot with the next distinct candidate — " +
+            "which a client-side filter cannot do. It can never starve you: once a " +
+            "session has exhausted the matching pool the highest-ranked repeats come " +
+            "back, so an empty knowledge half always means the corpus, never the " +
+            "suppression. Not an isolation boundary (history is keyed on tenant + " +
+            "subject + session + article) and best-effort: a miss just re-surfaces an " +
+            "article. Omit it to disable containment for that call.",
+        },
       },
       required: ["query"],
     },

package/lib/payload-path.js

@@ -0,0 +1,96 @@
+// Reads an import_stories payload from an absolute file path.
+//
+// Security: `payload_path` is read with the MCP process's filesystem privileges and an
+// agent can set it via prompt injection, so no file CONTENT is ever returned, and a file
+// that is not an import payload is never uploaded. The refusals still say which check
+// failed (missing, not a file, too large, not JSON, wrong shape) for a .json path; that
+// is metadata an agent needs to fix its own call, not content:
+//   * require an absolute path ending in .json, checked on the path AND on its realpath,
+//     so a symlink named x.json cannot point at /etc/passwd or /proc
+//   * reject /proc, /dev, /sys (pseudo-filesystems that could DoS or leak)
+//   * stat first and cap at 5 MiB (server also enforces a body size limit)
+//   * never echo a JSON.parse or fs error message: V8's SyntaxError quotes the file's
+//     content ("root:x:0:0"... is not valid JSON), so only err.code is reported
+//   * require the Epic 12 import shape (an object with an `epics` array) before returning,
+//     so a valid JSON file that is not a payload (a credentials file) is never POSTed
+//
+// Returns the parsed payload on success, or an { error, status, body } shape on failure.
+
+import nodePath from "node:path";
+import defaultFs from "node:fs/promises";
+
+export const MAX_PAYLOAD_BYTES = 5 * 1024 * 1024;
+
+const BLOCKED_ROOTS = ["/proc", "/dev", "/sys"];
+
+function refuse(body) {
+  return { error: true, status: 0, body };
+}
+
+function isBlocked(p) {
+  return BLOCKED_ROOTS.some((root) => p === root || p.startsWith(root + "/"));
+}
+
+function hasJsonExtension(p) {
+  return nodePath.extname(p).toLowerCase() === ".json";
+}
+
+export async function readPayloadFile(payloadPath, { fs = defaultFs } = {}) {
+  if (typeof payloadPath !== "string" || !nodePath.isAbsolute(payloadPath)) {
+    return refuse(`payload_path must be absolute (got '${payloadPath}').`);
+  }
+
+  if (isBlocked(nodePath.resolve(payloadPath))) {
+    return refuse(`payload_path refused: '${payloadPath}' targets a pseudo-filesystem path.`);
+  }
+
+  if (!hasJsonExtension(payloadPath)) {
+    return refuse(`payload_path refused: '${payloadPath}' must be a .json file.`);
+  }
+
+  let realPath;
+  try {
+    realPath = await fs.realpath(payloadPath);
+  } catch (err) {
+    return refuse(`Could not read payload_path '${payloadPath}' (${err.code || "error"}).`);
+  }
+
+  if (isBlocked(realPath)) {
+    return refuse(`payload_path refused: '${payloadPath}' targets a pseudo-filesystem path.`);
+  }
+
+  if (!hasJsonExtension(realPath)) {
+    return refuse(`payload_path refused: '${payloadPath}' must be a .json file.`);
+  }
+
+  let raw;
+  try {
+    const stat = await fs.stat(realPath);
+    if (!stat.isFile()) {
+      return refuse(`payload_path '${payloadPath}' is not a regular file.`);
+    }
+    if (stat.size > MAX_PAYLOAD_BYTES) {
+      return refuse(
+        `payload_path '${payloadPath}' exceeds max ${MAX_PAYLOAD_BYTES} bytes.`,
+      );
+    }
+    raw = await fs.readFile(realPath, "utf8");
+  } catch (err) {
+    return refuse(`Could not read payload_path '${payloadPath}' (${err.code || "error"}).`);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return refuse(`payload_path '${payloadPath}' is not valid JSON.`);
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || !Array.isArray(parsed.epics)) {
+    return refuse(
+      `payload_path '${payloadPath}' is not an import payload (expected an object with an "epics" array).`,
+    );
+  }
+
+  return parsed;
+}

package/package.json

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