@cachly-dev/mcp-server 0.10.122 → 0.10.123

package/dist/src/handlers/brain.js

@@ -1,4 +1,5 @@
 import { execSync } from 'node:child_process';
+import { createRequire } from 'node:module';
 import { calculateConfidence, confidenceBadge, STRUCTURED_TEMPLATES, CONFIDENCE_WARN_VALUE, CONFIDENCE_STALE_VALUE, CONFIDENCE_WARN_DAYS } from '../confidence.js';
 import { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge, ckgUpsertPersonNode, ckgUpsertFileNode, ckgRecordCollaboration, ckgUpsertServiceNode } from '../ckg.js';
 import { safeJsonParse, scanKeys } from '../utils.js';
@@ -6,15 +7,47 @@ import { getRole, ROLE_BADGE, getScopes, lessonVisibleToScope, reviewModeEnabled
 import { keywordSearch, tokenize, splitMultiQuery, levenshtein, indexVocab as _indexVocab } from '../search.js';
 import { rerankByQuality, qualityMultiplier, extractLessonQuality } from '../rerank.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
+import { upgradeNudge } from '../upgrade-nudge.js';
+import { cachlyUrl } from '../cachly-url.js';
 // ── Changelog (shown once per version in session_start) ──────────────────────
-const MCP_VERSION = '0.10.119';
+// Resolve the package version at runtime from package.json so the session briefing
+// `version` field always matches the published npm version. A hardcoded constant
+// silently drifted (0.10.119 vs published 0.10.122), making new-feature adoption
+// impossible to track. Paths cover both prod (dist/handlers/brain.js → ../../../) and
+// dev (src/handlers/brain.ts → ../../../). Falls back to a literal if resolution fails.
+const CURRENT_VERSION = (() => {
+    try {
+        const req = createRequire(import.meta.url);
+        for (const rel of ['../../../package.json', '../../package.json']) {
+            try {
+                const pkg = req(rel);
+                if (pkg.name === '@cachly-dev/mcp-server' && pkg.version)
+                    return pkg.version;
+            }
+            catch { /* try next candidate */ }
+        }
+    }
+    catch { /* fall through to literal */ }
+    return '0.10.100';
+})();
+// Resolve the total MCP tools count at runtime from generated capabilities.
+// This count is shown in session_start's What's-New briefing for the current version.
+// Falls back silently per CONTRACT: better to skip the count than show a wrong number.
+const getTotalMcpTools = () => {
+    try {
+        const req = createRequire(import.meta.url);
+        const caps = req('../../../CACHLY_CAPABILITIES.json');
+        return caps.mcp?.total_tools ?? null;
+    }
+    catch { /* fail silently */ }
+    return null;
+};
 const WHATS_NEW = {
     '0.10.119': [
         `🔍 **Explainable briefings — provenance in every warning**`,
         `  📎 \`/briefing\` warnings now carry \`outcome\`, \`author\`, \`learned_at\` and \`matched_on\` (the context tokens that triggered the warning) — editors can show WHY a fix hint fired, not just what it claims.`,
         `  🧰 VS Code 0.12.0 uses this: severity + confidence in the toast, full lesson card with provenance, "Not helpful" per-file suppression, reviewable CLS auto-learns.`,
         `  🧹 CI docs now describe exactly what ships: scan mode uses the REST \`/scan\` endpoint, the GitLab template covers learn/scan/confirm.`,
-        `  📊 126 MCP tools`,
     ],
     '0.10.115': [
         `🔧 **\`brain_get_pref\` + \`brain_set_pref\` — persistent Brain preferences**`,
@@ -332,7 +365,7 @@ const WHATS_NEW = {
         `✅ Build: 0 errors, 0 warnings · 379 tests green`,
     ],
     '0.10.57': [
-        `🆕 **What's new in v${MCP_VERSION}:**`,
+        `🆕 **What's new in v${CURRENT_VERSION}:**`,
         `  🔧 **Critical fix** — corrected the npm bin/main entry path (\`dist/src/index.js\`); 0.10.50–0.10.52 shipped a broken entry point`,
         `  🔧 Version hygiene — synced package.json, server.json, lockfile, MCP_VERSION; \`latest\` now points forward again`,
         `  ✅ Accurate tool count (95) across README, server.json, CLI banners`,
@@ -379,8 +412,18 @@ export const BRAIN_TOOL_NAMES = new Set([
 // DEPTH gate (hide the tail), never an access wall: the #1 result is always
 // returned. Usage/limit come from the same authoritative numbers as the Brain
 // Health bar (GET /instances/:id/memory), cached briefly to avoid per-call latency.
-const UPGRADE_URL = 'https://cachly.dev/billing';
+const UPGRADE_URL = cachlyUrl('/billing', 'upgrade');
 const _recallGateCache = new Map();
+/**
+ * Instances whose notice has already been shown in this process.
+ *
+ * Once per PROCESS, not once per call: the MCP server lives for the length of
+ * the editor session, so this is exactly "once per session". Without it the
+ * notice would repeat on every session_start — and with Ambient Recall that is
+ * every prompt. That is the nagging the upgrade nudge was built to avoid, and
+ * a line that appears every time stops being read within a day.
+ */
+const _noticeGezeigt = new Set();
 // ── Recall quota: ONE unit per recall CALL ───────────────────────────────────
 // The gate above reads a monthly counter that this function writes. It counts
 // calls, not lessons.
@@ -421,6 +464,7 @@ async function getRecallGate(instanceId, apiFetch) {
             limit,
             used,
             goodwillMessage: mem?.goodwill_message,
+            notice: mem?.notice,
         };
         _recallGateCache.set(instanceId, { gate, expiresAt: Date.now() + 60_000 });
         return gate;
@@ -1462,6 +1506,24 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 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)`, '');
             }
+            // Upgrade nudge — surfaces the free-tier quota BEFORE the wall, once
+            // per session and right next to the value it just proved.
+            const recallGate = await getRecallGate(instance_id, apiFetch);
+            const nudge = upgradeNudge({ used: recallGate.used, limit: recallGate.limit, savedMins: timeSavedMins });
+            if (nudge)
+                lines.push(nudge, '');
+            // Notice from the API — the only channel that reaches a WORKING account.
+            // Everything else we can say today requires denying the user something
+            // first (the 402 goodwill text arrived because it was an error), and most
+            // accounts have no email address on file.
+            //
+            // Once per process, so once per editor session. Repeating it would put it
+            // in front of the user on every prompt via Ambient Recall, and a line
+            // that appears every time stops being read within a day.
+            if (recallGate.notice && !_noticeGezeigt.has(instance_id)) {
+                _noticeGezeigt.add(instance_id);
+                lines.push(recallGate.notice, '');
+            }
             // ── Welcome-back digest (gap ≥ 7 days) ──────────────────────────────────
             // When the user has been away a week or more, lead with a short "what
             // happened while you were gone" digest. All data is already loaded above
@@ -1491,11 +1553,16 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             // ── 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 (seenVersion !== CURRENT_VERSION) {
+                    await redis.set('cachly:mcp:version:last_seen', CURRENT_VERSION, 'EX', 365 * 86400);
+                    const changelog = WHATS_NEW[CURRENT_VERSION];
                     if (changelog) {
                         lines.push(...changelog, '');
+                        // For current version, append dynamic tool count if available
+                        const toolCount = getTotalMcpTools();
+                        if (toolCount) {
+                            lines.push(`📊 ${toolCount} MCP tools`, '');
+                        }
                     }
                 }
             }
@@ -2356,33 +2423,12 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     await redis.expire(key, 90 * 86400);
                     autoLearned.push(topic);
                 }
-                // Also store a lesson per changed file area if files were changed
-                if (files_changed.length > 0) {
-                    const areas = [...new Set(files_changed.map(f => f.split('/').slice(0, 2).join('/')))].slice(0, 3);
-                    for (const area of areas) {
-                        const slug = area.replace(/[^a-z0-9]/gi, '-').toLowerCase().replace(/-+/g, '-').slice(0, 30);
-                        const topic = `auto:changed:${slug}`;
-                        const key = `cachly:lesson:best:${topic}`;
-                        const lesson = {
-                            topic,
-                            outcome: 'success',
-                            what_worked: `Files changed in ${area}: ${files_changed.filter(f => f.startsWith(area.split('/')[0])).slice(0, 5).join(', ')}`,
-                            context: summary.slice(0, 200),
-                            severity: 'minor',
-                            ts: now.toISOString(),
-                            recall_count: 0,
-                            auto_learned: true,
-                            version: 2,
-                        };
-                        await redis.set(key, JSON.stringify(lesson));
-                        await redis.expire(key, 90 * 86400);
-                        autoLearned.push(topic);
-                    }
-                }
             }
             catch { /* auto-learn errors must never break session_end */ }
             // ── 🌿 Ambient Git Learning ────────────────────────────────────────────────
             // Read git commits since session start → auto-learn each meaningful commit.
+            // The commit BODY (%b) carries the reasoning — what was measured, what the
+            // cause was, what trap it avoided. The subject (%s) alone is just a heading.
             const ambientLearned = [];
             if (workspace_path) {
                 try {
@@ -2396,13 +2442,56 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         } })()
                         : '';
                     const sinceArg = sessionStartTs ? `--since="${sessionStartTs}"` : '--since="1 hour ago"';
-                    const gitOut = execSync(`git -C "${workspace_path}" log ${sinceArg} --oneline --format="%H|||%s|||%ai"`, { timeout: 5000, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+                    // '|||ENDE' terminates one commit's record. A commit body can contain
+                    // blank lines and newlines of its own, so splitting the raw output on
+                    // '\n' would tear a single multi-line body apart into several fake
+                    // "commits" — splitting on the marker keeps each body intact.
+                    const gitOut = execSync(`git -C "${workspace_path}" log ${sinceArg} --oneline --format="%H|||%s|||%b|||%ai|||ENDE"`, { timeout: 5000, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
                     if (gitOut) {
                         const commitActionRe = /\b(fix|add|remove|refactor|migrate|update|resolve|implement|improve|optimize|configure|create|delete|disable|enable|debug|patch|upgrade|build|rewrite|deploy|feat|chore|docs|test|perf|ci)\b/i;
-                        for (const line of gitOut.split('\n').slice(0, 10)) {
-                            const [hash, msg, dateStr] = line.split('|||');
+                        const commitBlocks = gitOut.split('|||ENDE').map(b => b.trim()).filter(Boolean);
+                        for (const block of commitBlocks.slice(0, 10)) {
+                            const [hash, msg, rawBody, dateStr] = block.split('|||');
+                            // Files touched together in one commit are recorded as co-occurs
+                            // edges between file nodes in the graph ("who touches A usually
+                            // touches B") — that is independent of whether the commit message
+                            // itself is lesson-worthy, so it runs for every recent commit.
+                            if (hash) {
+                                try {
+                                    // '--root' matters for a repo's very first commit: without it,
+                                    // diff-tree has no parent to compare against and silently
+                                    // reports zero changed files for that commit.
+                                    const nameOut = execSync(`git -C "${workspace_path}" diff-tree --no-commit-id --name-only -r --root "${hash}"`, { timeout: 5000, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+                                    // Pairing is quadratic, so the cap decides the cost — and this
+                                    // runs inside session_end, which must stay quick. At 12 files
+                                    // that is 66 pairs; at 25 it would be 300, times up to ten
+                                    // commits. Each file node is upserted ONCE up front instead of
+                                    // once per pair: with 12 files that is 12 upserts rather than
+                                    // 132, and it turns ~530 round-trips into ~144.
+                                    const CO_OCCUR_MAX_FILES = 12;
+                                    const changedFiles = nameOut
+                                        ? nameOut.split('\n').map(f => f.trim()).filter(Boolean).slice(0, CO_OCCUR_MAX_FILES)
+                                        : [];
+                                    const fileIds = [];
+                                    for (const f of changedFiles)
+                                        fileIds.push(await ckgUpsertFileNode(redis, f));
+                                    for (let i = 0; i < fileIds.length; i++) {
+                                        for (let j = i + 1; j < fileIds.length; j++) {
+                                            await ckgUpdateEdge(redis, fileIds[i], 'co-occurs', fileIds[j], true);
+                                            await ckgUpdateEdge(redis, fileIds[j], 'co-occurs', fileIds[i], true);
+                                        }
+                                    }
+                                }
+                                catch { /* file co-occurrence is best-effort */ }
+                            }
                             if (!msg || !commitActionRe.test(msg))
                                 continue;
+                            // A heading alone is not a lesson. Without a substantial body —
+                            // the why, the measurement, the trap — nothing gets stored: better
+                            // no entry than one that fills space and says nothing.
+                            const body = (rawBody ?? '').trim();
+                            if (body.length < 120)
+                                continue;
                             const slug = msg
                                 .toLowerCase().replace(/^(fix|feat|chore|docs|test|ci|perf|refactor|build|revert)[:(\s]/i, '')
                                 .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40);
@@ -2416,7 +2505,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                             const commitLesson = {
                                 topic,
                                 outcome: 'success',
-                                what_worked: msg.slice(0, 200),
+                                what_worked: `${msg}\n\n${body.slice(0, 1200)}`,
                                 context: `Auto-learned from git commit ${(hash ?? '').slice(0, 7)} at ${dateStr ?? ''} in ${workspace_path}`,
                                 severity: 'minor',
                                 ts: now.toISOString(),
@@ -3349,7 +3438,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                             cachly: {
                                 command: 'npx',
                                 args: ['@cachly-dev/mcp-server@latest'],
-                                env: { CACHLY_INSTANCE_ID: instance_id },
+                                env: { CACHLY_JWT: '<cky_live_...>', CACHLY_BRAIN_INSTANCE_ID: instance_id },
                             },
                         },
                     }, null, 2),
@@ -3364,7 +3453,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                             cachly: {
                                 command: 'npx',
                                 args: ['@cachly-dev/mcp-server@latest'],
-                                env: { CACHLY_INSTANCE_ID: instance_id },
+                                env: { CACHLY_JWT: '<cky_live_...>', CACHLY_BRAIN_INSTANCE_ID: instance_id },
                             },
                         },
                     }, null, 2),
@@ -3379,7 +3468,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                             cachly: {
                                 command: 'npx',
                                 args: ['@cachly-dev/mcp-server@latest'],
-                                env: { CACHLY_INSTANCE_ID: instance_id },
+                                env: { CACHLY_JWT: '<cky_live_...>', CACHLY_BRAIN_INSTANCE_ID: instance_id },
                             },
                         },
                     }, null, 2),
@@ -3395,7 +3484,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                                 type: 'stdio',
                                 command: 'npx',
                                 args: ['@cachly-dev/mcp-server@latest'],
-                                env: { CACHLY_INSTANCE_ID: instance_id },
+                                env: { CACHLY_JWT: '<cky_live_...>', CACHLY_BRAIN_INSTANCE_ID: instance_id },
                             },
                         },
                     }, null, 2),
@@ -3410,7 +3499,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                             cachly: {
                                 command: 'npx',
                                 args: ['@cachly-dev/mcp-server@latest'],
-                                env: { CACHLY_INSTANCE_ID: instance_id },
+                                env: { CACHLY_JWT: '<cky_live_...>', CACHLY_BRAIN_INSTANCE_ID: instance_id },
                             },
                         },
                     }, null, 2),
@@ -3424,7 +3513,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         context_servers: {
                             cachly: {
                                 command: { path: 'npx', args: ['@cachly-dev/mcp-server@latest'] },
-                                env: { CACHLY_INSTANCE_ID: instance_id },
+                                env: { CACHLY_JWT: '<cky_live_...>', CACHLY_BRAIN_INSTANCE_ID: instance_id },
                             },
                         },
                     }, null, 2),
@@ -3439,7 +3528,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                             {
                                 name: 'cachly',
                                 command: 'npx @cachly-dev/mcp-server@latest',
-                                env: { CACHLY_INSTANCE_ID: instance_id },
+                                env: { CACHLY_JWT: '<cky_live_...>', CACHLY_BRAIN_INSTANCE_ID: instance_id },
                             },
                         ],
                     }, null, 2),
@@ -3452,6 +3541,8 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 ``,
                 `**Your Brain ID:** \`${instance_id}\``,
                 ``,
+                `Replace \`<cky_live_...>\` below with your own API key (get one at https://cachly.dev/setup-ai) — the Brain ID alone does not authenticate you.`,
+                ``,
                 `This Brain ID is model-agnostic. Every lesson you've learned, every Memory Crystal you've distilled,`,
                 `and every prediction from your Causal Knowledge Graph is accessible from **any MCP-compatible AI client**.`,
                 ``,