@cachly-dev/mcp-server 0.10.5 → 0.10.7

package/dist/handlers/brain.js

@@ -1,8 +1,21 @@
 import { execSync } from 'node:child_process';
 import { calculateConfidence, confidenceBadge, STRUCTURED_TEMPLATES, CONFIDENCE_WARN_VALUE, CONFIDENCE_STALE_VALUE, CONFIDENCE_WARN_DAYS } from '../confidence.js';
 import { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge } from '../ckg.js';
+import { safeJsonParse } from '../utils.js';
 import { keywordSearch, tokenize, splitMultiQuery, levenshtein, indexVocab as _indexVocab } from '../search.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
+// ── Changelog (shown once per version in session_start) ──────────────────────
+const MCP_VERSION = '0.10.0';
+const WHATS_NEW = {
+    '0.10.0': [
+        `🆕 **What's new in v${MCP_VERSION}:**`,
+        `  ✅ Zero-friction setup — auto-provisions your Brain, no manual config needed`,
+        `  ✅ 10× faster briefings — batch Redis fetches replace per-key loops`,
+        `  ✅ Crash-proof data reads — corrupted cache entries no longer break tools`,
+        `  ✅ \`session_end\` warns when called without an active session`,
+        `  ✅ \`get_api_status\` now shows live Redis ping + all instance statuses`,
+    ],
+};
 export const BRAIN_TOOL_NAMES = new Set([
     'learn_from_attempts', 'recall_best_solution', 'smart_recall',
     'session_start', 'session_end', 'session_ping', 'session_handoff', 'auto_learn_session',
@@ -98,7 +111,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             for (const dep of depends_on) {
                 const depKey = `cachly:dep:${dep}`;
                 const existing = await redis.get(depKey);
-                const depTopics = existing ? JSON.parse(existing) : [];
+                const depTopics = safeJsonParse(existing, []);
                 if (!depTopics.includes(topic))
                     depTopics.push(topic);
                 await redis.set(depKey, JSON.stringify(depTopics));
@@ -190,7 +203,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         const er = await redis.get(ek);
                         if (!er)
                             continue;
-                        const existEdge = JSON.parse(er);
+                        const existEdge = safeJsonParse(er, null);
+                        if (!existEdge)
+                            continue;
                         if (existEdge.edgeType === 'fixes' && existEdge.confidence > 0.7 && existEdge.trials >= 3) {
                             beliefConflict = `⚠️ **belief_conflict** on \`${topic}\`: previously confirmed fix (confidence ${existEdge.confidence.toFixed(2)}, n=${existEdge.trials}) now reports failure. Both beliefs retained as \`contested\`. Use \`ckg_inspect(concept="${conceptId}")\` to review.`;
                             // Store conflict marker
@@ -198,7 +213,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                             await redis.set(conflictKey, JSON.stringify({ topic, detected_at: new Date().toISOString(), fix_confidence: existEdge.confidence, fix_trials: existEdge.trials, failure_outcome: outcome }), 'EX', 60 * 60 * 24 * 90);
                             // Auto-trigger MADC deliberation in background — never blocks learn_from_attempts
                             // Note: fire-and-forget; madc_deliberate is handled elsewhere in the switch
-                            apiFetch(`/api/v1/instances/${instance_id}`).catch(() => undefined); // keep apiFetch warm
+                            // (conflict marker stored above — no warm-up call needed)
                         }
                     }
                 }
@@ -210,7 +225,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         const er = await redis.get(ek);
                         if (!er)
                             continue;
-                        const e2 = JSON.parse(er);
+                        const e2 = safeJsonParse(er, null);
+                        if (!e2)
+                            continue;
                         if (e2.edgeType !== 'fixes')
                             continue;
                         // Boost second-degree: edges from e2.to get a small fractional success
@@ -219,7 +236,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                             const sr = await redis.get(sk);
                             if (!sr)
                                 continue;
-                            const se = JSON.parse(sr);
+                            const se = safeJsonParse(sr, null);
+                            if (!se)
+                                continue;
                             if (se.edgeType !== 'co-occurs')
                                 continue;
                             // Add 0.1 fractional success (second-degree signal)
@@ -241,7 +260,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         const er = await redis.get(ek);
                         if (!er)
                             continue;
-                        const de = JSON.parse(er);
+                        const de = safeJsonParse(er, null);
+                        if (!de)
+                            continue;
                         if (de.trials < 3 && de.last_updated && new Date(de.last_updated).getTime() < decayCutoff) {
                             de.confidence = de.confidence * 0.9;
                             de.last_updated = new Date().toISOString();
@@ -281,7 +302,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             // Try exact best-solution key first
             const best = await redis.get(`cachly:lesson:best:${topic}`);
             if (best) {
-                const lesson = JSON.parse(best);
+                const lesson = safeJsonParse(best, null);
+                if (!lesson)
+                    return `⚠️ Lesson data for \`${topic}\` is corrupted. Re-store it with \`learn_from_attempts\`.`;
                 // ── Confidence decay check ───────────────────────────────────────────
                 const confidence = calculateConfidence(lesson);
                 const ref = lesson.verified_at ?? lesson.ts;
@@ -295,6 +318,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     confidence: 1.0,
                 };
                 await redis.set(`cachly:lesson:best:${topic}`, JSON.stringify(updatedLesson));
+                // Track estimated time saved (30m minor · 60m major · 240m critical)
+                const savedMins = lesson.severity === 'critical' ? 240 : lesson.severity === 'major' ? 60 : 30;
+                redis.incrbyfloat(`cachly:stats:time_saved_mins:${instance_id}`, savedMins).catch(() => { });
                 const sevEmoji = lesson.severity === 'critical' ? '🔴' : lesson.severity === 'major' ? '🟡' : lesson.severity ? '🟢' : '';
                 const auditSummary = (lesson.audit_trail ?? []).length > 1
                     ? `_Audit: ${(lesson.audit_trail ?? []).length} changes · stored ${new Date(lesson.ts).toLocaleDateString('de-DE')}_`
@@ -336,7 +362,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 const histKey = `cachly:lessons:${topic}`;
                 const all = await redis.lrange(histKey, -3, -1);
                 if (all.length > 0) {
-                    const parsed = all.map(e => JSON.parse(e));
+                    const parsed = all.map(e => safeJsonParse(e, null)).filter(Boolean);
                     const lines = parsed.map(p => `- ${p.outcome === 'success' ? '✅' : '❌'} ${p.what_worked.slice(0, 120)} (${new Date(p.ts).toLocaleDateString('de-DE')})`);
                     return `⚠️ No successful solution for \`${topic}\` yet. Last attempts:\n\n${lines.join('\n')}`;
                 }
@@ -348,7 +374,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 const raw = await redis.get(k);
                 if (!raw)
                     continue;
-                const lesson = JSON.parse(raw);
+                const lesson = safeJsonParse(raw, null);
+                if (!lesson)
+                    continue;
                 results.push(`**\`${lesson.topic}\`** — ${lesson.what_worked.slice(0, 200)}`);
             }
             return `🔍 **Partial matches for \`${topic}\`:**\n\n${results.join('\n\n')}`;
@@ -485,14 +513,13 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 lStream.on('error', reject);
             });
             const lessons = [];
-            for (const k of lessonKeys) {
-                const raw = await redis.get(k);
-                if (!raw)
-                    continue;
-                try {
-                    lessons.push(JSON.parse(raw));
+            if (lessonKeys.length > 0) {
+                const raws = await redis.mget(...lessonKeys);
+                for (const raw of raws) {
+                    const l = safeJsonParse(raw ?? null, null);
+                    if (l)
+                        lessons.push(l);
                 }
-                catch { /* skip corrupt */ }
             }
             lessons.sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime());
             // 3. Count context entries (filter :meta keys)
@@ -507,13 +534,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             });
             // 4. Last session
             const lastSessionRaw = await redis.get('cachly:session:last');
-            let lastSession = null;
-            if (lastSessionRaw) {
-                try {
-                    lastSession = JSON.parse(lastSessionRaw);
-                }
-                catch { /* ignore */ }
-            }
+            const lastSession = safeJsonParse(lastSessionRaw, null);
             // 5. Focus filtering
             const focusTerms = focus.toLowerCase().split(/\s+/).filter(Boolean);
             const focusLessons = focusTerms.length > 0
@@ -526,7 +547,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             let streakMessage = '';
             try {
                 const streakRaw = await redis.get('cachly:streak:current');
-                const streak = streakRaw ? JSON.parse(streakRaw) : null;
+                const streak = safeJsonParse(streakRaw, null);
                 const today = new Date().toISOString().slice(0, 10);
                 if (streak) {
                     const lastDate = streak.last_date;
@@ -567,11 +588,54 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 focus,
                 provider,
             }), 'EX', 86400); // auto-expire after 24h if session_end never called
+            // 8. Time saved counter
+            let timeSavedMins = 0;
+            try {
+                const raw = await redis.get(`cachly:stats:time_saved_mins:${instance_id}`);
+                timeSavedMins = parseFloat(raw ?? '0');
+            }
+            catch { /* non-critical */ }
             // ── Build briefing ──────────────────────────────────────────────────────
             const providerLabel = provider ? ` · ${provider}` : '';
             const lines = [`🧠 **Session Briefing**${providerLabel}`, ''];
             if (streakMessage)
                 lines.push(streakMessage, '');
+            // Time saved (only show when meaningful — 30+ minutes)
+            if (timeSavedMins >= 30) {
+                const h = Math.floor(timeSavedMins / 60);
+                const m = Math.round(timeSavedMins % 60);
+                const timeStr = h > 0 ? `${h}h${m > 0 ? ` ${m}m` : ''}` : `${m}m`;
+                lines.push(`⏱️ **Brain saved you ~${timeStr} total** (time not re-researching known fixes)`, '');
+            }
+            // ── What's New (shown once per version update) ──────────────────────────
+            try {
+                const seenVersion = await redis.get('cachly:mcp:version:last_seen');
+                if (seenVersion !== MCP_VERSION) {
+                    await redis.set('cachly:mcp:version:last_seen', MCP_VERSION, 'EX', 365 * 86400);
+                    const changelog = WHATS_NEW[MCP_VERSION];
+                    if (changelog) {
+                        lines.push(...changelog, '');
+                    }
+                }
+            }
+            catch { /* non-critical */ }
+            // ── First-time welcome (empty brain) ───────────────────────────────────
+            const isFirstSession = !lastSession && lessons.length === 0 && ctxCount === 0;
+            if (isFirstSession) {
+                lines.push('🎉 **Welcome! Your AI Brain is live.**', '');
+                lines.push('It learns from your work automatically. After your first session it will look like this:', '');
+                lines.push('  ✅ `api:auth` — Bearer token in header, not cookie; 401 on missing scope');
+                lines.push('  ✅ `database:migrations` — always run migrations before deploy');
+                lines.push('  ⚠️ `docker:build` — ARG changes bust all subsequent cache layers');
+                lines.push('');
+                lines.push('**3 steps to grow your brain:**');
+                lines.push('  1. Fix something → `learn_from_attempts(topic="bug:name", outcome="success", what_worked="...")`');
+                lines.push('  2. Save context → `remember_context(key="arch", value="...")`');
+                lines.push('  3. End session → `session_end(summary="What I did")`');
+                lines.push('');
+                lines.push('💡 Run `brain_doctor` for a setup health-check and personalised tips.');
+                lines.push('');
+            }
             // Handoff from previous window (if any)
             const handoffRaw = await redis.get('cachly:session:handoff');
             if (handoffRaw) {
@@ -707,7 +771,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         const cr = await redis.get(ck);
                         if (!cr)
                             continue;
-                        const cf = JSON.parse(cr);
+                        const cf = safeJsonParse(cr, null);
+                        if (!cf)
+                            continue;
                         lines.push(`  ⚠️ \`${cf.topic}\` — previously confirmed fix (${(cf.fix_confidence * 100).toFixed(0)}%, n=${cf.fix_trials}) now contradicted. Use \`ckg_inspect(concept="${ckgSlug(cf.topic)}")\``);
                     }
                     lines.push('');
@@ -766,6 +832,14 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             else {
                 lines.push('📭 No lessons yet. Use `learn_from_attempts` after solving tasks.', '');
             }
+            // Team invite prompt — fires once after 10th lesson if no team use yet
+            if (lessons.length >= 10) {
+                const hasTeamUse = lessons.some(l => l.author);
+                if (!hasTeamUse) {
+                    lines.push(`🤝 **Your Brain has ${lessons.length} lessons — your team could benefit instantly.**`);
+                    lines.push(`   Share: **cachly.dev/team** · or run \`team_learn\` after the next fix.`, '');
+                }
+            }
             // Open failures (lessons whose best-key has outcome != success)
             const openFailures = lessons.filter(l => l.outcome === 'failure' || l.outcome === 'partial');
             if (openFailures.length > 0) {
@@ -857,14 +931,16 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             try {
                 const crystalRaw = await redis.get('cachly:crystal:latest');
                 if (crystalRaw) {
-                    const crystal = JSON.parse(crystalRaw);
-                    const crystalAge = Math.round((Date.now() - new Date(crystal.ts).getTime()) / 86_400_000);
-                    if (crystalAge <= 90) {
-                        lines.push(`💎 **Memory Crystal** (${crystal.label} · ${crystal.session_count} sessions compressed):`);
-                        for (const p of crystal.top_patterns.slice(0, 3)) {
-                            lines.push(`  • **${p.category}** (${p.count}×): ${p.insight.slice(0, 90)}`);
+                    const crystal = safeJsonParse(crystalRaw, null);
+                    if (crystal) {
+                        const crystalAge = Math.round((Date.now() - new Date(crystal.ts).getTime()) / 86_400_000);
+                        if (crystalAge <= 90) {
+                            lines.push(`💎 **Memory Crystal** (${crystal.label} · ${crystal.session_count} sessions compressed):`);
+                            for (const p of crystal.top_patterns.slice(0, 3)) {
+                                lines.push(`  • **${p.category}** (${p.count}×): ${p.insight.slice(0, 90)}`);
+                            }
+                            lines.push('');
                         }
-                        lines.push('');
                     }
                 }
             }
@@ -876,7 +952,10 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     const PRIORITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3 };
                     const PRIORITY_ICON = { critical: '🔴', high: '🟠', medium: '🟡', low: '🔵' };
                     const openStatuses = new Set(['planned', 'in-progress', 'blocked']);
-                    const allItems = Object.values(roadmapAll).map(v => JSON.parse(v));
+                    const allItems = Object.values(roadmapAll).flatMap(v => {
+                        const item = safeJsonParse(v, null);
+                        return item ? [item] : [];
+                    });
                     const openItems = allItems
                         .filter(i => openStatuses.has(i.status))
                         .sort((a, b) => {
@@ -917,23 +996,25 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                             const nodeRaw = await redis.get(nk);
                             if (!nodeRaw)
                                 continue;
-                            const node = JSON.parse(nodeRaw);
+                            const node = safeJsonParse(nodeRaw, null);
+                            if (!node)
+                                continue;
                             const edgeKeys = await redis.smembers(`cachly:ckg:idx:from:${node.id}`);
                             for (const ek of edgeKeys.slice(0, 15)) {
                                 const edgeRaw = await redis.get(ek);
                                 if (!edgeRaw)
                                     continue;
-                                const edge = JSON.parse(edgeRaw);
+                                const edge = safeJsonParse(edgeRaw, null);
+                                if (!edge)
+                                    continue;
                                 if (edge.edgeType !== 'causes' && edge.edgeType !== 'co-occurs' && edge.edgeType !== 'fixes')
                                     continue;
                                 if (edge.confidence < 0.35)
                                     continue;
-                                // For "fixes" edges, the lesson is on the "from" node (fix for "to")
-                                // For "causes" edges, target is the failure mode
                                 const lessonKey = edge.edgeType === 'fixes' ? `cachly:lesson:best:${edge.from}` : `cachly:lesson:best:${edge.to}`;
                                 const lessonRaw = await redis.get(lessonKey);
-                                const lesson = lessonRaw ? JSON.parse(lessonRaw) : undefined;
-                                ppePredictions.push({ concept: node.id, edgeType: edge.edgeType, target: edge.to, confidence: edge.confidence, lesson });
+                                const lesson = safeJsonParse(lessonRaw, null);
+                                ppePredictions.push({ concept: node.id, edgeType: edge.edgeType, target: edge.to, confidence: edge.confidence, lesson: lesson ?? undefined });
                             }
                         }
                     }
@@ -964,7 +1045,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             // Measures: of recalled lessons with confidence > 0.85, what % had outcome=success?
             try {
                 const calRaw = await redis.get('cachly:mcm:calibration:last');
-                const lastCalMs = calRaw ? JSON.parse(calRaw).ts : 0;
+                const lastCalMs = safeJsonParse(calRaw, null)?.ts ?? 0;
                 const daysSinceCal = (Date.now() - lastCalMs) / 86_400_000;
                 if (daysSinceCal >= 30 && lessons.length >= 5) {
                     // Quick calibration pass on recalled lessons (recall_count > 0, outcome=success)
@@ -1011,8 +1092,6 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             }
             catch { /* non-critical */ }
             // ── 🌍 Knowledge Commons — community stats banner ───────────────────────
-            // Fetch syndication stats and show a 1-liner: total lessons + confirms + weekly growth.
-            // Non-fatal: never blocks session start if the API call fails.
             try {
                 const commonsStats = await apiFetch('/api/v1/syndication/stats');
                 if (commonsStats.total_lessons > 0) {
@@ -1023,6 +1102,19 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 }
             }
             catch { /* non-critical — never block session start */ }
+            // ── Brain Doctor hint (Punkt 6) — surface when brain needs attention ───
+            const hasOpenFailures = lessons.filter(l => l.outcome === 'failure' || l.outcome === 'partial').length > 0;
+            const hasStaleLessons = lessons.some(l => l.outcome === 'success' && calculateConfidence(l) < CONFIDENCE_WARN_VALUE);
+            if (lessons.length === 0 || hasOpenFailures || hasStaleLessons) {
+                const reasons = [];
+                if (lessons.length === 0)
+                    reasons.push('brain is empty');
+                if (hasOpenFailures)
+                    reasons.push('open failures');
+                if (hasStaleLessons)
+                    reasons.push('stale lessons');
+                lines.push(`🩺 _Run \`brain_doctor\` to fix: ${reasons.join(', ')}._`);
+            }
             return lines.join('\n');
         }
         // ── session_end ───────────────────────────────────────────────────────────
@@ -1033,18 +1125,20 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             // Calculate duration from session_start marker
             let durationMin;
             const currentRaw = await redis.get('cachly:session:current');
-            if (currentRaw) {
-                try {
-                    const current = JSON.parse(currentRaw);
-                    durationMin = Math.round((now.getTime() - new Date(current.started).getTime()) / 60000);
-                }
-                catch { /* ignore */ }
+            if (!currentRaw) {
+                return `⚠️ No active session found.\n\nRun \`session_start\` first to begin tracking a session, then call \`session_end\` when you're done.`;
+            }
+            const current = safeJsonParse(currentRaw, null);
+            if (current?.started) {
+                durationMin = Math.round((now.getTime() - new Date(current.started).getTime()) / 60000);
             }
-            // ── Session Replay: capture decision log ─────────────────────────────
             let decisionLog = [];
             try {
                 const dlEntries = await redis.lrange('cachly:session:decision-log', 0, -1);
-                decisionLog = dlEntries.map(e => JSON.parse(e));
+                decisionLog = dlEntries.flatMap(e => {
+                    const entry = safeJsonParse(e, null);
+                    return entry ? [entry] : [];
+                });
                 await redis.del('cachly:session:decision-log');
             }
             catch { /* non-critical */ }