prism-mcp-server 3.0.1 → 3.1.0

package/dist/tools/agentRegistryHandlers.js

@@ -8,6 +8,55 @@ import { getStorage } from "../storage/index.js";
 import { PRISM_USER_ID } from "../config.js";
 import { getRoleIcon } from "./agentRegistryDefinitions.js";
 import { getSetting } from "../storage/configStorage.js";
+// ─── Helpers ─────────────────────────────────────────────────
+/**
+ * Escape markdown metacharacters in user-controlled strings.
+ *
+ * Fields like `current_task`, `agent_name`, and `status` are user-provided
+ * and may contain characters (* _ ` [ etc.) that would corrupt the markdown
+ * formatting of agent_list_team output. We escape the most common ones to
+ * keep the display predictable without being overly aggressive.
+ *
+ * This is a display-integrity fix, not a security fix — MCP response text
+ * is rendered in the LLM's context where injection risk is low, but broken
+ * formatting reduces readability and can misguide the model.
+ */
+function escapeMd(str) {
+    if (!str)
+        return "";
+    return str
+        .replace(/\\/g, "\\\\")
+        .replace(/\*/g, "\\*")
+        .replace(/_/g, "\\_")
+        .replace(/`/g, "\\`")
+        .replace(/\[/g, "\\[")
+        .replace(/\]/g, "\\]")
+        // HTML angle-bracket escaping: prevents raw tags (e.g. <script> in agent
+        // names) from bleeding into LLM context as markup.
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+/**
+ * Returns a human-readable "time ago" string for a heartbeat timestamp.
+ *
+ * Clamped to prevent negative or NaN outputs due to:
+ *   - Clock skew between agents (heartbeat appears in the future)
+ *   - Malformed ISO strings that produce NaN from Date.parse()
+ * Fallback returns "just now" to avoid exposing confusing negative values.
+ */
+function getTimeAgo(isoString) {
+    const parsed = new Date(isoString).getTime();
+    if (isNaN(parsed))
+        return "unknown time"; // malformed timestamp
+    const diffMs = Date.now() - parsed;
+    const mins = Math.max(0, Math.floor(diffMs / 60000)); // clamp at 0 (no "future")
+    if (mins < 1)
+        return "just now";
+    if (mins < 60)
+        return `${mins}m ago`;
+    const hours = Math.floor(mins / 60);
+    return `${hours}h ago`;
+}
 // ─── Type Guards ─────────────────────────────────────────────
 function isAgentRegisterArgs(args) {
     return typeof args.project === "string";
@@ -30,7 +79,10 @@ export async function agentRegisterHandler(args) {
     const effectiveRole = args.role || await getSetting("default_role", "global");
     const effectiveName = args.agent_name || await getSetting("agent_name", "") || null;
     const storage = await getStorage();
-    const result = await storage.registerAgent({
+    // Register the agent. We don't use the return value here — the storage
+    // layer handles upsert internally and there are no caller-visible fields
+    // (e.g. server-assigned IDs) that we need to surface in the response.
+    await storage.registerAgent({
         project: args.project,
         user_id: PRISM_USER_ID,
         role: effectiveRole,
@@ -43,10 +95,10 @@ export async function agentRegisterHandler(args) {
         content: [{
                 type: "text",
                 text: `${icon} **Agent Registered**\n\n` +
-                    `- **Project:** ${args.project}\n` +
-                    `- **Role:** ${effectiveRole}\n` +
-                    (effectiveName ? `- **Name:** ${effectiveName}\n` : "") +
-                    (args.current_task ? `- **Task:** ${args.current_task}\n` : "") +
+                    `- **Project:** ${escapeMd(args.project)}\n` +
+                    `- **Role:** ${escapeMd(effectiveRole)}\n` +
+                    (effectiveName ? `- **Name:** ${escapeMd(effectiveName)}\n` : "") +
+                    (args.current_task ? `- **Task:** ${escapeMd(args.current_task)}\n` : "") +
                     `\nOther agents will see you when they call \`agent_list_team\` or \`session_load_context\`.`,
             }],
     };
@@ -64,8 +116,8 @@ export async function agentHeartbeatHandler(args) {
     return {
         content: [{
                 type: "text",
-                text: `💓 Heartbeat updated for **${effectiveRole}** on \`${args.project}\`.` +
-                    (args.current_task ? ` Task: ${args.current_task}` : ""),
+                text: `💓 Heartbeat updated for **${escapeMd(effectiveRole)}** on \`${escapeMd(args.project)}\`.` +
+                    (args.current_task ? ` Task: ${escapeMd(args.current_task)}` : ""),
             }],
     };
 }
@@ -82,7 +134,7 @@ export async function agentListTeamHandler(args) {
         return {
             content: [{
                     type: "text",
-                    text: `No active agents on \`${args.project}\`. Use \`agent_register\` to join the team.`,
+                    text: `No active agents on \`${escapeMd(args.project)}\`. Use \`agent_register\` to join the team.`,
                 }],
         };
     }
@@ -91,29 +143,20 @@ export async function agentListTeamHandler(args) {
         const ago = agent.last_heartbeat
             ? getTimeAgo(agent.last_heartbeat)
             : "unknown";
-        return (`${icon} **${agent.role}**` +
-            (agent.agent_name ? ` (${agent.agent_name})` : "") +
-            ` — ${agent.status}` +
-            (agent.current_task ? ` | Task: ${agent.current_task}` : "") +
+        // escapeMd() applied to all user-controlled fields to prevent
+        // markdown metacharacters in task descriptions from corrupting output
+        return (`${icon} **${escapeMd(agent.role)}**` +
+            (agent.agent_name ? ` (${escapeMd(agent.agent_name)})` : "") +
+            ` — ${escapeMd(agent.status)}` +
+            (agent.current_task ? ` | Task: ${escapeMd(agent.current_task)}` : "") +
             ` | Last seen: ${ago}`);
     });
     return {
         content: [{
                 type: "text",
-                text: `## 🐝 Active Hivemind Team — \`${args.project}\`\n\n` +
+                text: `## 🐝 Active Hivemind Team — \`${escapeMd(args.project)}\`\n\n` +
                     lines.join("\n") +
                     `\n\n_${team.length} agent(s) active. Stale agents (>30min) auto-pruned._`,
             }],
     };
 }
-// ─── Helpers ─────────────────────────────────────────────────
-function getTimeAgo(isoString) {
-    const diff = Date.now() - new Date(isoString).getTime();
-    const mins = Math.floor(diff / 60000);
-    if (mins < 1)
-        return "just now";
-    if (mins < 60)
-        return `${mins}m ago`;
-    const hours = Math.floor(mins / 60);
-    return `${hours}h ago`;
-}

package/dist/tools/index.js

@@ -26,8 +26,8 @@ export { webSearchHandler, braveWebSearchCodeModeHandler, localSearchHandler, br
 // This file always exports them — server.ts decides whether to include them in the tool list.
 //
 // v0.4.0: Added SESSION_COMPACT_LEDGER_TOOL and SESSION_SEARCH_MEMORY_TOOL
-export { SESSION_SAVE_LEDGER_TOOL, SESSION_SAVE_HANDOFF_TOOL, SESSION_LOAD_CONTEXT_TOOL, KNOWLEDGE_SEARCH_TOOL, KNOWLEDGE_FORGET_TOOL, SESSION_COMPACT_LEDGER_TOOL, SESSION_SEARCH_MEMORY_TOOL, MEMORY_HISTORY_TOOL, MEMORY_CHECKOUT_TOOL, SESSION_SAVE_IMAGE_TOOL, SESSION_VIEW_IMAGE_TOOL, SESSION_HEALTH_CHECK_TOOL, SESSION_FORGET_MEMORY_TOOL } from "./sessionMemoryDefinitions.js";
-export { sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, knowledgeSearchHandler, knowledgeForgetHandler, sessionSearchMemoryHandler, backfillEmbeddingsHandler, memoryHistoryHandler, memoryCheckoutHandler, sessionSaveImageHandler, sessionViewImageHandler, sessionHealthCheckHandler, sessionForgetMemoryHandler } from "./sessionMemoryHandlers.js";
+export { SESSION_SAVE_LEDGER_TOOL, SESSION_SAVE_HANDOFF_TOOL, SESSION_LOAD_CONTEXT_TOOL, KNOWLEDGE_SEARCH_TOOL, KNOWLEDGE_FORGET_TOOL, SESSION_COMPACT_LEDGER_TOOL, SESSION_SEARCH_MEMORY_TOOL, MEMORY_HISTORY_TOOL, MEMORY_CHECKOUT_TOOL, SESSION_SAVE_IMAGE_TOOL, SESSION_VIEW_IMAGE_TOOL, SESSION_HEALTH_CHECK_TOOL, SESSION_FORGET_MEMORY_TOOL, KNOWLEDGE_SET_RETENTION_TOOL } from "./sessionMemoryDefinitions.js";
+export { sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, knowledgeSearchHandler, knowledgeForgetHandler, sessionSearchMemoryHandler, backfillEmbeddingsHandler, memoryHistoryHandler, memoryCheckoutHandler, sessionSaveImageHandler, sessionViewImageHandler, sessionHealthCheckHandler, sessionForgetMemoryHandler, knowledgeSetRetentionHandler } from "./sessionMemoryHandlers.js";
 // ── Compaction Handler (v0.4.0 — Enhancement #2) ──
 // The compaction handler is in a separate file because it's significantly
 // more complex than the other session memory handlers (chunked Gemini

package/dist/tools/sessionMemoryDefinitions.js

@@ -600,3 +600,38 @@ export function isSessionForgetMemoryArgs(args) {
         "memory_id" in args &&
         typeof args.memory_id === "string");
 }
+// ─── v3.1: Knowledge Set Retention (TTL) ─────────────────────
+export const KNOWLEDGE_SET_RETENTION_TOOL = {
+    name: "knowledge_set_retention",
+    description: "Set an automatic data retention policy (TTL) for a project's memory. " +
+        "Entries older than ttl_days will be soft-deleted (archived) automatically " +
+        "on every server startup and every 12 hours while running.\n\n" +
+        "**Use cases:**\n" +
+        "- Set `ttl_days: 90` to auto-expire sessions older than 3 months\n" +
+        "- Set `ttl_days: 0` to disable auto-expiry (default)\n\n" +
+        "**Note:** Rollup/compaction entries are never expired — only raw sessions.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            project: {
+                type: "string",
+                description: "Project to set retention policy for.",
+            },
+            ttl_days: {
+                type: "integer",
+                description: "Entries older than this many days are auto-expired. " +
+                    "Set to 0 to disable. Minimum: 7 days when enabled.",
+                minimum: 0,
+            },
+        },
+        required: ["project", "ttl_days"],
+    },
+};
+export function isKnowledgeSetRetentionArgs(args) {
+    return (typeof args === "object" &&
+        args !== null &&
+        "project" in args &&
+        typeof args.project === "string" &&
+        "ttl_days" in args &&
+        typeof args.ttl_days === "number");
+}

package/dist/tools/sessionMemoryHandlers.js

@@ -32,7 +32,12 @@ import { GOOGLE_API_KEY, PRISM_USER_ID, PRISM_AUTO_CAPTURE, PRISM_CAPTURE_PORTS
 import { captureLocalEnvironment } from "../utils/autoCapture.js";
 import { isSessionSaveLedgerArgs, isSessionSaveHandoffArgs, isSessionLoadContextArgs, isKnowledgeSearchArgs, isKnowledgeForgetArgs, isSessionSearchMemoryArgs, isBackfillEmbeddingsArgs, isMemoryHistoryArgs, isMemoryCheckoutArgs, isSessionHealthCheckArgs, // v2.2.0: health check type guard
 isSessionForgetMemoryArgs, // Phase 2: GDPR-compliant memory deletion type guard
+isKnowledgeSetRetentionArgs, // v3.1: TTL retention policy type guard
  } from "./sessionMemoryDefinitions.js";
+// v3.1: In-memory debounce lock for auto-compaction.
+// Prevents multiple concurrent Gemini compaction tasks for the same project
+// when many agents call session_save_ledger at the same time.
+const activeCompactions = new Set();
 import { notifyResourceUpdate } from "../server.js";
 // ─── Save Ledger Handler ──────────────────────────────────────
 /**
@@ -85,6 +90,36 @@ export async function sessionSaveLedgerHandler(args) {
             });
         }
     }
+    // ─── Fire-and-forget auto-compact ────────────────────────────
+    // If the user has opted into auto-compact (via dashboard Settings → Boot),
+    // run a health check after saving and compact if brain is degraded/unhealthy.
+    // Uses debounce Set to prevent concurrent Gemini calls for same project.
+    getSetting("compaction_auto", "false").then(async (autoCompact) => {
+        if (autoCompact !== "true")
+            return;
+        if (activeCompactions.has(project)) {
+            debugLog(`[auto-compact] Skipped for "${project}" — compaction already in progress`);
+            return;
+        }
+        activeCompactions.add(project);
+        try {
+            const { runHealthCheck } = await import("../utils/healthCheck.js");
+            const { compactLedgerHandler } = await import("./compactionHandler.js");
+            const healthStats = await storage.getHealthStats(PRISM_USER_ID);
+            const report = runHealthCheck(healthStats);
+            if (report.status === "degraded" || report.status === "unhealthy") {
+                debugLog(`[auto-compact] Brain "${project}" is ${report.status} — triggering compaction`);
+                await compactLedgerHandler({ project });
+                debugLog(`[auto-compact] Compaction complete for "${project}"`);
+            }
+        }
+        catch (err) {
+            console.error(`[auto-compact] Non-fatal error for "${project}": ${err}`);
+        }
+        finally {
+            activeCompactions.delete(project);
+        }
+    }).catch(() => { });
     return {
         content: [{
                 type: "text",
@@ -1467,3 +1502,54 @@ export async function sessionForgetMemoryHandler(args) {
         };
     }
 }
+// ─── v3.1: Knowledge Set Retention Handler ────────────────
+/**
+ * Set a TTL (data retention policy) for a project.
+ * Saves the policy to configStorage, then immediately runs one sweep
+ * to expire any entries that are already over the TTL.
+ */
+export async function knowledgeSetRetentionHandler(args) {
+    if (!isKnowledgeSetRetentionArgs(args)) {
+        throw new Error("Invalid arguments for knowledge_set_retention");
+    }
+    const { project, ttl_days } = args;
+    if (ttl_days < 0) {
+        return {
+            content: [{ type: "text", text: "Error: ttl_days must be 0 (disabled) or a positive integer." }],
+            isError: true,
+        };
+    }
+    if (ttl_days > 0 && ttl_days < 7) {
+        return {
+            content: [{ type: "text", text: "Error: Minimum TTL is 7 days to prevent accidental data loss." }],
+            isError: true,
+        };
+    }
+    const storage = await getStorage();
+    // Save policy to configStorage so server.ts sweep can read it
+    await storage.setSetting(`ttl:${project}`, String(ttl_days));
+    if (ttl_days === 0) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `✅ Data retention **disabled** for project \"${project}\".\n\nEntries will be kept indefinitely.`,
+                }],
+            isError: false,
+        };
+    }
+    // Run an immediate sweep for entries already past TTL
+    const result = await storage.expireByTTL(project, ttl_days, PRISM_USER_ID);
+    return {
+        content: [{
+                type: "text",
+                text: `⏱️ **Retention policy set** for project \"${project}\":\n\n` +
+                    `- Auto-expire entries older than: **${ttl_days} days**\n` +
+                    `- Sweep runs on: server startup + every 12 hours\n` +
+                    `- Rollup/compaction entries: **never expired**\n\n` +
+                    (result.expired > 0
+                        ? `🗑️ Immediately expired **${result.expired}** entries already past the ${ttl_days}-day threshold.`
+                        : `✅ No existing entries exceeded the ${ttl_days}-day threshold.`),
+            }],
+        isError: false,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "mcpName": "io.github.dcostenco/prism-mcp",
   "description": "The Mind Palace for AI Agents — local-first MCP server with persistent memory (SQLite/Supabase), visual dashboard, time travel, multi-agent sync, Morning Briefings, reality drift detection, code mode templates, semantic vector search, and Brave Search + Gemini analysis. Zero-config local mode.",
   "module": "index.ts",
@@ -87,6 +87,7 @@
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@supabase/supabase-js": "^2.99.3",
     "dotenv": "^16.5.0",
+    "fflate": "^0.8.2",
     "quickjs-emscripten": "^0.32.0"
   }
 }