@everstateai/mcp 1.3.12 → 1.3.13

package/src/index.ts

@@ -101,6 +101,24 @@ async function runMcpServer() {
   // Session state - persists projectId across tool calls within this proxy instance
   let sessionProjectId = INITIAL_PROJECT_ID;
 
+  // Auto-session state: track last tool call time and whether sync has been called
+  let lastToolCallTime = 0;
+  let sessionSynced = false;
+  const AUTO_SYNC_IDLE_MS = 5 * 60 * 1000; // 5 minutes
+
+  // Context window tracking
+  // Claude's context window is ~200K tokens (~800K chars).
+  // We track cumulative MCP response sizes as a proxy for context growth.
+  // MCP responses are typically the largest context consumers since user messages
+  // and Claude's own output are smaller relative to tool results.
+  const CONTEXT_WINDOW_CHARS = 800_000; // ~200K tokens * 4 chars/token
+  const CONTEXT_WARNING_THRESHOLD = 0.75; // 75%
+  const CONTEXT_CRITICAL_THRESHOLD = 0.90; // 90%
+  let cumulativeResponseChars = 0;
+  let toolCallCount = 0;
+  let contextWarningIssued = false;
+  let contextCriticalIssued = false;
+
   if (!API_KEY) {
     console.error("EVERSTATE_API_KEY environment variable is required");
     console.error("");
@@ -173,6 +191,261 @@ async function runMcpServer() {
     }
   }
 
+  // ============ BATCH SYNC ============
+  // Buffer write operations locally and flush on a configurable interval
+  // to reduce API calls. Enabled via .everstate.json: { "batchSync": { "enabled": true, "intervalSeconds": 30 } }
+
+  interface BatchSyncConfig {
+    enabled: boolean;
+    intervalSeconds: number;
+  }
+
+  interface BufferEntry {
+    id: string;
+    queuedAt: string;
+    toolName: string;
+    arguments: Record<string, unknown>;
+    retryCount: number;
+  }
+
+  interface BatchBuffer {
+    version: number;
+    lastFlushAt: string | null;
+    lastFlushResult: { success: number; failed: number } | null;
+    entries: BufferEntry[];
+    failed: BufferEntry[];
+  }
+
+  function readBatchConfig(): BatchSyncConfig {
+    let dir = process.cwd();
+    const root = path.parse(dir).root;
+    while (dir !== root) {
+      const configPath = path.join(dir, ".everstate.json");
+      if (fs.existsSync(configPath)) {
+        try {
+          const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+          if (config.batchSync) {
+            const interval = config.batchSync.intervalSeconds ?? 30;
+            const MAX_INTERVAL = 300; // 5 minutes max — prevents stale data loss on crash
+            return {
+              enabled: config.batchSync.enabled ?? false,
+              intervalSeconds: Math.min(Math.max(interval, 5), MAX_INTERVAL),
+            };
+          }
+        } catch { /* continue */ }
+      }
+      dir = path.dirname(dir);
+    }
+    return { enabled: false, intervalSeconds: 30 };
+  }
+
+  const batchConfig = readBatchConfig();
+  const BUFFER_DIR = path.join(process.cwd(), ".claude");
+  const BUFFER_PATH = path.join(BUFFER_DIR, ".batch-buffer.json");
+  const MAX_RETRIES = 3;
+  const MAX_BUFFER_SIZE = 200;
+  const BUFFER_STALE_MS = 60 * 60 * 1000; // 1 hour
+
+  function emptyBuffer(): BatchBuffer {
+    return { version: 1, lastFlushAt: null, lastFlushResult: null, entries: [], failed: [] };
+  }
+
+  function readBuffer(): BatchBuffer {
+    try {
+      if (fs.existsSync(BUFFER_PATH)) {
+        const buf = JSON.parse(fs.readFileSync(BUFFER_PATH, "utf8")) as BatchBuffer;
+        // Discard stale entries on startup
+        const cutoff = Date.now() - BUFFER_STALE_MS;
+        buf.entries = buf.entries.filter(e => new Date(e.queuedAt).getTime() > cutoff);
+        buf.failed = (buf.failed || []).slice(-50);
+        return buf;
+      }
+    } catch { /* corrupted file, start fresh */ }
+    return emptyBuffer();
+  }
+
+  function writeBuffer(buffer: BatchBuffer): void {
+    try {
+      if (!fs.existsSync(BUFFER_DIR)) fs.mkdirSync(BUFFER_DIR, { recursive: true });
+      const tmpPath = BUFFER_PATH + ".tmp";
+      fs.writeFileSync(tmpPath, JSON.stringify(buffer, null, 2));
+      fs.renameSync(tmpPath, BUFFER_PATH);
+    } catch (err) {
+      console.error("[Everstate] Failed to write buffer:", err);
+    }
+  }
+
+  function addToBuffer(toolName: string, args: Record<string, unknown>): void {
+    const buffer = readBuffer();
+    if (buffer.entries.length >= MAX_BUFFER_SIZE) {
+      // Drop oldest entries
+      const dropped = buffer.entries.splice(0, buffer.entries.length - MAX_BUFFER_SIZE + 1);
+      console.error(`[Everstate] Buffer full, dropped ${dropped.length} oldest entries`);
+    }
+    buffer.entries.push({
+      id: `buf_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
+      queuedAt: new Date().toISOString(),
+      toolName,
+      arguments: args,
+      retryCount: 0,
+    });
+    writeBuffer(buffer);
+  }
+
+  // Tools that MUST execute immediately (return data the agent needs)
+  const IMMEDIATE_TOOLS = new Set([
+    "sync", "done", "recall", "status",
+    "ask_user", "check_user_response",
+    "everstate_list_projects", "everstate_switch_project", "everstate_current_project",
+    "list_projects", "switch_project", "current_project",
+  ]);
+
+  // Meta-tool action prefixes that must execute immediately (reads/interactive)
+  const IMMEDIATE_META_PREFIXES = [
+    "help", "session.", "search.", "context.", "heal.", "quality.",
+    "google.", "inbound.", "files.", "git.", "team.",
+    "work.get_", "work.list_", "work.search_", "work.get_portfolio",
+    "decisions.list", "decisions.get",
+    "gotchas.list", "gotchas.get",
+    "admin.get_", "admin.list_", "admin.check_", "admin.validate_", "admin.export_",
+    "project.", "progress.list", "progress.get",
+  ];
+
+  function isBatchable(toolName: string, args: Record<string, unknown>): boolean {
+    if (IMMEDIATE_TOOLS.has(toolName)) return false;
+    if (toolName === "everstate") {
+      const action = (args.action as string) || "";
+      for (const prefix of IMMEDIATE_META_PREFIXES) {
+        if (action === prefix || action.startsWith(prefix)) return false;
+      }
+      return true;
+    }
+    // Core tools: log is batchable, everything else is immediate by default
+    if (toolName === "log") return true;
+    return false;
+  }
+
+  function generateSyntheticResponse(toolName: string, args: Record<string, unknown>): string {
+    if (toolName === "log") {
+      const msg = (args.message as string) || "";
+      const type = (args.type as string) || "progress";
+      const labels: Record<string, string> = {
+        achievement: "Achievement logged",
+        progress: "Progress recorded",
+        note: "Note saved",
+        warning: "Warning recorded",
+      };
+      return `${labels[type] || "Logged"} (queued for sync): ${msg.substring(0, 120)}${msg.length > 120 ? "..." : ""}`;
+    }
+    if (toolName === "everstate") {
+      const action = (args.action as string) || "";
+      return `Queued for sync: ${action}`;
+    }
+    return `Queued for sync: ${toolName}`;
+  }
+
+  async function flushBuffer(): Promise<void> {
+    const buffer = readBuffer();
+    if (buffer.entries.length === 0) return;
+
+    const count = buffer.entries.length;
+    console.error(`[Everstate] Flushing ${count} buffered items...`);
+
+    let success = 0;
+    let failed = 0;
+    const remaining: BufferEntry[] = [];
+    const failedEntries: BufferEntry[] = [...(buffer.failed || [])];
+
+    // Try batch endpoint first
+    try {
+      const res = await fetch(`${API_BASE}/mcp/batch-execute`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${API_KEY}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          calls: buffer.entries.map(e => ({
+            name: e.toolName,
+            arguments: e.arguments,
+          })),
+        }),
+      });
+
+      if (res.ok) {
+        success = count;
+      } else if (res.status === 404) {
+        // Batch endpoint not deployed yet — fall back to individual calls
+        for (const entry of buffer.entries) {
+          try {
+            const r = await fetch(`${API_BASE}/mcp/execute`, {
+              method: "POST",
+              headers: {
+                Authorization: `Bearer ${API_KEY}`,
+                "Content-Type": "application/json",
+              },
+              body: JSON.stringify({
+                name: entry.toolName,
+                arguments: entry.arguments,
+              }),
+            });
+            if (r.ok) {
+              success++;
+            } else {
+              entry.retryCount++;
+              if (entry.retryCount >= MAX_RETRIES) {
+                failedEntries.push(entry);
+                failed++;
+              } else {
+                remaining.push(entry);
+              }
+            }
+          } catch {
+            entry.retryCount++;
+            if (entry.retryCount >= MAX_RETRIES) {
+              failedEntries.push(entry);
+              failed++;
+            } else {
+              remaining.push(entry);
+            }
+          }
+        }
+      } else {
+        // Server error — keep all entries for retry
+        for (const entry of buffer.entries) {
+          entry.retryCount++;
+          if (entry.retryCount >= MAX_RETRIES) {
+            failedEntries.push(entry);
+            failed++;
+          } else {
+            remaining.push(entry);
+          }
+        }
+      }
+    } catch {
+      // Network error — keep all entries for retry
+      for (const entry of buffer.entries) {
+        entry.retryCount++;
+        if (entry.retryCount >= MAX_RETRIES) {
+          failedEntries.push(entry);
+          failed++;
+        } else {
+          remaining.push(entry);
+        }
+      }
+    }
+
+    buffer.entries = remaining;
+    buffer.failed = failedEntries.slice(-50);
+    buffer.lastFlushAt = new Date().toISOString();
+    buffer.lastFlushResult = { success, failed };
+    writeBuffer(buffer);
+
+    if (success > 0 || failed > 0) {
+      console.error(`[Everstate] Flush: ${success} sent, ${failed} failed, ${remaining.length} retrying`);
+    }
+  }
+
   // Type for API responses
   interface ToolsResponse {
     tools: Array<{
@@ -223,6 +496,59 @@ async function runMcpServer() {
       enrichedArgs.projectId = sessionProjectId;
     }
 
+    // Auto-session: trigger sync if this is the first tool call or idle > 5 minutes
+    const now = Date.now();
+    const isIdle = lastToolCallTime > 0 && (now - lastToolCallTime) > AUTO_SYNC_IDLE_MS;
+    const needsSync = !sessionSynced || isIdle;
+    const isSyncCall = name === "sync" || name === "done";
+
+    // Flush buffer before auto-sync (idle means buffered items are sitting stale)
+    if (needsSync && isIdle && batchConfig.enabled) {
+      await flushBuffer();
+    }
+
+    if (needsSync && !isSyncCall && sessionProjectId) {
+      try {
+        console.error(`[Everstate] Auto-sync: ${!sessionSynced ? 'first tool call' : 'idle > 5min'}`);
+        await fetch(`${API_BASE}/mcp/execute`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${API_KEY}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            name: "sync",
+            arguments: { projectId: sessionProjectId, mode: "minimal" },
+          }),
+        });
+        sessionSynced = true;
+      } catch {
+        // Non-critical: don't block tool call if auto-sync fails
+        console.error("[Everstate] Auto-sync failed, continuing...");
+      }
+    }
+
+    if (isSyncCall) {
+      sessionSynced = true;
+    }
+    lastToolCallTime = now;
+
+    // Force-flush buffer before done() so session summary reflects all progress
+    if (name === "done" && batchConfig.enabled) {
+      await flushBuffer();
+    }
+
+    // Batch sync: buffer batchable write operations instead of calling API immediately
+    if (batchConfig.enabled && isBatchable(name, enrichedArgs)) {
+      const syntheticResponse = generateSyntheticResponse(name, enrichedArgs);
+      addToBuffer(name, enrichedArgs);
+      const bufSize = readBuffer().entries.length;
+      console.error(`[Everstate] Batched: ${name} (buffer: ${bufSize} items)`);
+      return {
+        content: [{ type: "text" as const, text: syntheticResponse }],
+      };
+    }
+
     const res = await fetch(`${API_BASE}/mcp/execute`, {
       method: "POST",
       headers: {
@@ -233,8 +559,17 @@ async function runMcpServer() {
     });
 
     if (!res.ok) {
+      // Read the response body for the actual error message
+      let errorDetail = `${res.status} ${res.statusText}`;
+      try {
+        const errorBody = await res.json() as { content?: Array<{ text?: string }> };
+        const msg = errorBody?.content?.[0]?.text;
+        if (msg) errorDetail = msg;
+      } catch {
+        // Body not JSON, use status text
+      }
       return {
-        content: [{ type: "text" as const, text: `API error: ${res.status} ${res.statusText}` }],
+        content: [{ type: "text" as const, text: errorDetail }],
         isError: true,
       };
     }
@@ -245,6 +580,71 @@ async function runMcpServer() {
       project?: { id?: string };
     };
 
+    // Track context growth from MCP responses
+    toolCallCount++;
+    const responseText = result.content?.map((c: { text?: string }) => c.text || '').join('') || '';
+    cumulativeResponseChars += responseText.length;
+
+    // Also count the request args as they're in context too
+    const requestChars = JSON.stringify(enrichedArgs).length;
+    cumulativeResponseChars += requestChars;
+
+    const contextUsage = cumulativeResponseChars / CONTEXT_WINDOW_CHARS;
+    const contextPercent = Math.round(contextUsage * 100);
+
+    // Force-flush buffer when context is running low — session may end abruptly
+    if (contextUsage >= CONTEXT_WARNING_THRESHOLD && batchConfig.enabled) {
+      flushBuffer().catch(() => {}); // Non-blocking
+    }
+
+    // Append context warning to tool response
+    if (contextUsage >= CONTEXT_CRITICAL_THRESHOLD && !contextCriticalIssued) {
+      contextCriticalIssued = true;
+      const warning = `\n\n---\n` +
+        `**CONTEXT CRITICAL (${contextPercent}% estimated usage)**\n\n` +
+        `This session's context window is nearly full. You should:\n` +
+        `1. Call \`done\` with a detailed summary and next steps\n` +
+        `2. Tell the user to start a new session — Everstate will restore context automatically\n\n` +
+        `Continuing will lead to context compaction which loses conversation detail.\n` +
+        `---`;
+      if (result.content?.[0]?.text) {
+        result.content[0].text += warning;
+      }
+    } else if (contextUsage >= CONTEXT_WARNING_THRESHOLD && !contextWarningIssued) {
+      contextWarningIssued = true;
+      const warning = `\n\n---\n` +
+        `**CONTEXT WARNING (${contextPercent}% estimated usage)**\n\n` +
+        `This session is consuming context quickly (~${toolCallCount} tool calls, ~${Math.round(cumulativeResponseChars / 4000)}K tokens estimated).\n` +
+        `Consider wrapping up soon. When ready:\n` +
+        `1. Call \`done\` with a summary of what was accomplished and what's next\n` +
+        `2. Suggest the user start a new session — Everstate will pick up where you left off\n` +
+        `---`;
+      if (result.content?.[0]?.text) {
+        result.content[0].text += warning;
+      }
+
+      // Log the warning to Everstate for analytics
+      try {
+        await fetch(`${API_BASE}/mcp/execute`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${API_KEY}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            name: "log",
+            arguments: {
+              projectId: sessionProjectId,
+              type: "warning",
+              message: `Context window at ${contextPercent}% estimated usage after ${toolCallCount} tool calls (~${Math.round(cumulativeResponseChars / 4)} tokens in MCP responses)`,
+            },
+          }),
+        });
+      } catch {
+        // Non-critical
+      }
+    }
+
     // Update session state based on tool results
     if (name === "switch_project" || name === "everstate_switch_project") {
       const data = result.data || result.project;
@@ -260,19 +660,51 @@ async function runMcpServer() {
     // For sync calls, check for npm package updates and prepend notice
     if (name === "sync" && result.content?.[0]?.text) {
       try {
-        const latestVersion = await checkNpmVersion();
-        if (latestVersion) {
+        const versionInfo = await checkNpmVersion();
+        if (versionInfo) {
           const { getMcpProxyVersion: getVersion } = await import("./setup/version.js");
           const currentVersion = getVersion();
-          if (currentVersion !== "0.0.0" && latestVersion !== currentVersion && compareVersionStrings(currentVersion, latestVersion) < 0) {
-            const updateNotice = `> **Update available:** @everstateai/mcp ${currentVersion} → ${latestVersion}\n` +
-              `> Run \`npx @everstateai/mcp update-all\` to update.\n\n`;
+          if (currentVersion !== "0.0.0" && versionInfo.version !== currentVersion && compareVersionStrings(currentVersion, versionInfo.version) < 0) {
+            // Build update notice with optional changelog
+            let updateNotice = `> **Update available:** @everstateai/mcp ${currentVersion} → ${versionInfo.version}\n`;
+            if (versionInfo.changelog) {
+              updateNotice += `> _What's new: ${versionInfo.changelog}_\n`;
+            }
+            updateNotice += `> Auto-updating in background... (disable with \`everstate({ action: "admin.settings", params: { autoUpdate: false } })\`)\n\n`;
             result.content[0].text = updateNotice + result.content[0].text;
+
+            // Trigger auto-update in background (non-blocking)
+            autoUpdateNpmPackage(versionInfo.version).catch(() => {});
           }
         }
       } catch {
         // Non-critical, continue without update notice
       }
+
+      // Check for MEMORY.md coexistence and add note if found
+      try {
+        const fs = await import('fs');
+        const path = await import('path');
+        const projectDir = process.cwd();
+        const memoryPaths = [
+          path.join(projectDir, 'MEMORY.md'),
+          path.join(projectDir, '.claude', 'MEMORY.md'),
+        ];
+        const hasMemoryMd = memoryPaths.some(p => fs.existsSync(p));
+        if (hasMemoryMd && result.content?.[0]?.text) {
+          const memoryNote = `> **Note:** MEMORY.md detected. MEMORY.md = your personal notes (local). Everstate = shared project memory (cloud, cross-tool). They complement each other.\n\n`;
+          // Insert after any update notice but before the main content
+          const text = result.content[0].text;
+          const headerMatch = text.match(/^(# Everstate Session Sync\n\n)/);
+          if (headerMatch) {
+            result.content[0].text = headerMatch[1] + memoryNote + text.slice(headerMatch[1].length);
+          } else {
+            result.content[0].text = memoryNote + text;
+          }
+        }
+      } catch {
+        // Non-critical
+      }
     }
 
     return result;
@@ -291,17 +723,34 @@ async function runMcpServer() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error("Everstate MCP Proxy connected to", API_BASE);
+
+  // Start batch sync flush timer if enabled
+  if (batchConfig.enabled) {
+    console.error(`[Everstate] Batch sync: ON (flush every ${batchConfig.intervalSeconds}s)`);
+    setInterval(async () => {
+      try {
+        await flushBuffer();
+      } catch (err) {
+        console.error("[Everstate] Flush error:", err);
+      }
+    }, batchConfig.intervalSeconds * 1000);
+  }
 }
 
 // Cache npm version check (once per MCP server lifetime, max every 4 hours)
-let cachedLatestVersion: string | null = null;
+interface NpmVersionInfo {
+  version: string;
+  changelog?: string;
+}
+let cachedVersionInfo: NpmVersionInfo | null = null;
 let lastNpmCheck = 0;
 const NPM_CHECK_INTERVAL = 4 * 60 * 60 * 1000; // 4 hours
+let autoUpdateInProgress = false;
 
-async function checkNpmVersion(): Promise<string | null> {
+async function checkNpmVersion(): Promise<NpmVersionInfo | null> {
   const now = Date.now();
-  if (cachedLatestVersion && now - lastNpmCheck < NPM_CHECK_INTERVAL) {
-    return cachedLatestVersion;
+  if (cachedVersionInfo && now - lastNpmCheck < NPM_CHECK_INTERVAL) {
+    return cachedVersionInfo;
   }
 
   try {
@@ -314,11 +763,11 @@ async function checkNpmVersion(): Promise<string | null> {
     clearTimeout(timeout);
 
     if (res.ok) {
-      const data = (await res.json()) as { version?: string };
+      const data = (await res.json()) as { version?: string; changelog?: string };
       if (data.version) {
-        cachedLatestVersion = data.version;
+        cachedVersionInfo = { version: data.version, changelog: data.changelog };
         lastNpmCheck = now;
-        return data.version;
+        return cachedVersionInfo;
       }
     }
   } catch {
@@ -327,6 +776,47 @@ async function checkNpmVersion(): Promise<string | null> {
   return null;
 }
 
+/**
+ * Auto-update the npm package if enabled and a new version is available.
+ * This runs in the background and doesn't block tool calls.
+ */
+async function autoUpdateNpmPackage(latestVersion: string): Promise<void> {
+  if (autoUpdateInProgress) return;
+
+  // Check if auto-update is disabled
+  const fs = await import('fs');
+  const path = await import('path');
+  const settingsPath = path.join(process.env.HOME || '', '.everstate', 'settings.json');
+
+  try {
+    if (fs.existsSync(settingsPath)) {
+      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      if (settings.autoUpdate === false) {
+        return; // User has disabled auto-updates
+      }
+    }
+  } catch {
+    // If we can't read settings, proceed with auto-update
+  }
+
+  autoUpdateInProgress = true;
+  console.error(`[Everstate] Auto-updating to v${latestVersion}...`);
+
+  try {
+    const { execSync } = await import('child_process');
+    // Use npm to update the package globally or locally depending on how it's installed
+    execSync('npm install -g @everstateai/mcp@latest', {
+      stdio: 'pipe',
+      timeout: 60000, // 1 minute timeout
+    });
+    console.error(`[Everstate] Successfully updated to v${latestVersion}. Restart your AI tool to use the new version.`);
+  } catch (error) {
+    console.error(`[Everstate] Auto-update failed: ${String(error)}. Run 'npx @everstateai/mcp update-all' manually.`);
+  } finally {
+    autoUpdateInProgress = false;
+  }
+}
+
 function compareVersionStrings(a: string, b: string): number {
   const aParts = a.split(".").map(Number);
   const bParts = b.split(".").map(Number);