@plur-ai/mcp 0.9.9 → 0.9.11

package/dist/index.js

@@ -4,8 +4,8 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from "fs";
 import { join } from "path";
 import { fileURLToPath } from "url";
-import { homedir } from "os";
-var VERSION = "0.9.9";
+import { homedir, platform } from "os";
+var VERSION = "0.9.11";
 var HELP = `plur-mcp v${VERSION} \u2014 persistent memory for AI agents
 
 Usage:
@@ -53,7 +53,9 @@ function extractManifestVersion(skillMdPath) {
     return null;
   }
 }
-var CLI = "npx @plur-ai/cli";
+var _shimName = platform() === "win32" ? "plur-hook.cmd" : "plur-hook";
+var _shimCandidate = join(homedir(), ".plur", "bin", _shimName);
+var CLI = existsSync(_shimCandidate) ? _shimCandidate : "npx @plur-ai/cli";
 var PLUR_HOOKS = {
   // --- Session lifecycle ---
   UserPromptSubmit: [{
@@ -277,7 +279,7 @@ if (arg === "init") {
   process.exit(0);
 }
 if (arg === "serve" || arg === void 0) {
-  const { runStdio } = await import("./server-X5ZMO46X.js");
+  const { runStdio } = await import("./server-FHZHOMM5.js");
   runStdio().catch((err) => {
     console.error("Failed to start PLUR MCP server:", err);
     process.exit(1);

package/dist/{server-X5ZMO46X.js → server-FHZHOMM5.js}

@@ -14,10 +14,10 @@ import {
 import { Plur as Plur2, checkForUpdate } from "@plur-ai/core";
 
 // src/tools.ts
-import { extractMetaEngrams, validateMetaEngram, confidenceBand, generateProfile, getProfileForInjection, selectModelForOperation } from "@plur-ai/core";
+import { extractMetaEngrams, validateMetaEngram, confidenceBand, generateProfile, getProfileForInjection, selectModelForOperation, getCachedUpdateCheck, minorVersionsBehind, scanForTensions, CapabilityCanary } from "@plur-ai/core";
 
 // src/version.ts
-var VERSION = "0.9.9";
+var VERSION = "0.9.11";
 
 // src/tools.ts
 function makeHttpLlm(baseUrl, apiKey, model = "gpt-4o-mini") {
@@ -86,6 +86,17 @@ function sanitizeStatement(raw) {
   }
   return raw.slice(0, cut).trimEnd();
 }
+var mcpCanary = new CapabilityCanary({ threshold: 10 });
+mcpCanary.expect({
+  id: "session_start_hook",
+  description: "Automatic memory injection via hooks",
+  fix: "Run: npx @plur-ai/mcp init"
+});
+mcpCanary.expect({
+  id: "learn_activity",
+  description: "Learning from corrections",
+  fix: "Call plur_learn when corrected. If using hooks, verify they are installed."
+});
 function getToolDefinitions() {
   return [
     {
@@ -129,23 +140,29 @@ function getToolDefinitions() {
         const statement = sanitizeStatement(args.statement);
         try {
           const engram = await plur.learnRouted(statement, context);
+          const isOutbox = !!engram.structured_data?._outbox;
+          mcpCanary.signal("learn_activity");
           return {
             id: engram.id,
             statement: engram.statement,
             scope: engram.scope,
             type: engram.type,
             pinned: engram.pinned === true,
-            decision: "ADD"
+            decision: "ADD",
+            ...isOutbox ? { outbox: true, warning: "Remote write failed; engram queued locally for retry on next session start or plur_sync." } : {}
           };
         } catch (err) {
           const engram = plur.learn(statement, context);
+          const isOutbox = !!engram.structured_data?._outbox;
+          mcpCanary.signal("learn_activity");
           return {
             id: engram.id,
             statement: engram.statement,
             scope: engram.scope,
             type: engram.type,
             decision: "ADD",
-            warning: `Remote write failed (${err.message}); fell back to local. The id above is the local placeholder \u2014 the canonical engram is NOT on the server.`
+            ...isOutbox ? { outbox: true } : {},
+            warning: `Remote write failed (${err.message}); engram queued for retry.`
           };
         }
       }
@@ -412,10 +429,13 @@ function getToolDefinitions() {
       handler: async (args, plur) => {
         if (args.id) {
           const engram = plur.getById(args.id);
-          if (!engram) throw new Error(`Engram not found: ${args.id}`);
-          if (engram.status === "retired") return { success: false, error: `Already retired: ${args.id}` };
+          if (engram) {
+            if (engram.status === "retired") return { success: false, error: `Already retired: ${args.id}` };
+            await plur.forget(args.id);
+            return { success: true, retired: { id: engram.id, statement: engram.statement } };
+          }
           await plur.forget(args.id);
-          return { success: true, retired: { id: engram.id, statement: engram.statement } };
+          return { success: true, retired: { id: args.id } };
         }
         if (args.search) {
           const matches = plur.recall(args.search, { limit: 100 });
@@ -648,7 +668,21 @@ function getToolDefinitions() {
       },
       handler: async (args, plur) => {
         const result = plur.sync(args.remote);
-        return result;
+        let outbox_result;
+        try {
+          outbox_result = await plur.flushOutbox();
+        } catch {
+        }
+        return {
+          ...result,
+          ...outbox_result && (outbox_result.flushed > 0 || outbox_result.failed > 0) ? {
+            outbox: {
+              flushed: outbox_result.flushed,
+              pending: outbox_result.failed,
+              warnings: outbox_result.expired_warnings
+            }
+          } : {}
+        };
       }
     },
     {
@@ -821,6 +855,7 @@ function getToolDefinitions() {
       },
       handler: async (_args, plur) => {
         const status = plur.status();
+        const versionCheck = getCachedUpdateCheck("@plur-ai/mcp");
         return {
           version: VERSION,
           engram_count: status.engram_count,
@@ -829,7 +864,17 @@ function getToolDefinitions() {
           storage_root: status.storage_root,
           locked_count: status.locked_count,
           tension_count: status.tension_count,
-          versioned_engram_count: status.versioned_engram_count ?? 0
+          versioned_engram_count: status.versioned_engram_count ?? 0,
+          outbox_count: status.outbox_count ?? 0,
+          // Version check (issue #151)
+          ...versionCheck?.updateAvailable && versionCheck.latest ? {
+            update_available: {
+              current: versionCheck.current,
+              latest: versionCheck.latest,
+              behind: minorVersionsBehind(versionCheck.current, versionCheck.latest)
+            }
+          } : {},
+          capabilities: mcpCanary.status()
         };
       }
     },
@@ -898,6 +943,13 @@ function getToolDefinitions() {
             "  \u2022 Or opt out: set PLUR_DISABLE_EMBEDDINGS=1, or write `embeddings: { enabled: false }` to ~/.plur/config.yaml \u2014 hybrid search will run BM25-only"
           );
         }
+        const canaryStatuses = mcpCanary.status();
+        for (const cs of canaryStatuses) {
+          if (!cs.healthy) {
+            checks.push({ check: `capability: ${cs.capability}`, ok: false, detail: cs.warning });
+            if (cs.warning) remediation.push(cs.warning);
+          }
+        }
         return {
           ok: checks.every((c) => c.ok),
           checks,
@@ -905,6 +957,7 @@ function getToolDefinitions() {
             before_probe: before,
             after_probe: after
           },
+          capabilities: canaryStatuses,
           remediation: remediation.length > 0 ? remediation : ["All checks passed \u2014 PLUR is healthy."]
         };
       }
@@ -922,10 +975,17 @@ function getToolDefinitions() {
         required: ["task"]
       },
       handler: async (args, plur) => {
+        mcpCanary.tick();
+        mcpCanary.signal("session_start_hook");
         const crypto = await import("crypto");
         const session_id = crypto.randomUUID();
         const task = args.task;
         const tags = args.tags;
+        let outbox_result;
+        try {
+          outbox_result = await plur.flushOutbox();
+        } catch {
+        }
         const status = plur.status();
         const store_stats = {
           engram_count: status.engram_count,
@@ -967,6 +1027,19 @@ function getToolDefinitions() {
 You have ${store_stats.engram_count} engrams but none matched this task. Call plur_learn to capture new learnings from this session.`;
         }
         const isFreshInstall = store_stats.engram_count === 0 && store_stats.episode_count === 0;
+        const versionCheck = getCachedUpdateCheck("@plur-ai/mcp");
+        let version_warning;
+        if (versionCheck?.updateAvailable && versionCheck.latest) {
+          const behind = minorVersionsBehind(versionCheck.current, versionCheck.latest);
+          if (behind > 2) {
+            version_warning = `CRITICAL: Running PLUR v${versionCheck.current} \u2014 latest is v${versionCheck.latest} (${behind} minor versions behind). Known bugs may be present. Update immediately: npx @plur-ai/mcp@latest`;
+            guide = `\u26A0\uFE0F ${version_warning}
+
+${guide}`;
+          } else {
+            version_warning = `Update available: PLUR v${versionCheck.current} \u2192 v${versionCheck.latest}. Run: npx @plur-ai/mcp@latest`;
+          }
+        }
         return {
           session_id,
           engrams: engrams ?? [],
@@ -975,7 +1048,17 @@ You have ${store_stats.engram_count} engrams but none matched this task. Call pl
           // Ask LLM to check back — MCP can't push, but we can request a follow-up
           follow_up: store_stats.engram_count === 0 ? "This is a fresh store with 0 engrams. After your first exchange with the user, review what you learned and call plur_learn for any corrections, preferences, or patterns. Build the memory from this session." : void 0,
           // On fresh install, suggest hook setup for reliable injection
-          setup_hint: isFreshInstall ? "IMPORTANT: For reliable memory injection, ask the user to run: npx @plur-ai/cli init \u2014 this installs Claude Code hooks that automatically inject engrams at conversation start and after context compaction. Without hooks, memory injection depends on you remembering to call plur_session_start." : void 0
+          setup_hint: isFreshInstall ? "IMPORTANT: For reliable memory injection, ask the user to run: npx @plur-ai/cli init \u2014 this installs Claude Code hooks that automatically inject engrams at conversation start and after context compaction. Without hooks, memory injection depends on you remembering to call plur_session_start." : void 0,
+          // Outbox flush results (issue #26)
+          ...outbox_result && (outbox_result.flushed > 0 || outbox_result.failed > 0) ? {
+            outbox: {
+              flushed: outbox_result.flushed,
+              pending: outbox_result.failed,
+              warnings: outbox_result.expired_warnings
+            }
+          } : {},
+          // Version staleness warning (issue #151)
+          ...version_warning ? { version_warning, version: VERSION } : {}
         };
       }
     },
@@ -999,14 +1082,21 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
           engram_suggestions: {
             type: "array",
             items: {
-              type: "object",
-              properties: {
-                statement: { type: "string", description: "A concise, reusable assertion. Write it as advice to your future self." },
-                type: { type: "string", enum: ["behavioral", "terminological", "procedural", "architectural"] }
-              },
-              required: ["statement"]
+              // Prefer {statement, type} objects. Bare strings are tolerated
+              // and treated as {statement: <string>} (issue #231).
+              anyOf: [
+                { type: "string" },
+                {
+                  type: "object",
+                  properties: {
+                    statement: { type: "string", description: "A concise, reusable assertion. Write it as advice to your future self." },
+                    type: { type: "string", enum: ["behavioral", "terminological", "procedural", "architectural"] }
+                  },
+                  required: ["statement"]
+                }
+              ]
             },
-            description: "Learnings from this session. Review the conversation for corrections, preferences, patterns, and technical facts before calling."
+            description: 'Learnings from this session. Preferred shape is {statement: "...", type?: "..."}; bare strings are also accepted and treated as the statement. Review the conversation for corrections, preferences, patterns, and technical facts before calling.'
           }
         },
         required: ["summary", "engram_suggestions"]
@@ -1016,9 +1106,23 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
         const session_id = args.session_id;
         const suggestions = args.engram_suggestions;
         let engrams_created = 0;
-        if (suggestions?.length) {
-          for (const s of suggestions) {
-            plur.learn(s.statement, { type: s.type });
+        if (Array.isArray(suggestions) && suggestions.length) {
+          for (let i = 0; i < suggestions.length; i++) {
+            const s = suggestions[i];
+            let statement;
+            let type;
+            if (typeof s === "string") {
+              statement = s;
+            } else if (s && typeof s === "object") {
+              statement = s.statement;
+              type = s.type;
+            }
+            if (typeof statement !== "string" || statement.length === 0) {
+              throw new Error(
+                `engram_suggestions[${i}] must be a string or {statement: string, type?: string}, got ${typeof s}`
+              );
+            }
+            plur.learn(statement, { type });
             engrams_created++;
           }
         }
@@ -1077,8 +1181,13 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
       annotations: { title: "List stores", readOnlyHint: true, idempotentHint: true },
       inputSchema: { type: "object", properties: {} },
       handler: async (_args, plur) => {
-        const stores = plur.listStores();
-        return { stores, count: stores.length };
+        const stores = await plur.listStoresAsync();
+        const outboxCount = plur.outboxCount();
+        return {
+          stores,
+          count: stores.length,
+          ...outboxCount > 0 ? { outbox_pending: outboxCount } : {}
+        };
       }
     },
     {
@@ -1123,13 +1232,19 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
     },
     {
       name: "plur_tensions",
-      description: "List engram pairs that have conflicting knowledge \u2014 shows tensions in your memory that may need resolution",
+      description: "List or scan for engram pairs that have conflicting knowledge. Without scan mode, shows previously detected conflicts. With scan:true, runs an active LLM-powered contradiction scan and returns only high-confidence tensions.",
       annotations: { title: "Tensions", readOnlyHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {
           scope: { type: "string", description: "Filter by scope" },
-          domain: { type: "string", description: "Filter by domain prefix" }
+          domain: { type: "string", description: "Filter by domain prefix" },
+          scan: { type: "boolean", description: "Run an active contradiction scan using an LLM judge. Requires OPENAI_API_KEY or OPENROUTER_API_KEY env var, or explicit llm_base_url + llm_api_key args." },
+          llm_base_url: { type: "string", description: "OpenAI-compatible API base URL for scan mode (e.g. https://api.openai.com/v1)" },
+          llm_api_key: { type: "string", description: "API key for the LLM (scan mode)" },
+          llm_model: { type: "string", description: "Model name for scan mode (default: gpt-4o-mini)" },
+          min_confidence: { type: "number", description: "Minimum confidence threshold for scan mode (0\u20131, default: 0.7)" },
+          max_pairs: { type: "number", description: "Maximum candidate pairs to evaluate in scan mode (default: 50)" }
         }
       },
       handler: async (args, plur) => {
@@ -1137,6 +1252,30 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
           scope: args.scope,
           domain: args.domain
         });
+        if (args.scan) {
+          const llm = args.llm_base_url && args.llm_api_key ? makeHttpLlm(args.llm_base_url, args.llm_api_key, args.llm_model) : getLlmFunction();
+          if (!llm) {
+            return {
+              error: "scan mode requires an LLM. Set OPENAI_API_KEY or OPENROUTER_API_KEY, or pass llm_base_url + llm_api_key.",
+              tensions: [],
+              count: 0
+            };
+          }
+          const result = await scanForTensions(engrams, llm, {
+            min_confidence: args.min_confidence,
+            max_pairs: args.max_pairs
+          });
+          return {
+            pairs_checked: result.pairs_checked,
+            count: result.new_tensions,
+            tensions: result.tensions.map((t) => ({
+              engram_a: { id: t.id_a, statement: t.statement_a },
+              engram_b: { id: t.id_b, statement: t.statement_b },
+              confidence: t.confidence,
+              reason: t.reason
+            }))
+          };
+        }
         const tensions = [];
         const seen = /* @__PURE__ */ new Set();
         for (const engram of engrams) {
@@ -1150,11 +1289,13 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
             tensions.push({
               engram_a: { id: engram.id, statement: engram.statement, type: engram.type },
               engram_b: { id: other.id, statement: other.statement, type: other.type },
-              detected_at: engram.activation.last_accessed
+              detected_at: engram.activation.last_accessed,
+              purge_hint: "These conflicts are from the legacy detection system. Run plur_tensions_purge to clear them, then use scan:true for active contradiction detection."
             });
           }
         }
-        return { tensions, count: tensions.length };
+        const purge_hint = tensions.length > 0 ? "These are legacy conflict relations. Run plur_tensions_purge to clear them." : void 0;
+        return { tensions, count: tensions.length, ...purge_hint ? { purge_hint } : {} };
       }
     },
     {
@@ -1364,7 +1505,7 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
     },
     {
       name: "plur_batch_decay",
-      description: "Apply ACT-R decay to all engrams. Run weekly. Returns status transitions only.",
+      description: "Apply ACT-R decay to all local engrams. Run weekly. Only decays engrams in the local YAML store \u2014 remote-store engrams are not decayed client-side. Returns status transitions only.",
       annotations: { title: "Batch decay", destructiveHint: false, idempotentHint: false },
       inputSchema: {
         type: "object",
@@ -1521,6 +1662,31 @@ Use \`scope\` to namespace engrams per project:
 
 Override with \`PLUR_PATH\` environment variable.
 `;
+function jsonSchemaPropToZod(prop) {
+  if (!prop || typeof prop !== "object") return z.unknown();
+  const variants = prop.anyOf ?? prop.oneOf;
+  if (Array.isArray(variants) && variants.length > 0) {
+    const zodVariants = variants.map(jsonSchemaPropToZod);
+    if (zodVariants.length === 1) return zodVariants[0];
+    return z.union(zodVariants);
+  }
+  if (prop.type === "string") return prop.enum ? z.enum(prop.enum) : z.string();
+  if (prop.type === "number" || prop.type === "integer") return z.number();
+  if (prop.type === "boolean") return z.boolean();
+  if (prop.type === "array") {
+    const itemSchema = prop.items ? jsonSchemaPropToZod(prop.items) : z.unknown();
+    return z.array(itemSchema);
+  }
+  if (prop.type === "object" && prop.properties) {
+    const shape = {};
+    for (const [k, p] of Object.entries(prop.properties)) {
+      const field = jsonSchemaPropToZod(p);
+      shape[k] = prop.required?.includes(k) ? field : field.optional();
+    }
+    return z.object(shape).passthrough();
+  }
+  return z.unknown();
+}
 async function createServer(plur) {
   const instance = plur ?? new Plur2();
   const tools = getToolDefinitions();
@@ -1553,7 +1719,7 @@ async function createServer(plur) {
     const tool = tools.find((t) => t.name === request.params.name);
     if (!tool) {
       return {
-        content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],
+        content: [{ type: "text", text: JSON.stringify({ error: `Unknown tool: ${request.params.name}`, success: false }) }],
         isError: true
       };
     }
@@ -1563,18 +1729,14 @@ async function createServer(plur) {
       if (schema?.properties) {
         const shape = {};
         for (const [key, prop] of Object.entries(schema.properties)) {
-          let field;
-          if (prop.type === "string") field = prop.enum ? z.enum(prop.enum) : z.string();
-          else if (prop.type === "number") field = z.number();
-          else if (prop.type === "boolean") field = z.boolean();
-          else if (prop.type === "array") field = z.array(z.unknown());
-          else field = z.unknown();
+          const field = jsonSchemaPropToZod(prop);
           shape[key] = schema.required?.includes(key) ? field : field.optional();
         }
         const parsed = z.object(shape).passthrough().safeParse(args);
         if (!parsed.success) {
+          const details = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join(", ");
           return {
-            content: [{ type: "text", text: `Invalid arguments: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join(", ")}` }],
+            content: [{ type: "text", text: JSON.stringify({ error: `Invalid arguments: ${details}`, success: false }) }],
             isError: true
           };
         }
@@ -1585,7 +1747,7 @@ async function createServer(plur) {
       const message = err?.message ?? String(err);
       server.sendLoggingMessage({ level: "error", data: `Tool ${request.params.name} failed: ${message}` });
       return {
-        content: [{ type: "text", text: `Error: ${message}` }],
+        content: [{ type: "text", text: JSON.stringify({ error: message, success: false }) }],
         isError: true
       };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plur-ai/mcp",
-  "version": "0.9.9",
+  "version": "0.9.11",
   "type": "module",
   "bin": {
     "plur-mcp": "dist/index.js"
@@ -13,7 +13,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.23.0",
-    "@plur-ai/core": "0.9.9"
+    "@plur-ai/core": "0.9.11"
   },
   "devDependencies": {
     "@types/node": "^25.5.0"