@cachly-dev/mcp-server 0.10.58 → 0.10.60

package/dist/src/handlers/brain.js

@@ -1,13 +1,27 @@
 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 { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge, ckgUpsertPersonNode, ckgUpsertFileNode } from '../ckg.js';
 import { safeJsonParse } from '../utils.js';
 import { keywordSearch, tokenize, splitMultiQuery, levenshtein, indexVocab as _indexVocab } from '../search.js';
 import { rerankByQuality } from '../rerank.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
 // ── Changelog (shown once per version in session_start) ──────────────────────
-const MCP_VERSION = '0.10.58';
+const MCP_VERSION = '0.10.60';
 const WHATS_NEW = {
+    '0.10.60': [
+        `🆕 **Phase 3B: File map + team overview + visibility**`,
+        `  📁 \`brain_file_map(file_paths=[...])\` — experts + lessons per file before you touch it`,
+        `  🗺️ \`team_expertise_map()\` — full team skills matrix in one table`,
+        `  🔒 \`visibility: "private"\` on \`learn_from_attempts\` — private notes never leak to smart_recall`,
+        `  📊 98 MCP tools`,
+    ],
+    '0.10.59': [
+        `🆕 **Phase 3A: Org-wide knowledge graph**`,
+        `  👥 \`brain_who_knows(topic="...")\` — find your team's experts on any topic instantly`,
+        `  🕸️ Person + File nodes auto-built from \`learn_from_attempts(author="...", file_paths=[...])\``,
+        `  👤 Author attribution now shown inline in \`smart_recall\` results`,
+        `  📊 96 MCP tools · 386 tests green`,
+    ],
     '0.10.58': [
         `🧹 Zero lint warnings — all unused imports cleaned across every handler`,
         `✅ Build: 0 errors, 0 warnings · 379 tests green`,
@@ -48,11 +62,12 @@ const WHATS_NEW = {
 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',
+    'brain_who_knows', 'brain_file_map', 'team_expertise_map',
 ]);
 export async function handleBrainTool(name, args, getConnection, apiFetch) {
     switch (name) {
         case 'learn_from_attempts': {
-            const { instance_id, topic, outcome, what_worked, what_failed = '', context: ctx = '', severity = 'major', file_paths = [], commands = [], tags = [], depends_on = [], author = '', } = args;
+            const { instance_id, topic, outcome, what_worked, what_failed = '', context: ctx = '', severity = 'major', file_paths = [], commands = [], tags = [], depends_on = [], author = '', visibility = 'team', } = args;
             const redis = await getConnection(instance_id);
             const ts = new Date().toISOString();
             // ── Structured template hints ──────────────────────────────────────────
@@ -170,6 +185,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 tags,
                 depends_on,
                 ...(author ? { author } : {}),
+                visibility,
                 recall_count: recallCount,
                 ts,
                 verified_at: outcome === 'success' || outcome === 'partial' ? ts : undefined,
@@ -316,6 +332,22 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 }
             }
             catch { /* CKG updates are non-critical */ }
+            // ── Phase 3A: People + File nodes in knowledge graph ──────────────────────
+            // Builds the "who knows what" map automatically from author + file_paths.
+            // Person → authored → Concept edges power brain_who_knows queries.
+            if (author) {
+                try {
+                    const domain = topic.split(':')[0] ?? 'unknown';
+                    const personId = await ckgUpsertPersonNode(redis, author, domain);
+                    const conceptId = ckgSlug(topic);
+                    await ckgUpdateEdge(redis, personId, 'authored', conceptId, outcome === 'success', outcome === 'partial');
+                    for (const fp of file_paths.slice(0, 8)) {
+                        const fileId = await ckgUpsertFileNode(redis, fp);
+                        await ckgUpdateEdge(redis, personId, 'touched', fileId, true);
+                    }
+                }
+                catch { /* non-critical */ }
+            }
             // ── Ambient team propagation: if author is set + outcome is success,
             // auto-store as a team lesson so knowledge is shared without a separate
             // team_learn call. Tags gain 'team'; the lesson is attributed to the author.
@@ -503,9 +535,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 }
             }
             // ── Layer 2: Semantic search (parallel, optional) ────────────────────────
-            const inst = await apiFetch(`/api/v1/instances/${instance_id}`);
+            const inst = await apiFetch(`/api/v1/instances/${instance_id}`).catch(() => null);
             const semHits = [];
-            if (inst.vector_token && hasEmbedProvider()) {
+            if (inst?.vector_token && hasEmbedProvider()) {
                 try {
                     const embedding = await computeEmbedding(query);
                     const vectorUrl = `https://api.cachly.dev/v1/sem/${inst.vector_token}`;
@@ -610,7 +642,15 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 }
             }
             catch { /* non-critical — keyword + semantic always available */ }
-            const hybridResults = [...hybridMap.values()].sort((a, b) => b.hybridScore - a.hybridScore);
+            // Filter private lessons — they are only accessible via exact recall_best_solution
+            const hybridResults = [...hybridMap.values()]
+                .filter(r => {
+                if (!r.key.startsWith('cachly:lesson:best:'))
+                    return true;
+                const ld = safeJsonParse(r.content, {});
+                return ld.visibility !== 'private';
+            })
+                .sort((a, b) => b.hybridScore - a.hybridScore);
             // ── Build output ──────────────────────────────────────────────────────────
             const lines = [`🧠 **Smart Recall** for: _"${query}"_\n`];
             // "Brain saved you here" banner — surfaces value inline for proven recalled lessons
@@ -670,13 +710,19 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 else {
                     for (const r of hybridResults.slice(0, 8)) {
                         const label = r.key.replace('cachly:ctx:', '📝 ').replace('cachly:lesson:best:', '💡 ').replace('cachly:idx:', '📂 ');
+                        let authorBadge = '';
+                        if (r.key.startsWith('cachly:lesson:best:')) {
+                            const ld = safeJsonParse(r.content, {});
+                            if (ld.author)
+                                authorBadge = ` · 👤 ${ld.author}`;
+                        }
                         const scorePart = r.matchType === 'hybrid'
                             ? `BM25: ${(r.bm25Score ?? 0).toFixed(2)}, sem: ${((r.semScore ?? 0) * 100).toFixed(0)}%, 🔀 hybrid`
                             : r.matchType === 'semantic'
                                 ? `sem: ${((r.semScore ?? 0) * 100).toFixed(0)}%, 🎯 semantic`
                                 : `BM25: ${(r.bm25Score ?? 0).toFixed(2)}, matched: ${r.matchedWords?.join(', ')}`;
                         const preview = r.content.slice(0, 400).replace(/\n/g, ' ');
-                        lines.push(`**${label}** _(${scorePart})_`);
+                        lines.push(`**${label}**${authorBadge} _(${scorePart})_`);
                         lines.push(`> ${preview}${r.content.length > 400 ? '…' : ''}\n`);
                     }
                 }
@@ -1785,6 +1831,275 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 lines.push(`**Skipped** (better lesson already exists): ${skipped.map(t => `\`${t}\``).join(', ')}`);
             return lines.join('\n');
         }
+        // ── brain_who_knows ───────────────────────────────────────────────────────
+        // Phase 3A: Org-wide people intelligence. Returns ranked list of contributors
+        // whose authored edges in the CKG match the query topic.
+        case 'brain_who_knows': {
+            const { instance_id, topic, limit = 10, } = args;
+            const redis = await getConnection(instance_id);
+            // Step 1: Find candidate concept node IDs matching the query
+            const querySlug = ckgSlug(topic);
+            const qTokens = tokenize(topic).filter((t) => t.length >= 3).slice(0, 5);
+            const candidateConceptIds = new Set([querySlug]);
+            for (const token of qTokens.slice(0, 3)) {
+                const nodeStream = redis.scanStream({ match: `cachly:ckg:node:*${token}*`, count: 30 });
+                await new Promise((res, rej) => {
+                    nodeStream.on('data', (batch) => {
+                        for (const k of batch.slice(0, 10)) {
+                            const nodeId = k.replace('cachly:ckg:node:', '');
+                            if (!nodeId.startsWith('person:') && !nodeId.startsWith('file:'))
+                                candidateConceptIds.add(nodeId);
+                        }
+                    });
+                    nodeStream.on('end', res);
+                    nodeStream.on('error', rej);
+                });
+            }
+            const personScores = new Map();
+            for (const conceptId of [...candidateConceptIds].slice(0, 25)) {
+                const inboundEdgeKeys = await redis.smembers(`cachly:ckg:idx:to:${conceptId}`);
+                for (const ek of inboundEdgeKeys) {
+                    const er = await redis.get(ek);
+                    if (!er)
+                        continue;
+                    const edge = safeJsonParse(er, null);
+                    if (!edge || edge.edgeType !== 'authored')
+                        continue;
+                    const personNodeRaw = await redis.get(`cachly:ckg:node:${edge.from}`);
+                    if (!personNodeRaw)
+                        continue;
+                    const personNode = safeJsonParse(personNodeRaw, null);
+                    if (!personNode || personNode.type !== 'person')
+                        continue;
+                    const existing = personScores.get(edge.from);
+                    if (existing) {
+                        existing.lessonCount++;
+                        existing.totalConfidence += edge.confidence;
+                        existing.domains.add(personNode.domain);
+                        if (edge.last_updated > existing.lastActive)
+                            existing.lastActive = edge.last_updated;
+                    }
+                    else {
+                        personScores.set(edge.from, {
+                            handle: personNode.handle,
+                            lessonCount: 1,
+                            totalConfidence: edge.confidence,
+                            domains: new Set([personNode.domain]),
+                            lastActive: personNode.last_active ?? edge.last_updated,
+                        });
+                    }
+                }
+            }
+            if (personScores.size === 0) {
+                return [
+                    `## 👥 Who Knows About \`${topic}\`?`,
+                    ``,
+                    `No attributed lessons found yet.`,
+                    ``,
+                    `Knowledge attribution builds automatically — add \`author="name"\` to \`learn_from_attempts\` calls:`,
+                    `\`learn_from_attempts(topic="${topic}", author="your-handle", ...)\``,
+                ].join('\n');
+            }
+            // Step 3: Sort by expertise score (lesson count × avg confidence)
+            const ranked = [...personScores.entries()]
+                .map(([, s]) => ({
+                handle: s.handle,
+                lessonCount: s.lessonCount,
+                avgConfidence: s.totalConfidence / s.lessonCount,
+                domains: [...s.domains].slice(0, 3).join(', '),
+                lastActive: s.lastActive,
+            }))
+                .sort((a, b) => (b.lessonCount * b.avgConfidence) - (a.lessonCount * a.avgConfidence))
+                .slice(0, limit);
+            const lines = [
+                `## 👥 Who Knows About \`${topic}\`?`,
+                ``,
+                `**${ranked.length}** contributor${ranked.length !== 1 ? 's' : ''} with relevant lessons:`,
+                ``,
+            ];
+            for (const [i, p] of ranked.entries()) {
+                const medal = i === 0 ? '🥇' : i === 1 ? '🥈' : i === 2 ? '🥉' : `${i + 1}.`;
+                const conf = (p.avgConfidence * 100).toFixed(0);
+                const daysSince = Math.floor((Date.now() - new Date(p.lastActive).getTime()) / 86400000);
+                const recency = daysSince < 1 ? 'today' : daysSince < 7 ? `${daysSince}d ago` : daysSince < 30 ? `${Math.floor(daysSince / 7)}w ago` : `${Math.floor(daysSince / 30)}mo ago`;
+                lines.push(`${medal} **${p.handle}** — ${p.lessonCount} lesson${p.lessonCount !== 1 ? 's' : ''} · ${conf}% confidence · last active ${recency}`, `   _domains: ${p.domains}_`, ``);
+            }
+            lines.push(`---`, `_Attribution grows with every \`learn_from_attempts(author="...", ...)\` call._`);
+            return lines.join('\n');
+        }
+        // ── brain_file_map ────────────────────────────────────────────────────────
+        // Phase 3B: "What do we know about these files?" — experts + lessons per file.
+        case 'brain_file_map': {
+            const { instance_id, file_paths = [], } = args;
+            if (!file_paths.length)
+                return '⚠️ Pass at least one file path.';
+            const redis = await getConnection(instance_id);
+            const lines = [
+                `## 📁 File Knowledge Map`,
+                ``,
+                `_What cachly knows about the files you're about to touch:_`,
+                ``,
+            ];
+            for (const fp of file_paths.slice(0, 10)) {
+                lines.push(`### \`${fp}\``);
+                // ── Experts via CKG file nodes ─────────────────────────────────────
+                const fileId = `file:${ckgSlug(fp)}`;
+                const inbound = await redis.smembers(`cachly:ckg:idx:to:${fileId}`);
+                const experts = [];
+                for (const ek of inbound) {
+                    const er = await redis.get(ek);
+                    if (!er)
+                        continue;
+                    const edge = safeJsonParse(er, null);
+                    if (!edge || edge.edgeType !== 'touched')
+                        continue;
+                    const personRaw = await redis.get(`cachly:ckg:node:${edge.from}`);
+                    if (!personRaw)
+                        continue;
+                    const pn = safeJsonParse(personRaw, null);
+                    if (!pn || pn.type !== 'person')
+                        continue;
+                    experts.push({ handle: pn.handle, touches: edge.trials, lastSeen: edge.last_updated });
+                }
+                experts.sort((a, b) => b.touches - a.touches);
+                if (experts.length > 0) {
+                    const expLine = experts.slice(0, 5).map((e, i) => {
+                        const medal = i === 0 ? '🥇' : i === 1 ? '🥈' : i === 2 ? '🥉' : `${i + 1}.`;
+                        const days = Math.floor((Date.now() - new Date(e.lastSeen).getTime()) / 86400000);
+                        const ago = days < 1 ? 'today' : days < 7 ? `${days}d ago` : `${Math.floor(days / 7)}w ago`;
+                        return `${medal} **${e.handle}** (${e.touches}× · ${ago})`;
+                    }).join(' · ');
+                    lines.push(`**Experts:** ${expLine}`);
+                }
+                else {
+                    lines.push(`**Experts:** _None yet — add \`author\` to \`learn_from_attempts\` calls_`);
+                }
+                // ── Related lessons via BM25 on filename tokens ────────────────────
+                const tokens = fp.replace(/[^a-z0-9]/gi, ' ').split(/\s+/).filter(t => t.length >= 4);
+                const lessonQuery = tokens.slice(0, 3).join(' ');
+                const relatedLessons = [];
+                if (lessonQuery) {
+                    try {
+                        const hits = await keywordSearch(redis, ['cachly:lesson:best:*'], lessonQuery, 4);
+                        for (const h of hits) {
+                            const ld = safeJsonParse(h.content, {});
+                            if (ld.visibility === 'private')
+                                continue;
+                            const emoji = ld.outcome === 'success' ? '✅' : ld.outcome === 'partial' ? '⚠️' : '❌';
+                            const sev = ld.severity === 'critical' ? ' 🔴' : ld.severity === 'major' ? ' 🟡' : '';
+                            const by = ld.author ? ` · 👤 ${ld.author}` : '';
+                            const topic = h.key.replace('cachly:lesson:best:', '');
+                            relatedLessons.push(`  - ${emoji} \`${topic}\`${sev}${by} — ${(ld.what_worked ?? '').slice(0, 100)}`);
+                        }
+                    }
+                    catch { /* non-critical */ }
+                }
+                // Also: exact file_paths match via lesson scan
+                if (relatedLessons.length < 2) {
+                    const scanKeys = [];
+                    const stream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
+                    await new Promise((res, rej) => {
+                        stream.on('data', (b) => scanKeys.push(...b));
+                        stream.on('end', res);
+                        stream.on('error', rej);
+                    });
+                    for (const k of scanKeys.slice(0, 300)) {
+                        const raw = await redis.get(k);
+                        if (!raw)
+                            continue;
+                        const ld = safeJsonParse(raw, {});
+                        if (ld.visibility === 'private')
+                            continue;
+                        if (!(ld.file_paths ?? []).includes(fp))
+                            continue;
+                        const topic = k.replace('cachly:lesson:best:', '');
+                        if (relatedLessons.some(l => l.includes(`\`${topic}\``)))
+                            continue;
+                        const emoji = ld.outcome === 'success' ? '✅' : ld.outcome === 'partial' ? '⚠️' : '❌';
+                        const sev = ld.severity === 'critical' ? ' 🔴' : ld.severity === 'major' ? ' 🟡' : '';
+                        const by = ld.author ? ` · 👤 ${ld.author}` : '';
+                        relatedLessons.push(`  - ${emoji} \`${topic}\`${sev}${by} — ${(ld.what_worked ?? '').slice(0, 100)}`);
+                    }
+                }
+                if (relatedLessons.length > 0) {
+                    lines.push(`**Related lessons:**`);
+                    lines.push(...relatedLessons.slice(0, 5));
+                }
+                else {
+                    lines.push(`**Related lessons:** _None yet_`);
+                }
+                lines.push(``);
+            }
+            lines.push(`---`, `_Attribution builds with \`learn_from_attempts(file_paths=[...], author="...")\`. Run this before committing to track what changed and why._`);
+            return lines.join('\n');
+        }
+        // ── team_expertise_map ────────────────────────────────────────────────────
+        // Phase 3B: Full team expertise overview — who knows what, at a glance.
+        case 'team_expertise_map': {
+            const { instance_id, top_n = 20, } = args;
+            const redis = await getConnection(instance_id);
+            // Scan all person nodes
+            const personKeys = [];
+            const pStream = redis.scanStream({ match: 'cachly:ckg:node:person:*', count: 200 });
+            await new Promise((res, rej) => {
+                pStream.on('data', (b) => personKeys.push(...b));
+                pStream.on('end', res);
+                pStream.on('error', rej);
+            });
+            if (personKeys.length === 0) {
+                return [
+                    `## 🗺️ Team Expertise Map`,
+                    ``,
+                    `No contributors yet.`,
+                    ``,
+                    `Add \`author="handle"\` to any \`learn_from_attempts\` call to start building the map.`,
+                ].join('\n');
+            }
+            const people = [];
+            for (const pk of personKeys) {
+                const raw = await redis.get(pk);
+                if (!raw)
+                    continue;
+                const pn = safeJsonParse(raw, null);
+                if (!pn || pn.type !== 'person')
+                    continue;
+                // Count authored lessons + collect domains from authored edges
+                const outEdgeKeys = await redis.smembers(`cachly:ckg:idx:from:${pn.id}`);
+                const domainCounts = new Map();
+                let lessonCount = 0;
+                for (const ek of outEdgeKeys) {
+                    const er = await redis.get(ek);
+                    if (!er)
+                        continue;
+                    const edge = safeJsonParse(er, null);
+                    if (!edge || edge.edgeType !== 'authored')
+                        continue;
+                    lessonCount++;
+                    const domain = edge.to.split(':')[0] ?? 'unknown';
+                    domainCounts.set(domain, (domainCounts.get(domain) ?? 0) + 1);
+                }
+                people.push({ handle: pn.handle, lessonCount, domains: domainCounts, lastActive: pn.last_active });
+            }
+            people.sort((a, b) => b.lessonCount - a.lessonCount);
+            const topPeople = people.slice(0, top_n);
+            const lines = [
+                `## 🗺️ Team Expertise Map`,
+                ``,
+                `**${topPeople.length}** contributor${topPeople.length !== 1 ? 's' : ''} tracked:`,
+                ``,
+                `| # | Handle | Lessons | Top domains | Last active |`,
+                `|---|--------|---------|-------------|-------------|`,
+            ];
+            for (const [i, p] of topPeople.entries()) {
+                const medal = i === 0 ? '🥇' : i === 1 ? '🥈' : i === 2 ? '🥉' : `${i + 1}`;
+                const days = Math.floor((Date.now() - new Date(p.lastActive).getTime()) / 86400000);
+                const ago = days < 1 ? 'today' : days < 7 ? `${days}d ago` : days < 30 ? `${Math.floor(days / 7)}w ago` : `${Math.floor(days / 30)}mo ago`;
+                const domainStr = [...p.domains.entries()].sort((a, b) => b[1] - a[1]).slice(0, 3).map(([d, c]) => `${d}(${c})`).join(', ') || '—';
+                lines.push(`| ${medal} | **${p.handle}** | ${p.lessonCount} | ${domainStr} | ${ago} |`);
+            }
+            lines.push(``, `---`, `_Use \`brain_who_knows(topic="...")\` to find the expert for a specific problem._`);
+            return lines.join('\n');
+        }
         // ── sync_file_changes ─────────────────────────────────────────────────────
         default:
             return null;