cf-memory-mcp 3.15.0 → 3.17.0

package/bin/cf-memory-mcp.js

@@ -688,7 +688,12 @@ class CFMemoryMCP {
                     result: {
                         protocolVersion: respondVersion,
                         capabilities: {
-                            tools: {}
+                            tools: {},
+                            // Resources capability exposes the resume handoff at
+                            // cfm://resume/current and recent handoffs at
+                            // cfm://resume/recent for clients that prefer the
+                            // resources protocol over tool calls.
+                            resources: {}
                         },
                         serverInfo: {
                             name: 'cf-memory-mcp-simplified',
@@ -726,12 +731,93 @@ class CFMemoryMCP {
                 return;
             }
 
-            // Handle resources/list locally (we have none)
+            // Handle resources/list locally — expose the resume handoff
+            // and recent handoffs as MCP resources for clients that prefer
+            // the resources capability over tool calls.
             if (message.method === 'resources/list') {
+                const meta = this.getRepoMetadata();
+                const repoPath = meta.repo_path || 'unknown';
+                const branch = meta.branch || 'unknown';
+                const resources = [
+                    {
+                        uri: 'cfm://resume/current',
+                        name: 'Current resume handoff',
+                        description: `The most-recent matching handoff for ${repoPath} (branch=${branch}). Returns the same payload as get_context_bootstrap({resume:true}).`,
+                        mimeType: 'application/json',
+                    },
+                    {
+                        uri: 'cfm://resume/recent',
+                        name: 'Recent handoffs (top 5)',
+                        description: `The 5 most-recent handoffs for ${repoPath}, status-ranked (in_progress > completed). Useful for picking a specific session via session_id_hint.`,
+                        mimeType: 'application/json',
+                    },
+                ];
+                const response = {
+                    jsonrpc: '2.0',
+                    id: message.id,
+                    result: { resources },
+                };
+                process.stdout.write(JSON.stringify(response) + '\n');
+                return;
+            }
+
+            // Handle resources/read — serve the resume packet as if the
+            // agent had called get_context_bootstrap({resume:true}). Lets
+            // MCP clients that use the resources capability (instead of
+            // tools) recover prior chat state.
+            if (message.method === 'resources/read') {
+                const uri = message.params?.uri;
+                if (uri === 'cfm://resume/current' || uri === 'cfm://resume/recent') {
+                    try {
+                        const meta = this.getRepoMetadata();
+                        const args = { resume: true };
+                        if (meta.repo_path) args.repo_path = meta.repo_path;
+                        if (meta.branch) args.branch = meta.branch;
+                        const fake = { params: { name: 'retrieve_context', arguments: {} } };
+                        await this.maybeFillProjectId(fake);
+                        if (fake.params.arguments.project_id) args.project_id = fake.params.arguments.project_id;
+                        const bootstrap = await this.makeRequest({
+                            jsonrpc: '2.0',
+                            id: `resource-read-${Date.now()}`,
+                            method: 'tools/call',
+                            params: { name: 'get_context_bootstrap', arguments: args },
+                        });
+                        const text = bootstrap?.result?.content?.[0]?.text || '{}';
+                        // For cfm://resume/recent, surface only the recent_handoffs summaries.
+                        let payload = text;
+                        if (uri === 'cfm://resume/recent') {
+                            try {
+                                const parsed = JSON.parse(text);
+                                payload = JSON.stringify({
+                                    recent_handoffs: parsed.recent_handoffs || [],
+                                }, null, 2);
+                            } catch (_) { /* fall through with raw text */ }
+                        }
+                        const response = {
+                            jsonrpc: '2.0',
+                            id: message.id,
+                            result: { contents: [{ uri, mimeType: 'application/json', text: payload }] },
+                        };
+                        process.stdout.write(JSON.stringify(response) + '\n');
+                        return;
+                    } catch (err) {
+                        const response = {
+                            jsonrpc: '2.0',
+                            id: message.id,
+                            error: { code: -32603, message: `Failed to read ${uri}: ${err && err.message}` },
+                        };
+                        process.stdout.write(JSON.stringify(response) + '\n');
+                        return;
+                    }
+                }
+                // Unknown resource URI
                 const response = {
                     jsonrpc: '2.0',
                     id: message.id,
-                    result: { resources: [] }
+                    error: {
+                        code: -32602,
+                        message: `Unknown resource URI: ${uri}. Supported: cfm://resume/current, cfm://resume/recent`,
+                    },
                 };
                 process.stdout.write(JSON.stringify(response) + '\n');
                 return;
@@ -846,6 +932,7 @@ class CFMemoryMCP {
                 message.params.arguments?.resume) {
                 const cached = this.maybeServePrewarmedResume(message);
                 if (cached) {
+                    this.injectRepoDiffIntoResume(cached);
                     _mcpTrace('RESUME_PREWARM', `served get_context_bootstrap id=${message.id} from cache`);
                     process.stdout.write(JSON.stringify(cached) + '\n');
                     return;
@@ -900,6 +987,16 @@ class CFMemoryMCP {
                 this.cacheImplicitSessionFromResponse(response);
             }
 
+            // Inject bridge-side git diff into resume responses. Lets the
+            // agent see what's changed in the repo since the handoff was
+            // written — files modified, commits added, branch moves —
+            // without having to call git themselves.
+            if (message.method === 'tools/call' &&
+                message.params?.name === 'get_context_bootstrap' &&
+                message.params.arguments?.resume) {
+                this.injectRepoDiffIntoResume(response);
+            }
+
             // Send response to stdout
             process.stdout.write(JSON.stringify(response) + '\n');
 
@@ -2392,18 +2489,128 @@ class CFMemoryMCP {
             // Tool-call counter for auto-checkpoint safety net. Counts all
             // tool/call messages; auto-checkpoint fires every N calls.
             this._toolCallCount = (this._toolCallCount || 0) + 1;
+
+            // Activity timeline: keep the last 15 user-meaningful tool calls
+            // in a ring buffer so synthesized handoffs include a "what was
+            // I doing" trail. Excludes housekeeping (health_check, list_*)
+            // and the internal auto-* calls themselves.
+            const TIMELINE_TOOLS = new Set([
+                'retrieve_context', 'get_file_content', 'get_file_outline',
+                'get_related_code', 'refresh_files', 'refresh_stale',
+                'index_project', 'index_github', 'store_memory',
+                'find_stale_files',
+            ]);
+            if (TIMELINE_TOOLS.has(toolName)) {
+                if (!this._activityTimeline) this._activityTimeline = [];
+                const summary = this.summarizeToolCall(toolName, args);
+                this._activityTimeline.push({ tool: toolName, summary, at: Date.now() });
+                if (this._activityTimeline.length > 15) {
+                    this._activityTimeline.shift();
+                }
+            }
         } catch (err) {
             this.logDebug(`trackToolActivity failed: ${err && err.message}`);
         }
     }
 
+    /**
+     * Mutates a get_context_bootstrap response to attach a `repo_diff`
+     * field describing what's changed in the local repo since the
+     * handoff. Bridge-only — server has no git access. Best-effort, silent
+     * on failure.
+     *
+     * Opt out via CF_MEMORY_RESUME_DIFF=off.
+     */
+    injectRepoDiffIntoResume(response) {
+        try {
+            const opt = process.env.CF_MEMORY_RESUME_DIFF;
+            if (opt === '0' || opt === 'false' || opt === 'off') return;
+            const text = response?.result?.content?.[0]?.text;
+            if (!text) return;
+            let parsed;
+            try { parsed = JSON.parse(text); } catch (_) { return; }
+            const envelope = parsed?.resume_handoff;
+            if (!envelope) return;
+
+            const meta = this.getRepoMetadata();
+            const repoRoot = meta.repo_path;
+            if (!repoRoot) return;
+            // Reference point: prefer ended_at, fall back to started_at.
+            const since = envelope.ended_at || envelope.started_at;
+            if (!since) return;
+
+            const diff = this.computeRepoDiff(repoRoot, since, envelope.handoff?.branch || meta.branch);
+            if (diff) {
+                envelope.repo_diff = diff;
+                // Re-serialize the modified envelope back into the response.
+                response.result.content[0].text = JSON.stringify(parsed);
+            }
+        } catch (err) {
+            this.logDebug(`injectRepoDiffIntoResume failed: ${err && err.message}`);
+        }
+    }
+
+    /**
+     * Run a bounded git query in the repo root to summarize changes since
+     * the handoff was written. Returns { commits, files_changed,
+     * branch_now, branch_at_handoff } or null if git isn't available.
+     */
+    computeRepoDiff(repoRoot, sinceIso, handoffBranch) {
+        try {
+            const { execSync } = require('child_process');
+            const run = (cmd) => execSync(cmd, {
+                cwd: repoRoot,
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+                timeout: 1000,
+            });
+            // Git accepts ISO timestamps via --since
+            const commitsOut = run(`git log --since='${sinceIso}' --pretty=format:'%h %s' -n 25`);
+            const commits = commitsOut.split('\n').filter(Boolean).map(line => {
+                const [hash, ...rest] = line.split(' ');
+                return { hash, subject: rest.join(' ').slice(0, 120) };
+            });
+
+            // Files changed since the handoff. Compare HEAD against the
+            // commit closest to the handoff time. If no commits since,
+            // diff vs. HEAD~0 returns nothing.
+            let filesChanged = [];
+            try {
+                const namesOut = run(`git log --since='${sinceIso}' --name-only --pretty=format:''`);
+                const names = new Set(namesOut.split('\n').map(s => s.trim()).filter(Boolean));
+                filesChanged = Array.from(names).slice(0, 50);
+            } catch (_) { /* empty diff is fine */ }
+
+            // Branch information.
+            let branchNow = null;
+            try {
+                branchNow = run('git symbolic-ref --short HEAD').trim();
+            } catch (_) { /* detached HEAD */ }
+
+            const diff = {
+                commits_since_handoff: commits,
+                files_changed_count: filesChanged.length,
+                files_changed: filesChanged,
+            };
+            if (branchNow) diff.branch_now = branchNow;
+            if (handoffBranch) diff.branch_at_handoff = handoffBranch;
+            if (handoffBranch && branchNow && handoffBranch !== branchNow) {
+                diff.branch_changed = true;
+            }
+            return diff;
+        } catch (err) {
+            this.logDebug(`computeRepoDiff failed: ${err && err.message}`);
+            return null;
+        }
+    }
+
     /**
      * Build a minimal handoff packet from observed bridge activity. Used by
-     * end_session auto-synthesis and the periodic auto-checkpoint. Returns
-     * just the fields the bridge can credibly populate — agent-supplied
-     * fields like decisions/blockers are intentionally omitted so a future
-     * resume reader can tell the difference between "agent wrote this" and
-     * "bridge synthesized this".
+     * end_session auto-synthesis, the periodic auto-checkpoint, and the
+     * SIGINT/SIGTERM safety net. Returns just the fields the bridge can
+     * credibly populate — agent-supplied fields like decisions/blockers
+     * are intentionally omitted so a future resume reader can tell the
+     * difference between "agent wrote this" and "bridge synthesized this".
      */
     synthesizeMinimalHandoff() {
         const handoff = {
@@ -2424,10 +2631,65 @@ class CFMemoryMCP {
         } else {
             handoff.goal = 'Bridge-synthesized handoff (no explicit goal)';
         }
-        handoff.notes = `Auto-synthesized by cf-memory-mcp bridge. Agent did not provide a handoff. Tool calls observed: ${this._toolCallCount || 0}. Set CF_MEMORY_AUTO_HANDOFF=off to disable.`;
+
+        // Activity timeline: last 15 meaningful tool calls, condensed to
+        // a single line each. Goes in handoff.notes so the next chat
+        // sees the recent trajectory ("what was I doing").
+        const timelineNote = this.formatActivityTimeline();
+        const baseNote = `Auto-synthesized by cf-memory-mcp bridge. Agent did not provide a handoff. Tool calls observed: ${this._toolCallCount || 0}. Set CF_MEMORY_AUTO_HANDOFF=off to disable.`;
+        handoff.notes = timelineNote ? `${baseNote}\n\nRecent activity:\n${timelineNote}` : baseNote;
         return handoff;
     }
 
+    /**
+     * Condense an MCP tool call into a single-line summary. Used for the
+     * activity timeline so the synthesized handoff includes "what was I
+     * doing" context. Keeps each line under 120 chars.
+     */
+    summarizeToolCall(toolName, args) {
+        try {
+            const trim = (s, n) => typeof s === 'string' ? s.slice(0, n) : '';
+            switch (toolName) {
+                case 'retrieve_context':
+                    return `retrieve_context: "${trim(args.query, 80)}"`;
+                case 'get_file_content':
+                    return `get_file_content: ${trim(args.file_path, 80)}`;
+                case 'get_file_outline':
+                    return `get_file_outline: ${trim(args.file_path, 80)}`;
+                case 'get_related_code':
+                    return `get_related_code: ${trim(args.chunk_name || args.chunk_id, 80)}`;
+                case 'refresh_files':
+                    return `refresh_files: ${(args.file_paths || []).slice(0, 3).join(', ')}${(args.file_paths || []).length > 3 ? '…' : ''}`;
+                case 'refresh_stale':
+                    return `refresh_stale${args.project_id ? ' '+args.project_id : ''}`;
+                case 'index_project':
+                    return `index_project: ${trim(args.project_path, 80)}`;
+                case 'index_github':
+                    return `index_github: ${trim(args.repo_url, 80)}`;
+                case 'store_memory':
+                    return `store_memory: "${trim(args.content, 80)}"`;
+                case 'find_stale_files':
+                    return `find_stale_files`;
+                default:
+                    return toolName;
+            }
+        } catch (_) {
+            return toolName;
+        }
+    }
+
+    /**
+     * Format the activity timeline as a compact bullet list. Returns ""
+     * when no timeline exists.
+     */
+    formatActivityTimeline() {
+        if (!this._activityTimeline || this._activityTimeline.length === 0) return '';
+        return this._activityTimeline
+            .slice(-10)  // last 10 of the up-to-15 buffer
+            .map(e => `  - ${e.summary}`)
+            .join('\n');
+    }
+
     /**
      * Pre-fetch the resume handoff for the current cwd at bridge startup.
      * The result is cached and surfaced when the agent's first call is
@@ -3061,11 +3323,56 @@ class CFMemoryMCP {
     }
 
     /**
-     * Graceful shutdown
+     * Graceful shutdown. Best-effort: tries to flush a synthesized handoff
+     * to the active implicit session so the resume state survives the
+     * shutdown. Uses keep_open so the session can still be properly closed
+     * later if the agent reconnects. Bounded by a 2s timeout so we never
+     * hang the exit on a slow network round-trip.
+     *
+     * Opt out via CF_MEMORY_SHUTDOWN_HANDOFF=off.
      */
     shutdown(reason = 'UNKNOWN') {
         this.logDebug(`Shutting down (reason: ${reason})`);
-        process.exit(0);
+        const optOut = process.env.CF_MEMORY_SHUTDOWN_HANDOFF;
+        const enabled = !(optOut === '0' || optOut === 'false' || optOut === 'off');
+        if (!enabled) {
+            process.exit(0);
+            return;
+        }
+        // Resolve the implicit session WITHOUT creating a new one — we
+        // don't want to leave an empty session row behind if the agent
+        // never did anything. Only flush when there's tracked activity.
+        const cwd = process.env.CF_MEMORY_WATCH_PATH || process.cwd();
+        const sessionId = this._implicitSessionByCwd?.get(cwd);
+        const hasActivity = this._activityFiles && this._activityFiles.size > 0;
+        if (!sessionId || !hasActivity) {
+            this.logDebug(`shutdown handoff skipped: session=${sessionId||'(none)'} activity=${this._activityFiles?.size||0}`);
+            process.exit(0);
+            return;
+        }
+
+        const handoff = this.synthesizeMinimalHandoff();
+        const meta = this.getRepoMetadata();
+        if (meta.repo_path) handoff.repo_path = meta.repo_path;
+        if (meta.branch) handoff.branch = meta.branch;
+
+        const args = { session_id: sessionId, keep_open: true, handoff };
+        const message = {
+            jsonrpc: '2.0',
+            id: `shutdown-${Date.now()}`,
+            method: 'tools/call',
+            params: { name: 'end_session', arguments: args },
+        };
+        _mcpTrace('SHUTDOWN_HANDOFF', `session=${sessionId} reason=${reason}`);
+
+        // Race the request against a 2s deadline so we never hang exit.
+        const deadline = new Promise(resolve => setTimeout(resolve, 2000));
+        Promise.race([
+            this.makeRequest(message).catch(err => {
+                this.logDebug(`shutdown handoff request failed: ${err && err.message}`);
+            }),
+            deadline,
+        ]).finally(() => process.exit(0));
     }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cf-memory-mcp",
-	"version": "3.15.0",
+	"version": "3.17.0",
 	"description": "Cloudflare-hosted MCP server for code indexing, retrieval, and assistant memory with a direct remote MCP endpoint and local stdio bridge.",
 	"main": "bin/cf-memory-mcp.js",
 	"bin": {