@abraca/mcp 2.15.0 → 2.17.0

package/dist/index.d.ts

@@ -31,6 +31,7 @@ declare class AbracadabraMCPServer {
   private _spaceConnections;
   private childCache;
   private evictionTimer;
+  private heartbeatTimer;
   private _mcpServerRef;
   private _serverRef;
   private _handledTaskIds;
@@ -117,6 +118,15 @@ declare class AbracadabraMCPServer {
    *  the live `connectionStatus` getter. */
   private _wsConnected;
   ensureConnected(): Promise<void>;
+  /**
+   * Bring one provider's socket back to a synced state WITHOUT swapping its
+   * Y.Doc. First let the SDK's own auto-reconnect finish if it's mid-flight;
+   * if the socket is still dead, force a reconnect on the same doc. Because the
+   * document is never replaced, every observer attached to it (root awareness,
+   * tree reads, the inbox `entries` array, the stateless chat listener) keeps
+   * firing — no re-attach needed. Best-effort: logs but never throws.
+   */
+  private _healProvider;
   ensureSpaceActive(targetId: string | null | undefined): Promise<boolean>;
   /** Get the root doc-tree Y.Map of the active space. */
   getTreeMap(): Y.Map<any> | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/mcp",
-  "version": "2.15.0",
+  "version": "2.17.0",
   "description": "MCP server for Abracadabra — AI agent collaboration on CRDT documents",
   "license": "MIT",
   "type": "module",
@@ -36,7 +36,7 @@
     "y-protocols": "^1.0.6",
     "yjs": "^13.6.8",
     "zod": "^4.3.6",
-    "@abraca/convert": "2.15.0"
+    "@abraca/convert": "2.17.0"
   },
   "scripts": {
     "test": "node --no-warnings --conditions=source --experimental-transform-types --test 'tests/*.test.ts'"

package/src/server.ts

@@ -67,6 +67,7 @@ export class AbracadabraMCPServer {
 	private _spaceConnections = new Map<string, SpaceConnection>();
 	private childCache = new Map<string, CachedProvider>();
 	private evictionTimer: ReturnType<typeof setInterval> | null = null;
+	private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
 	private _mcpServerRef: McpServer | null = null;
 	private _serverRef: Server | null = null;
 	private _handledTaskIds = new Set<string>();
@@ -243,6 +244,15 @@ export class AbracadabraMCPServer {
 
 		// Step 6: Start eviction timer
 		this.evictionTimer = setInterval(() => this.evictIdle(), 60_000);
+
+		// Step 7: Connection heartbeat. An idle MCP (no tool calls for a while)
+		// would otherwise let an expired JWT drop the socket with nothing to heal
+		// it — silently killing chat/awareness + inbox dispatch. `ensureConnected`
+		// is a no-op while healthy (just refreshes a near-expiry token) and
+		// reconnects on the SAME docs (space + inbox) if dead, so observers survive.
+		this.heartbeatTimer = setInterval(() => {
+			void this.ensureConnected();
+		}, 30_000);
 	}
 
 	/** Connect to a space's root doc and cache it. Sets it as the active connection. */
@@ -357,8 +367,10 @@ export class AbracadabraMCPServer {
 		if (this._reconnecting) return this._reconnecting;
 		this._reconnecting = (async () => {
 			try {
-				// 1) Refresh the JWT proactively so a reconnect doesn't retry with a
-				//    stale token (which the server rejects, stopping the WS retry loop).
+				// 1) Refresh the JWT proactively so any reconnect re-authenticates
+				//    with a fresh token (a stale one is rejected, which stops the WS
+				//    retry loop). The provider's `token` callback reads `client.token`,
+				//    so refreshing it here is enough for the forced reconnect below.
 				if (!this.client.isTokenValid() && this._signFn && this._userId) {
 					try {
 						await this.client.loginWithKey(this._userId, this._signFn);
@@ -367,47 +379,16 @@ export class AbracadabraMCPServer {
 					}
 				}
 
+				// 2) Heal the active space provider (root doc tree + chat/awareness).
 				const conn = this._activeConnection;
-				if (!conn) return; // cold start — connect() handles it
-				if (this._wsConnected(conn.provider)) return;
-
-				// 2) Socket is Connecting/Disconnected — give the SDK's own reconnect a
-				//    bounded window to come back before we tear anything down.
-				try {
-					await waitForSync(conn.provider, 6000);
-				} catch {
-					/* fell through to rebuild */
-				}
-				// connectionStatus is a live getter — re-check via the helper (fresh
-				// scope) since the WS may have come back during the wait.
-				if (this._wsConnected(conn.provider)) return;
-
-				// 3) Still dead → rebuild the active space from scratch. A fresh
-				//    provider re-auths and reconnects cleanly; cached child providers
-				//    rode the old (now-destroyed) socket, so drop them too.
-				console.error(
-					"[abracadabra-mcp] Active connection dead — rebuilding space provider…",
-				);
-				const docId = conn.docId;
-				this._spaceConnections.delete(docId);
-				try {
-					conn.provider.destroy();
-				} catch {
-					/* already gone */
-				}
-				for (const [, cached] of this.childCache) {
-					try {
-						cached.provider.destroy();
-					} catch {
-						/* already gone */
-					}
-				}
-				this.childCache.clear();
-				try {
-					await this._connectToSpace(docId);
-					console.error("[abracadabra-mcp] Space provider rebuilt + synced");
-				} catch (e) {
-					console.error("[abracadabra-mcp] Connection rebuild failed:", e);
+				if (conn) await this._healProvider(conn.provider, "space");
+
+				// 3) Heal the dedicated inbox provider. It rides its OWN socket, so the
+				//    space-provider heal above doesn't cover it — a drop + expired JWT
+				//    could otherwise permanently stop its retry and silently kill DM /
+				//    mention dispatch. Same failure mode, same same-doc fix.
+				if (this._inboxProvider) {
+					await this._healProvider(this._inboxProvider, "inbox");
 				}
 			} finally {
 				this._reconnecting = null;
@@ -416,6 +397,45 @@ export class AbracadabraMCPServer {
 		return this._reconnecting;
 	}
 
+	/**
+	 * Bring one provider's socket back to a synced state WITHOUT swapping its
+	 * Y.Doc. First let the SDK's own auto-reconnect finish if it's mid-flight;
+	 * if the socket is still dead, force a reconnect on the same doc. Because the
+	 * document is never replaced, every observer attached to it (root awareness,
+	 * tree reads, the inbox `entries` array, the stateless chat listener) keeps
+	 * firing — no re-attach needed. Best-effort: logs but never throws.
+	 */
+	private async _healProvider(
+		provider: AbracadabraProvider,
+		label: string,
+	): Promise<void> {
+		if (this._wsConnected(provider)) return;
+
+		// Give the SDK's own reconnect a bounded window before forcing one.
+		try {
+			await waitForSync(provider, 6000);
+		} catch {
+			/* fell through to forced reconnect */
+		}
+		// connectionStatus is a live getter — re-check via the helper (fresh
+		// scope) since the WS may have come back during the wait.
+		if (this._wsConnected(provider)) return;
+
+		console.error(
+			`[abracadabra-mcp] ${label} socket dead — forcing reconnect on the same doc…`,
+		);
+		provider.reconnect();
+		try {
+			await waitForSync(provider, 10000);
+			console.error(`[abracadabra-mcp] ${label} reconnected + re-synced`);
+		} catch (e) {
+			console.error(
+				`[abracadabra-mcp] ${label} reconnect did not re-sync in time:`,
+				e,
+			);
+		}
+	}
+
 	async ensureSpaceActive(
 		targetId: string | null | undefined,
 	): Promise<boolean> {
@@ -1328,6 +1348,10 @@ export class AbracadabraMCPServer {
 			clearInterval(this.evictionTimer);
 			this.evictionTimer = null;
 		}
+		if (this.heartbeatTimer) {
+			clearInterval(this.heartbeatTimer);
+			this.heartbeatTimer = null;
+		}
 
 		for (const dispose of this._inboxDisposers) {
 			try {

package/src/tools/content.ts

@@ -7,7 +7,7 @@ import { z } from 'zod'
 import type { AbracadabraMCPServer } from '../server.ts'
 import { populateYDocFromMarkdown, parseFrontmatter } from '../converters/markdownToYjs.ts'
 import { yjsToMarkdown } from '../converters/yjsToMarkdown.ts'
-import { toPlain, patchEntry } from '@abraca/dabra'
+import { toPlain, patchEntry, reconcileDocCover } from '@abraca/dabra'
 
 export function registerContentTools(mcp: McpServer, server: AbracadabraMCPServer) {
   mcp.tool(
@@ -146,6 +146,13 @@ export function registerContentTools(mcp: McpServer, server: AbracadabraMCPServe
         const fallbackTitle = title || existingLabel || 'Untitled'
         populateYDocFromMarkdown(fragment, contentToWrite, fallbackTitle)
 
+        // Keep the persisted cover metadata in sync with the media blocks now
+        // in the body. Without this, removing an image via write_document left
+        // an orphaned cover on the kanban/gallery card (image gone from the
+        // body, coverUploadId still pointing at the upload).
+        const coverTree = server.getTreeMap()
+        if (coverTree) reconcileDocCover(coverTree, docId, fragment)
+
         // Auto-update presence: mark this doc as focused and place cursor at end
         server.setFocusedDoc(docId)
         server.setDocCursor(docId, fragment.length)