From 2e2cfcd773bce653a069fc0776396bef0beb64dc Mon Sep 17 00:00:00 2001
From: agent_coder <agent_coder@vvzvlad.xyz>
Date: Fri, 10 Jul 2026 05:35:57 +0300
Subject: [PATCH] feat(mcp): enrich collab connect/persist/closed error texts
 with pageId + retry hint (#437)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Append `(pageId <id>; transient — retry once; persistent failures mean the
collab server is unreachable/overloaded)` to the connect-timeout, persist-timeout
and connection-closed error texts in CollabSession, so the agent can self-correct
instead of blind-looping. The Yjs-encode error is left untouched (it already names
the offending attribute).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/mcp/src/lib/collab-session.ts | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git a/packages/mcp/src/lib/collab-session.ts b/packages/mcp/src/lib/collab-session.ts
index 1c1c8d81..9a4b7a6d 100644
--- a/packages/mcp/src/lib/collab-session.ts
+++ b/packages/mcp/src/lib/collab-session.ts
@@ -202,6 +202,21 @@ export class CollabSession {
     this.ydoc = new Y.Doc();
   }
 
+  /**
+   * Shared diagnostic suffix (issue #437) appended to the connect-timeout,
+   * persist-timeout and connection-closed error texts: names the offending
+   * pageId and tells the agent this class of failure is transient (retry once)
+   * vs. a persistent collab-server outage, so it can self-correct instead of
+   * blind-looping. The Yjs-encode error is deliberately NOT touched — it
+   * already names the offending attribute.
+   */
+  private hint(): string {
+    return (
+      `(pageId ${this.pageId}; transient — retry once; persistent failures ` +
+      `mean the collab server is unreachable/overloaded)`
+    );
+  }
+
   /**
    * A cached session may be reused only when it is fully ready, still synced,
    * has not lost its connection, and has not exceeded its max age (invariant 5
@@ -232,7 +247,9 @@ export class CollabSession {
         // The 25s connect timeout: the collab connection never became ready.
         this.opts?.onConnectTimeout?.();
         this.teardown(
-          new Error("Connection timeout to collaboration server"),
+          new Error(
+            `Connection timeout to collaboration server ${this.hint()}`,
+          ),
           false,
         );
       }, CONNECT_TIMEOUT_MS);
@@ -259,7 +276,7 @@ export class CollabSession {
           if (process.env.DEBUG) console.error("WS Disconnect");
           this.teardown(
             new Error(
-              "Collaboration connection closed before the update was persisted/synced",
+              `Collaboration connection closed before the update was persisted/synced ${this.hint()}`,
             ),
             true,
           );
@@ -268,7 +285,7 @@ export class CollabSession {
           if (process.env.DEBUG) console.error("WS Close");
           this.teardown(
             new Error(
-              "Collaboration connection closed before the update was persisted/synced",
+              `Collaboration connection closed before the update was persisted/synced ${this.hint()}`,
             ),
             true,
           );
@@ -403,7 +420,7 @@ export class CollabSession {
         persistTimer = setTimeout(() => {
           localFinish(
             new Error(
-              "Timeout waiting for collaboration server to persist the update",
+              `Timeout waiting for collaboration server to persist the update ${this.hint()}`,
             ),
           );
         }, PERSIST_TIMEOUT_MS);