@cachly-dev/mcp-server 0.10.117 → 0.10.118

package/dist/src/index.js

@@ -694,6 +694,10 @@ import { handleAdvancedTool } from './handlers/advanced.js';
 import { handleSyndicateTool } from './handlers/syndicate.js';
 import { handleFedbrainTool, _lastBrainFromGitCounts } from './handlers/fedbrain.js';
 import { installClsPostCommitHook, CLS_HOOK_VERSION } from './cls-hook.js';
+import { installAmbientHooks, AMBIENT_HOOK_VERSION } from './ambient-hooks.js';
+import { runAmbient, truncateToTokens, parseHookPayload, stopObservation } from './ambient-cli.js';
+import { appendLedgerEntry, readLedger, defaultLedgerPath } from './ambient-ledger.js';
+import { netBalance, shouldBackoff } from './ambient-recall.js';
 import { handleShareTool } from './handlers/share.js';
 import { handleVizTool } from './handlers/viz.js';
 // ── Tools (imported from tools.ts) ─────────────────────────────────────────
@@ -748,6 +752,21 @@ function sendFunnelEvent(event, extra, metrics) {
         signal: AbortSignal.timeout(3000),
     }).catch(() => { });
 }
+// Mirrors one ambient net-token ledger entry to the API (Phase 4 v2: the
+// org-wide dashboard aggregates these per team). Best-effort fire-and-forget —
+// the local JSONL ledger stays authoritative; this never throws and never
+// blocks a hook. Returns the fetch promise so short-lived CLI paths can flush
+// (bounded) before process.exit kills the socket.
+function reportAmbientLedgerEvent(instanceId, entry) {
+    if (!instanceId || !JWT || process.env.CACHLY_NO_TELEMETRY === '1')
+        return Promise.resolve();
+    return fetch(`${API_URL}/api/v1/instances/${instanceId}/ambient-events`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${JWT}` },
+        body: JSON.stringify({ events: [entry] }),
+        signal: AbortSignal.timeout(3000),
+    }).then(() => undefined, () => undefined);
+}
 async function sendAnonymousTelemetry(toolName) {
     if (_telemetryPingSent)
         return;
@@ -1178,7 +1197,19 @@ async function handleTool(name, args) {
             return `⚠️ Unknown tool: ${name}`;
     }
 }
-const server = new Server({ name: 'cachly-mcp', version: CURRENT_VERSION }, { capabilities: { tools: {} } });
+// Pushed to every MCP host at connect time (initialize response). This is the
+// "SessionStart-equivalent" for harnesses without a per-prompt hook — Cursor,
+// Windsurf, Cline, Copilot agent-mode all surface `instructions`. It's a one-time
+// nudge (not per-prompt recall), so it stays short and behavior-focused.
+const CACHLY_MCP_INSTRUCTIONS = `This project has a Cachly AI Brain — persistent, cross-session memory of past fixes, decisions, and gotchas for THIS codebase. Use it proactively; it makes you faster and stops you repeating known mistakes.
+
+- BEFORE a non-trivial task: call smart_recall with a short description of what you're about to do. If it returns lessons, apply them before researching from scratch.
+- WHEN debugging an error: call causal_trace with the exact error first — a known fix may already exist.
+- AFTER a fix, deploy, or discovery: call learn_from_attempts so the knowledge persists.
+- BEFORE a risky op (deploy, migration, dependency bump): call brain_predict.
+
+The Brain instance id comes from the CACHLY_BRAIN_INSTANCE_ID environment variable.`;
+const server = new Server({ name: 'cachly-mcp', version: CURRENT_VERSION }, { capabilities: { tools: {} }, instructions: CACHLY_MCP_INSTRUCTIONS });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 // ── Auto-session management ───────────────────────────────────────────────────
 // Transparently starts a Brain session on the first tool call of a process
@@ -1467,31 +1498,49 @@ Report predicted failure risks to the user before proceeding.
 Never commit code that does not compile. Run \`tsc --noEmit\` / \`go build ./...\` before every commit.
 ${CLAUDE_MD_MARKER_END}`;
 }
+// Cursor loads rules from .cursor/rules/*.mdc with YAML frontmatter. alwaysApply
+// makes the block active in every request (the closest Cursor gets to a
+// SessionStart briefing). The frontmatter sits OUTSIDE the brain markers so
+// idempotent marker-replacement leaves it intact.
+const CURSOR_MDC_FRONTMATTER = '---\n' +
+    'description: Cachly AI Brain — persistent memory protocol (recall before tasks, learn after fixes)\n' +
+    'alwaysApply: true\n' +
+    '---\n\n';
 /**
- * Schreibt das Brain-Protokoll in alle relevanten Instruction-Dateien:
- * - CLAUDE.md
- * - AGENTS.md
- * - .github/copilot-instructions.md
- * Idempotent, Marker-basiert.
+ * Schreibt das Brain-Protokoll in alle relevanten Instruction-/Rules-Dateien:
+ * - CLAUDE.md                        (Claude Code)
+ * - AGENTS.md                        (Codex / generic agents)
+ * - .github/copilot-instructions.md  (GitHub Copilot)
+ * - .cursor/rules/cachly.mdc         (Cursor — frontmatter + alwaysApply)
+ * - .windsurfrules                   (Windsurf / Cascade)
+ * - .clinerules                      (Cline)
+ * Idempotent, Marker-basiert. Cross-Harness Tier A (siehe make_cachly_great_again.md §6.7).
  */
 export async function writeInstructions(projectDir, instanceId) {
     const { writeFile, appendFile, readFile, mkdir } = await import('node:fs/promises');
     const { existsSync } = await import('node:fs');
     const { resolve, dirname } = await import('node:path');
+    // `prefix` is written only when the file is created fresh (Cursor .mdc needs it);
+    // on marker-update/append the prefix is left untouched.
     const files = [
-        resolve(projectDir, 'CLAUDE.md'),
-        resolve(projectDir, 'AGENTS.md'),
-        resolve(projectDir, '.github', 'copilot-instructions.md'),
+        { path: resolve(projectDir, 'CLAUDE.md') },
+        { path: resolve(projectDir, 'AGENTS.md') },
+        { path: resolve(projectDir, '.github', 'copilot-instructions.md') },
+        { path: resolve(projectDir, '.cursor', 'rules', 'cachly.mdc'), prefix: CURSOR_MDC_FRONTMATTER },
+        { path: resolve(projectDir, '.windsurfrules') },
+        { path: resolve(projectDir, '.clinerules') },
     ];
     const block = '\n' + buildClaudeMdBlock(instanceId) + '\n';
     const results = {};
-    for (const file of files) {
+    for (const { path: file, prefix } of files) {
         await mkdir(dirname(file), { recursive: true });
         if (existsSync(file)) {
             const existing = await readFile(file, 'utf-8');
             if (existing.includes(CLAUDE_MD_MARKER_START)) {
-                // Idempotent update: replace existing block
-                const updated = existing.replace(new RegExp(`${CLAUDE_MD_MARKER_START}[\s\S]*?${CLAUDE_MD_MARKER_END}`), buildClaudeMdBlock(instanceId));
+                // Idempotent update: replace existing block ([\s\S] must keep its
+                // backslashes so it matches any char — a bare [\s\S] in the template
+                // literal collapses to [sS] and the replace silently no-ops).
+                const updated = existing.replace(new RegExp(`${CLAUDE_MD_MARKER_START}[\\s\\S]*?${CLAUDE_MD_MARKER_END}`), buildClaudeMdBlock(instanceId));
                 await writeFile(file, updated, 'utf-8');
                 results[file] = 'updated';
                 continue;
@@ -1500,7 +1549,7 @@ export async function writeInstructions(projectDir, instanceId) {
             results[file] = 'appended';
             continue;
         }
-        await writeFile(file, block.trimStart(), 'utf-8');
+        await writeFile(file, (prefix ?? '') + block.trimStart(), 'utf-8');
         results[file] = 'written';
     }
     return results;
@@ -2408,6 +2457,22 @@ if (process.argv[2] === 'init') {
             console.log(`✓  CLS hook already current in .git/hooks/post-commit`);
     }
     catch { /* non-critical — git hook is a best-effort feature */ }
+    // ── Ambient Recall Phase 4: auto-install SessionStart + UserPromptSubmit hooks ─
+    // Only for Claude Code (the hooks config lives in .claude/settings.json).
+    if (editor === 'claude') {
+        try {
+            const a = await installAmbientHooks(projectDir, instanceId, JWT || undefined);
+            const scriptVerb = a.scripts === 'written' ? '✅ Written' : a.scripts === 'upgraded' ? `✅ Upgraded (→ ${AMBIENT_HOOK_VERSION})` : '✓  Unchanged';
+            console.log(`${scriptVerb}: .claude/hooks/ (Ambient Recall — session briefing, per-prompt recall, file briefing, auto-learn)`);
+            if (a.settings === 'written')
+                console.log(`✅ Written: .claude/settings.json (Ambient Recall hooks wired)`);
+            else if (a.settings === 'merged')
+                console.log(`✅ Merged: .claude/settings.json (Ambient Recall hooks wired)`);
+            else
+                console.log(`✓  Ambient Recall hooks already wired in .claude/settings.json`);
+        }
+        catch { /* non-critical — ambient hooks are a best-effort feature */ }
+    }
     const initSecs = ((Date.now() - initStart) / 1000).toFixed(1);
     console.log(`\n🧠 Cachly AI Brain configured for ${editor === 'claude' ? 'Claude Code' : editor}! (${initSecs}s)`);
     console.log(`   Restart your editor — the \`cachly\` MCP tools will appear.`);
@@ -3395,6 +3460,138 @@ if (process.argv[2] === 'learn-git') {
     }
     process.exit(0);
 }
+// ── ambient-recall: CLI entrypoint for the Claude Code hooks ──────────────────
+// Invoked as: <hook payload JSON on stdin> | cachly ambient-recall
+// SessionStart/UserPromptSubmit/PreToolUse payloads recall through the §6.3
+// relevance gate (ambient-cli.ts) and print the `hookSpecificOutput` JSON that
+// Claude Code injects as additionalContext — or nothing. Stop payloads instead
+// feed a fix-signal observation to auto_learn_session (the automatic
+// `learn_from_attempts`). Injections are booked into the net-token ledger
+// (§6.2) and auto-backoff kicks in when the recent window is net-negative.
+// Best-effort: no JWT, no stdin, a slow brain or any error → prints nothing and
+// exits 0 so a hook can NEVER block or corrupt the agent's turn.
+if (process.argv[2] === 'ambient-recall') {
+    try {
+        if (process.stdin.isTTY)
+            process.exit(0); // no piped payload → nothing to do
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        const raw = Buffer.concat(chunks).toString('utf-8');
+        if (!JWT)
+            process.exit(0); // not authenticated → silent no-op
+        const instanceId = process.env.CACHLY_BRAIN_INSTANCE_ID ?? _defaultInstanceId;
+        // Stop event → auto-learn, never inject (roadmap §6.1 PostToolUse/Stop row).
+        const stopPayload = parseHookPayload(raw);
+        if (stopPayload?.hook_event_name === 'Stop') {
+            const obs = stopObservation(stopPayload);
+            if (obs && instanceId) {
+                await handleTool('auto_learn_session', { instance_id: instanceId, observations: [obs] });
+            }
+            process.exit(0);
+        }
+        let reported;
+        const out = await runAmbient(raw, {
+            timeoutMs: 3000, // §6.3 guardrail 4: never stall the prompt on a slow brain
+            // Ambient injection budget: one relevance-ranked briefing, hard-capped.
+            // smart_recall already returns its hits best-first, so the capped head is
+            // the high-signal part. Per-lesson structured candidates are a future slice.
+            gate: { topK: 1, maxTokens: 500 },
+            backoff: async () => shouldBackoff(await readLedger()),
+            onInject: (tokens, event) => {
+                const entry = { ts: new Date().toISOString(), event, injected: tokens, prevented: 0 };
+                void appendLedgerEntry(entry);
+                reported = reportAmbientLedgerEvent(instanceId, entry); // org dashboard mirror
+            },
+            recall: async (query) => {
+                if (!instanceId)
+                    return [];
+                const text = String((await handleTool('smart_recall', { instance_id: instanceId, query })) ?? '');
+                const miss = text.length < 80 || /No lessons found|no lessons|No matches found/i.test(text);
+                if (miss)
+                    return [];
+                return [{ id: 'ambient', summary: truncateToTokens(text, 500), confidence: 0.9, score: 0.9 }];
+            },
+        });
+        if (out)
+            process.stdout.write(out);
+        // Bounded flush so the dashboard mirror survives process.exit — never more
+        // than 500ms on top of a turn that already injected.
+        if (reported)
+            await Promise.race([reported, new Promise((r) => setTimeout(r, 500))]);
+    }
+    catch {
+        // Swallow everything — an ambient hook must never break the agent.
+    }
+    process.exit(0);
+}
+// ── ambient-credit: agent-reported prevented-token credit (§6.2) ──────────────
+// Invoked as: cachly ambient-credit <tokens> [note…] — the injected context's
+// footer invites the agent to call this when a recalled lesson changed its path.
+// This is the client-side signal that makes the net ledger (and auto-backoff)
+// meaningful before the server-side dashboard exists. Silent + exit 0 always.
+if (process.argv[2] === 'ambient-credit') {
+    try {
+        const tokens = Math.round(Number(process.argv[3]));
+        if (Number.isFinite(tokens) && tokens > 0) {
+            // Cap a single credit: self-reported savings should never let one
+            // enthusiastic claim mask weeks of negative balance.
+            const capped = Math.min(tokens, 20_000);
+            const note = process.argv.slice(4).join(' ').slice(0, 200) || undefined;
+            const entry = { ts: new Date().toISOString(), event: 'credit', injected: 0, prevented: capped, note };
+            await appendLedgerEntry(entry);
+            await reportAmbientLedgerEvent(process.env.CACHLY_BRAIN_INSTANCE_ID ?? _defaultInstanceId, entry); // org dashboard mirror
+            console.log(`✅ ambient credit recorded: ${capped} tokens${note ? ` (${note})` : ''}`);
+        }
+        else {
+            console.error('Usage: npx @cachly-dev/mcp-server@latest ambient-credit <tokens-saved> [note]');
+        }
+    }
+    catch { /* telemetry — never fail loudly */ }
+    process.exit(0);
+}
+// ── ambient-stats: the honest net-token readout (§6.2) ────────────────────────
+// Shows injected vs prevented and the NET — even when it is negative — plus
+// whether auto-backoff is currently pausing injection.
+if (process.argv[2] === 'ambient-stats') {
+    const entries = await readLedger();
+    const bal = netBalance(entries);
+    const backing = shouldBackoff(entries);
+    const recent = entries.slice(-5);
+    console.log('\n🧠 Ambient Recall — net-token ledger\n');
+    console.log(`   Turns recorded:   ${entries.length}`);
+    console.log(`   Injected tokens:  ${bal.injected}`);
+    console.log(`   Prevented tokens: ${bal.prevented} (agent-reported via ambient-credit)`);
+    console.log(`   NET:              ${bal.net >= 0 ? '+' : ''}${bal.net} tokens`);
+    console.log(`   Auto-backoff:     ${backing ? '🔴 ACTIVE — recent window is net-negative, injection paused' : '🟢 inactive'}`);
+    if (recent.length > 0) {
+        console.log('\n   Last entries:');
+        for (const e of recent) {
+            const what = e.prevented > 0 ? `+${e.prevented} prevented` : `-${e.injected} injected`;
+            console.log(`   • ${e.ts.slice(0, 19)} ${e.event}: ${what}${e.note ? ` (${e.note})` : ''}`);
+        }
+    }
+    console.log('');
+    process.exit(0);
+}
+// ── doctor: one-command setup diagnosis ───────────────────────────────────────
+// Walks the whole activation chain — runtime → credential → API → auth →
+// instance → hooks → ledger — and prints one ✅/⚠️/❌ report with a concrete
+// next step per finding. Exit 1 only on hard failures (warnings stay 0).
+if (process.argv[2] === 'doctor') {
+    const { checkNodeVersion, checkCredential, checkApiReachable, checkAuthAccepted, checkInstance, inspectAmbientHooks, checkHooks, checkLedger, renderDoctorReport, doctorExitCode, } = await import('./doctor.js');
+    const checks = [
+        checkNodeVersion(),
+        checkCredential(JWT),
+        await checkApiReachable(API_URL),
+        await checkAuthAccepted(API_URL, JWT),
+        checkInstance(process.env.CACHLY_BRAIN_INSTANCE_ID ?? _defaultInstanceId),
+        checkHooks(inspectAmbientHooks(process.cwd())),
+        checkLedger(await readLedger(), defaultLedgerPath()),
+    ];
+    console.log(renderDoctorReport(checks));
+    process.exit(doctorExitCode(checks));
+}
 // ── cls-ingest: CLI entrypoint for the git post-commit hook ───────────────────
 // Invoked as: cachly cls-ingest '<json>'  where json = { instance_id, source, payload }.
 // Auth comes from CACHLY_JWT (embedded in the generated hook). This is a silent,
@@ -3468,7 +3665,7 @@ if (!JWT) {
 //   • Editor as an MCP stdio server (non-TTY)  → ONE stderr hint, then KEEP RUNNING
 //     so tools/list works and the first tool call starts the browser sign-in.
 // Skip entirely for CLI subcommands that intentionally run without credentials.
-const _cliNoAuthCommands = ['demo', 'share', 'publish', 'health', 'autosetup', 'setup', 'autopilot', 'init', 'digest', 'invite', 'badge', 'join', 'upgrade', 'bench', 'tool-specs', 'openapi'];
+const _cliNoAuthCommands = ['demo', 'share', 'publish', 'health', 'autosetup', 'setup', 'autopilot', 'init', 'digest', 'invite', 'badge', 'join', 'upgrade', 'bench', 'tool-specs', 'openapi', 'ambient-credit', 'ambient-stats', 'doctor'];
 if (!JWT && !_cliNoAuthCommands.includes(process.argv[2] ?? '')) {
     const runningInTerminal = !process.argv[2] && process.stdout.isTTY === true && _isMain;
     if (runningInTerminal) {