fix(ai): harden pre-response ECONNRESET retry — bigger budget, jittered backoff, shorter keep-alive (#310)

In prod the AI provider resets the connection pre-response (ECONNRESET); the
#175 pre-response retry recovers it, but 2 of the 3 allowed attempts were burned
in a single turn — no headroom, and one more reset would surface an error to the
user. This is tuning for resilience (not a diagnosis of who resets):

- Retry budget 2 → 4 (total 5 attempts), env-configurable via
  AI_STREAM_PRE_RESPONSE_RETRIES (0 = no retry; empty/invalid → default 4).
- Backoff: linear 150*(attempt+1) → capped exponential + full jitter
  (preResponseBackoffMs, a pure injectable helper): base 150ms, ×2 per attempt,
  capped 2000ms, delay = random in [0, capped]. Avoids a synchronized retry
  storm and spreads reconnects across the reset window.
- Keep-alive default 10_000 → 4_000 ms so undici recycles idle sockets before a
  ~5s upstream/middlebox idle cutoff can poison them (a common pre-response
  reset cause). Still env-overridable via AI_STREAM_KEEPALIVE_MS.
- .env.example documents both knobs.

Timeout (900s), RETRYABLE_CONNECT_CODES, and the instrumentation are unchanged.

refs #310

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.env.example

@@ -173,9 +173,21 @@ MCP_DOCMOST_PASSWORD=
 # Keep-alive recycle window (ms) for streaming chat/agent AI + external-MCP calls.
 # A pooled connection idle longer than this is closed instead of reused, so a
 # NAT / egress firewall / reverse proxy that silently drops idle connections
-# cannot poison a reused socket into a PRE-RESPONSE `read ECONNRESET`. Lower it if
-# your egress drops idle connections faster than ~10s. Default 10000 (10 s).
-# AI_STREAM_KEEPALIVE_MS=10000
+# cannot poison a reused socket into a PRE-RESPONSE `read ECONNRESET`. Kept under
+# common ~5s upstream/middlebox idle cutoffs so undici recycles the socket before
+# the network kills it (fewer resets), while still reusing within a burst of
+# back-to-back calls. Lower it further if your egress drops idle connections even
+# faster. Default 4000 (4 s).
+# AI_STREAM_KEEPALIVE_MS=4000
+
+# Number of PRE-RESPONSE connection retries for streaming chat/agent AI calls: a
+# reset/timeout BEFORE any response byte (e.g. `read ECONNRESET` on a stale pooled
+# socket) is retried on a fresh connection with jittered exponential backoff.
+# Total attempts = value + 1, so the default 4 gives 5 attempts — headroom to
+# absorb a short BURST of upstream resets without exhausting the budget. Safe to
+# retry: a started stream is never replayed, only a connect that never responded.
+# 0 disables the retry. Default 4.
+# AI_STREAM_PRE_RESPONSE_RETRIES=4
 
 # Silence timeout (ms) for EXTERNAL-MCP transport ONLY (not the chat provider).
 # Tighter than AI_STREAM_TIMEOUT_MS so a byte-silent/hung MCP server is broken in

apps/client/src/components/ui/agent-avatar-stack.test.tsx

@@ -2,7 +2,7 @@ import { describe, it, expect, vi } from "vitest";
 import { render, screen, fireEvent } from "@testing-library/react";
 import { MantineProvider } from "@mantine/core";
 import { Provider, createStore } from "jotai";
-import { AgentAvatarStack, agentGlyphBackground } from "./agent-avatar-stack";
+import { AgentAvatarStack } from "./agent-avatar-stack";
 import {
   activeAiChatIdAtom,
   aiChatWindowOpenAtom,
@@ -26,23 +26,6 @@ function renderStack(props: Props) {
   return { store, ...utils };
 }
 
-describe("agentGlyphBackground", () => {
-  it("is deterministic for a given agent name", () => {
-    expect(agentGlyphBackground("Researcher")).toBe(
-      agentGlyphBackground("Researcher"),
-    );
-  });
-
-  it("differs by name and stays a fixed dark shade (readable emoji)", () => {
-    expect(agentGlyphBackground("Researcher")).not.toBe(
-      agentGlyphBackground("Нарратор"),
-    );
-    // Only the hue varies; saturation/lightness are pinned low so the glyph is
-    // always a dark circle.
-    expect(agentGlyphBackground("Нарратор")).toMatch(/^hsl\(\d+, 45%, 24%\)$/);
-  });
-});
-
 describe("AgentAvatarStack", () => {
   it("internal chat WITH role: emoji glyph in front + human launcher behind", () => {
     const { container } = renderStack({

apps/client/src/components/ui/agent-avatar-stack.tsx

@@ -23,34 +23,14 @@ export interface LauncherInfo {
   avatarUrl?: string | null;
 }
 
+// Same violet token as the former AiAgentBadge (which used color="violet").
+const AGENT_COLOR = "violet";
 const GLYPH_SIZE = 38;
 const LAUNCHER_SIZE = 22;
-// How far the launcher avatar sticks out past the agent's top-right corner, so
+// How far the launcher avatar sticks out past the agent's bottom-right corner, so
 // the "human behind" reads as behind (lower z-index) yet stays clearly visible.
 const LAUNCHER_OVERHANG = 8;
 
-// Small deterministic string hash (same algorithm as custom-avatar's initials
-// hash) used to pick a stable per-agent glyph color.
-function hashName(input: string): number {
-  let hash = 0;
-  for (let i = 0; i < input.length; i += 1) {
-    hash = (hash << 5) - hash + input.charCodeAt(i);
-    hash |= 0;
-  }
-  return Math.abs(hash);
-}
-
-/**
- * Deterministic DARK background for an emoji/sparkles agent glyph. The hue is
- * derived from the agent-name hash so distinct agents get distinct circles;
- * saturation and lightness are pinned low ("shifted into darkness") so a bright
- * emoji or the white sparkles icon stays legible on top (#300).
- */
-export function agentGlyphBackground(name: string): string {
-  const hue = hashName(name) % 360;
-  return `hsl(${hue}, 45%, 24%)`;
-}
-
 /**
  * The front avatar. Image-source priority (#300):
  *   1. agent.avatarUrl -> a real avatar image (external MCP agent account).
@@ -68,18 +48,9 @@ function AgentGlyph({ agent }: { agent: AgentInfo }) {
     );
   }
 
-  // Emoji/sparkles glyphs sit on a per-agent dark circle (hashed from the agent
-  // name) so different agents are visually distinct, while the dark background
-  // keeps the emoji / white sparkles icon readable.
-  const bg = agentGlyphBackground(agent.name);
-  const glyphStyles = {
-    root: { background: bg },
-    placeholder: { background: bg, color: "var(--mantine-color-white)" },
-  };
-
   if (agent.emoji) {
     return (
-      <Avatar size={GLYPH_SIZE} radius="xl" variant="filled" styles={glyphStyles}>
+      <Avatar size={GLYPH_SIZE} radius="xl" color={AGENT_COLOR} variant="filled">
         <span style={{ fontSize: Math.round(GLYPH_SIZE * 0.5) }} aria-hidden>
           {agent.emoji}
         </span>
@@ -88,7 +59,7 @@ function AgentGlyph({ agent }: { agent: AgentInfo }) {
   }
 
   return (
-    <Avatar size={GLYPH_SIZE} radius="xl" variant="filled" styles={glyphStyles}>
+    <Avatar size={GLYPH_SIZE} radius="xl" color={AGENT_COLOR} variant="filled">
       <IconSparkles size={Math.round(GLYPH_SIZE * 0.55)} stroke={2} />
     </Avatar>
   );
@@ -185,7 +156,7 @@ export function AgentAvatarStack({
         : {})}
     >
       {launcher && (
-        <Box pos="absolute" top={0} right={0} style={{ zIndex: 0 }}>
+        <Box pos="absolute" bottom={0} right={0} style={{ zIndex: 0 }}>
           <CustomAvatar
             size={LAUNCHER_SIZE}
             avatarUrl={launcher.avatarUrl}
@@ -194,8 +165,8 @@ export function AgentAvatarStack({
           />
         </Box>
       )}
-      {/* The agent glyph keeps its own size (flex-centered in the container); the
-          launcher overhangs it by LAUNCHER_OVERHANG at the top-right and stays visible. */}
+      {/* Pin the agent glyph to the top-left at its own size; the launcher then
+          overhangs it by LAUNCHER_OVERHANG at the bottom-right and stays visible. */}
       <Box
         style={{
           position: "relative",

apps/client/src/features/ai-chat/components/reasoning-block.test.tsx

@@ -1,7 +1,14 @@
 import { describe, it, expect, vi } from "vitest";
-import { render, screen } from "@testing-library/react";
+import { render, screen, fireEvent } from "@testing-library/react";
 import { MantineProvider } from "@mantine/core";
 
+// Spy on the markdown renderer so we can assert it is NOT called while the block
+// is collapsed (the #302 fix) and IS called once on expand. The count/fallback
+// tests don't depend on real markdown, so a light stub is safe.
+vi.mock("@/features/ai-chat/utils/markdown.ts", () => ({
+  renderChatMarkdown: vi.fn((md: string) => `<p>${md}</p>`),
+}));
+
 // Stub react-i18next so `t` returns the key with `{{count}}` interpolated. This
 // keeps the assertions on the component's OWN count logic (authoritative vs
 // estimate) rather than on translation, and mirrors the t-mock pattern used by
@@ -17,6 +24,7 @@ vi.mock("react-i18next", () => ({
 
 import ReasoningBlock from "./reasoning-block";
 import { estimateTokens } from "@/features/ai-chat/utils/count-stream-tokens.ts";
+import { renderChatMarkdown } from "@/features/ai-chat/utils/markdown.ts";
 
 // matchMedia (read by MantineProvider) is stubbed globally in vitest.setup.ts.
 
@@ -62,4 +70,18 @@ describe("ReasoningBlock", () => {
     // either way the text is present in the document.
     expect(screen.getByText(/reasoning/)).toBeDefined();
   });
+
+  it("does not parse the reasoning markdown while collapsed; parses on expand (#302)", () => {
+    const renderSpy = vi.mocked(renderChatMarkdown);
+    renderSpy.mockClear();
+    renderBlock({ text: "**bold** reasoning", tokens: 5 });
+    // Collapsed is the default. The expensive markdown parse (marked + DOMPurify)
+    // must NOT run for the hidden body — that O(n^2) re-parse on every streamed
+    // delta is exactly what froze the chat (#302). The collapsed body shows the
+    // cheap raw-text fallback instead.
+    expect(renderSpy).not.toHaveBeenCalled();
+    // Expanding parses the current text exactly once (a user-initiated click).
+    fireEvent.click(screen.getByRole("button"));
+    expect(renderSpy).toHaveBeenCalledTimes(1);
+  });
 });

apps/client/src/features/ai-chat/components/reasoning-block.tsx

@@ -34,15 +34,19 @@ function ReasoningBlock({ text, tokens }: ReasoningBlockProps) {
   // Authoritative count wins; otherwise estimate live from the streamed text.
   const count = tokens && tokens > 0 ? tokens : estimateTokens(text);
   const trimmed = text.trim();
-  // Memoize the markdown render so toggling `open` (or a parent re-render caused
-  // by an unrelated streamed delta) does not re-parse the reasoning text; it
-  // recomputes only when the reasoning text itself changes (while it streams in).
-  // collapseBlankLines collapses the blank-line gaps the model emits between every
-  // list item / paragraph so the reasoning renders compactly (tight lists, joined
-  // paragraphs) — ONLY here, not in the normal answer.
+  // Parse the reasoning markdown ONLY while the block is expanded. Collapsed is the
+  // default and the common case during a long "thinking" stream: reasoning text
+  // streams in and grows with every throttled delta (~20Hz), so a `[trimmed]`-only
+  // memo re-parses the whole, ever-growing text (marked + DOMPurify) on every delta
+  // — an O(n²) storm that pins the main thread and freezes the chat, all for a block
+  // the user isn't even looking at (the html is only shown inside <Collapse in={open}>
+  // below). Gating on `open` skips that hidden parsing entirely; expanding parses the
+  // current text once (an instant, user-initiated click), and further streaming while
+  // open is the normal per-delta append render, like the answer.
   const html = useMemo(
-    () => (trimmed ? renderChatMarkdown(collapseBlankLines(trimmed), {}) : ""),
-    [trimmed],
+    () =>
+      open && trimmed ? renderChatMarkdown(collapseBlankLines(trimmed), {}) : "",
+    [open, trimmed],
   );
 
   return (

apps/server/src/core/ai-chat/tools/ai-chat-tools.service.ts

@@ -173,6 +173,11 @@ export class AiChatToolsService {
       });
 
     return {
+      // INTENTIONAL per-transport divergence (not in the shared registry): this
+      // in-app search runs a semantic + keyword hybrid (RRF) with in-process
+      // access control and a tuned schema (limit 1-20); the standalone MCP
+      // `search` is a plain REST full-text search (limit up to 100). Different
+      // behaviour AND schema, so kept per-layer.
       searchPages: tool({
         description:
           'Search the wiki for pages relevant to a query. Combines exact ' +
@@ -432,6 +437,10 @@ export class AiChatToolsService {
         },
       }),
 
+      // INTENTIONAL per-transport divergence (not shared): the description is
+      // tuned for the in-app agent (e.g. "retry with a corrected EXACT selection"
+      // and "Reversible via the comment UI"); the standalone MCP `create_comment`
+      // keeps its own wording. Kept per-layer.
       createComment: tool({
         description:
           'Add an INLINE comment to a page, or reply to an existing top-level ' +
@@ -519,6 +528,10 @@ export class AiChatToolsService {
         async () => await client.getSpaces(),
       ),
 
+      // INTENTIONAL per-transport divergence (not shared): keeps the `tree:true`
+      // hierarchy mode but is worded for the in-app agent; the standalone MCP
+      // `list_pages` carries its own wording. Kept per-layer so each side tunes
+      // its own guidance.
       listPages: tool({
         description:
           'List the most recent pages, optionally scoped to a single space. ' +
@@ -692,85 +705,25 @@ export class AiChatToolsService {
         async ({ pageId }) => await client.stashPage(pageId),
       ),
 
-      patchNode: tool({
-        description:
-          'Replace a single content block (by id) with a new ProseMirror ' +
-          'node; the replacement keeps the same nodeId. Example node: a ' +
-          'paragraph {"type":"paragraph","content":[{"type":"text","text":"Hello"}]} ' +
-          'or a heading {"type":"heading","attrs":{"level":2},"content":' +
-          '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
-          '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node arg ' +
-          'may be a JSON object or a JSON string (both accepted). Reversible: ' +
-          'the previous version is kept in page history.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page.'),
-          nodeId: z
-            .string()
-            .describe('The block id to replace (from getOutline/getPageJson).'),
-          node: z
-            .any()
-            .describe(
-              'The replacement ProseMirror node, e.g. ' +
-                '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
-                'JSON object or JSON string both accepted.',
-            ),
-        }),
-        execute: async ({ pageId, nodeId, node }) => {
-          // Parity with the standalone MCP server (index.ts patch_node): the
-          // model sometimes serializes the node as a JSON string. Parse it
-          // before the client's typeof-object guard rejects it.
+      // Schema + description from the shared registry (identical across both
+      // transports). The execute body keeps its OWN parseNodeArg normalization:
+      // the model sometimes serializes the node as a JSON string, and we parse it
+      // before the client's typeof-object guard rejects it (parity with the
+      // standalone MCP server, index.ts patch_node).
+      patchNode: sharedTool(
+        sharedToolSpecs.patchNode,
+        async ({ pageId, nodeId, node }) => {
           const parsedNode = parseNodeArg(node);
           return await client.patchNode(pageId, nodeId, parsedNode);
         },
-      }),
+      ),
 
-      insertNode: tool({
-        description:
-          'Insert a ProseMirror node relative to an anchor, or append it at ' +
-          'the top level. For before/after you MUST provide EXACTLY ONE of ' +
-          'anchorNodeId or anchorText. Example node: a paragraph ' +
-          '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
-          'heading {"type":"heading","attrs":{"level":2},"content":' +
-          '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
-          '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node arg ' +
-          'may be a JSON object or a JSON string (both accepted). Reversible ' +
-          'via page history.',
-        inputSchema: modelFriendlyInput({
-          pageId: z.string().describe('The id of the page.'),
-          node: z
-            .any()
-            .describe(
-              'The ProseMirror node to insert, e.g. ' +
-                '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
-                'JSON object or JSON string both accepted.',
-            ),
-          position: z
-            .enum(['before', 'after', 'append'])
-            .describe('Where to insert relative to the anchor.'),
-          anchorNodeId: z
-            .string()
-            .optional()
-            .describe('Anchor block id (for before/after).'),
-          anchorText: z
-            .string()
-            .optional()
-            .describe(
-              'Anchor text fragment (for before/after), matched against the ' +
-                "block's literal rendered plain text (no markdown). " +
-                'Markdown/emoji are tolerated as a fallback; prefer plain text ' +
-                'or anchorNodeId.',
-            ),
-        }),
-        execute: async ({
-          pageId,
-          node,
-          position,
-          anchorNodeId,
-          anchorText,
-        }) => {
-          // Parity with the standalone MCP server (index.ts insert_node): the
-          // model sometimes serializes the node as a JSON string. Parse it
-          // before the client's typeof-object guard rejects it.
+      // Shared registry schema + description; execute retains parseNodeArg on the
+      // incoming node (parity with the standalone MCP server, index.ts
+      // insert_node).
+      insertNode: sharedTool(
+        sharedToolSpecs.insertNode,
+        async ({ pageId, node, position, anchorNodeId, anchorText }) => {
           const parsedNode = parseNodeArg(node);
           return await client.insertNode(pageId, parsedNode, {
             position,
@@ -778,7 +731,7 @@ export class AiChatToolsService {
             anchorText,
           });
         },
-      }),
+      ),
 
       deleteNode: sharedTool(
         sharedToolSpecs.deleteNode,
@@ -821,6 +774,10 @@ export class AiChatToolsService {
         },
       }),
 
+      // NOT in the shared registry: this layer names the table argument
+      // `tableRef`, while the standalone MCP tool names it `table` (index.ts).
+      // Sharing one buildShape would rename a model-facing parameter on one
+      // transport, so the table row/cell tools stay per-layer by design.
       tableInsertRow: tool({
         description:
           'Insert a row of plain-text cells into a table. Reversible via ' +
@@ -841,6 +798,8 @@ export class AiChatToolsService {
           await client.tableInsertRow(pageId, tableRef, cells, index),
       }),
 
+      // NOT shared — same `tableRef` (here) vs `table` (MCP) parameter-name
+      // divergence as tableInsertRow.
       tableDeleteRow: tool({
         description:
           'Delete a table row at a 0-based index. Reversible via page history.',
@@ -855,6 +814,8 @@ export class AiChatToolsService {
           await client.tableDeleteRow(pageId, tableRef, index),
       }),
 
+      // NOT shared — same `tableRef` (here) vs `table` (MCP) parameter-name
+      // divergence as tableInsertRow.
       tableUpdateCell: tool({
         description:
           'Set the plain-text content of a table cell at [row, col] (0-based). ' +
@@ -884,6 +845,10 @@ export class AiChatToolsService {
           await client.importPageMarkdown(pageId, markdown),
       ),
 
+      // INTENTIONAL per-transport divergence (not shared): adds a security
+      // confirmation framing ("Only share when the user explicitly asked, since
+      // this exposes the page to anyone with the link") for the in-app agent; the
+      // standalone MCP `share_page` keeps the plain public-URL wording.
       sharePage: tool({
         description:
           'Make a page PUBLICLY accessible and return its public URL. ' +
@@ -910,6 +875,10 @@ export class AiChatToolsService {
         async ({ historyId }) => await client.restorePageVersion(historyId),
       ),
 
+      // INTENTIONAL per-transport divergence (not shared): deliberately omits the
+      // `deleteComments` schema field (comment-deletion guardrail) and carries a
+      // much shorter description; the standalone MCP `docmost_transform` exposes
+      // the full helper catalogue. Different schema, so kept per-layer.
       transformPage: tool({
         description:
           'Run a sandboxed JS transform of the form `(doc, ctx) => doc` over a ' +

apps/server/src/core/ai-chat/tools/shared-tool-specs.contract.spec.ts

@@ -113,9 +113,15 @@ describe('SHARED_TOOL_SPECS contract parity', () => {
       const expectedKeys = Object.keys(shape).sort();
       expect(actualKeys).toEqual(expectedKeys);
 
-      // A non-.optional() field must surface as required in the advertised schema.
+      // A field that was NOT wrapped in `.optional()` must surface as required in
+      // the advertised schema. We test for the ZodOptional wrapper rather than
+      // `isOptional()`: `z.any()`/`z.unknown()` accept `undefined` and so report
+      // `isOptional() === true`, yet z.toJSONSchema still lists them under
+      // `required` (they carry no `.optional()`). Matching on the wrapper is what
+      // the emitted JSON schema actually does, so it stays correct for the
+      // registry's `node: z.any()` fields (patchNode/insertNode).
       const expectedRequired = Object.entries(shape)
-        .filter(([, field]) => !(field as z.ZodTypeAny).isOptional?.())
+        .filter(([, field]) => !(field instanceof z.ZodOptional))
         .map(([k]) => k)
         .sort();
       expect((json.required ?? []).slice().sort()).toEqual(expectedRequired);

apps/server/src/integrations/ai/ai-streaming-fetch.spec.ts

@@ -6,6 +6,8 @@ import {
   streamKeepAliveMs,
   streamingDispatcherOptions,
   isRetryableConnectError,
+  preResponseConnectRetries,
+  preResponseBackoffMs,
 } from './ai-streaming-fetch';
 
 /**
@@ -47,8 +49,8 @@ describe('streamTimeoutMs', () => {
     expect(streamingDispatcherOptions()).toEqual({
       headersTimeout: 900_000,
       bodyTimeout: 900_000,
-      keepAliveTimeout: 10_000,
-      keepAliveMaxTimeout: 10_000,
+      keepAliveTimeout: 4_000,
+      keepAliveMaxTimeout: 4_000,
     });
   });
 });
@@ -60,21 +62,91 @@ describe('streamKeepAliveMs', () => {
     else process.env.AI_STREAM_KEEPALIVE_MS = ORIG;
   });
 
-  it('defaults to 10s (recycle idle sockets so a NAT/proxy drop cannot poison reuse)', () => {
+  it('defaults to 4s (recycle idle sockets under common ~5s upstream idle cutoffs)', () => {
     delete process.env.AI_STREAM_KEEPALIVE_MS;
-    expect(streamKeepAliveMs()).toBe(10_000);
+    expect(streamKeepAliveMs()).toBe(4_000);
   });
 
   it('honours a positive override and ignores invalid/non-positive', () => {
-    process.env.AI_STREAM_KEEPALIVE_MS = '4000';
-    expect(streamKeepAliveMs()).toBe(4000);
+    process.env.AI_STREAM_KEEPALIVE_MS = '7000';
+    expect(streamKeepAliveMs()).toBe(7000);
     for (const bad of ['0', '-1', 'x', '']) {
       process.env.AI_STREAM_KEEPALIVE_MS = bad;
-      expect(streamKeepAliveMs()).toBe(10_000);
+      expect(streamKeepAliveMs()).toBe(4_000);
     }
   });
 });
 
+/**
+ * #310: the PRE-RESPONSE retry budget was raised 2 -> 4 (5 total attempts) and
+ * made env-configurable so a BURST of upstream resets doesn't exhaust it.
+ */
+describe('preResponseConnectRetries', () => {
+  const ORIG = process.env.AI_STREAM_PRE_RESPONSE_RETRIES;
+  afterEach(() => {
+    if (ORIG === undefined) delete process.env.AI_STREAM_PRE_RESPONSE_RETRIES;
+    else process.env.AI_STREAM_PRE_RESPONSE_RETRIES = ORIG;
+  });
+
+  it('defaults to 4 retries (5 total attempts)', () => {
+    delete process.env.AI_STREAM_PRE_RESPONSE_RETRIES;
+    expect(preResponseConnectRetries()).toBe(4);
+  });
+
+  it('honours a non-negative override (incl. 0 = single attempt)', () => {
+    process.env.AI_STREAM_PRE_RESPONSE_RETRIES = '6';
+    expect(preResponseConnectRetries()).toBe(6);
+    process.env.AI_STREAM_PRE_RESPONSE_RETRIES = '0';
+    expect(preResponseConnectRetries()).toBe(0);
+  });
+
+  it('ignores an invalid / negative override (falls back to default 4)', () => {
+    for (const bad of ['-1', 'abc', '']) {
+      process.env.AI_STREAM_PRE_RESPONSE_RETRIES = bad;
+      expect(preResponseConnectRetries()).toBe(4);
+    }
+  });
+});
+
+/**
+ * #310: linear `150 * (attempt + 1)` backoff replaced with capped exponential +
+ * FULL jitter to avoid a thundering herd of lock-step reconnects. Bound-check the
+ * jitter by pinning the randomness source to its extremes.
+ */
+describe('preResponseBackoffMs', () => {
+  it('with rand=0 waits 0 (bottom of the full-jitter window)', () => {
+    for (let attempt = 0; attempt < 6; attempt++) {
+      expect(preResponseBackoffMs(attempt, () => 0)).toBe(0);
+    }
+  });
+
+  it('with rand=1 returns the capped exponential top of the window', () => {
+    // base 150ms, exp = 150 * 2**attempt, capped at 2000ms.
+    expect(preResponseBackoffMs(0, () => 1)).toBe(150);
+    expect(preResponseBackoffMs(1, () => 1)).toBe(300);
+    expect(preResponseBackoffMs(2, () => 1)).toBe(600);
+    expect(preResponseBackoffMs(3, () => 1)).toBe(1200);
+    // 150 * 2**4 = 2400 -> capped to 2000.
+    expect(preResponseBackoffMs(4, () => 1)).toBe(2000);
+    expect(preResponseBackoffMs(10, () => 1)).toBe(2000);
+  });
+
+  it('stays within [0, cap] and is NOT the old fixed linear value', () => {
+    const cap = 2000;
+    for (let attempt = 0; attempt < 8; attempt++) {
+      for (const r of [0, 0.5, 0.999, 1]) {
+        const d = preResponseBackoffMs(attempt, () => r);
+        expect(d).toBeGreaterThanOrEqual(0);
+        expect(d).toBeLessThanOrEqual(cap);
+      }
+    }
+    // The old formula gave a fixed 150*(attempt+1); the jittered one with a
+    // mid-range rand does not reproduce it (e.g. attempt 0 -> 75, not 150).
+    expect(preResponseBackoffMs(0, () => 0.5)).toBe(75);
+    expect(preResponseBackoffMs(0, () => 0.5)).not.toBe(150);
+  });
+});
+
 describe('isRetryableConnectError', () => {
   it('matches connection-level codes on the error or its cause', () => {
     expect(isRetryableConnectError({ cause: { code: 'ECONNRESET' } })).toBe(true);
@@ -156,8 +228,12 @@ describe('createStreamingFetch — against a delayed server', () => {
 describe('withPreResponseRetry', () => {
   // The retry is the OUTERMOST layer (over the dispatcher-bound streaming fetch),
   // matching ai.service's withPreResponseRetry(instrument(createStreamingFetch())).
-  // PRE_RESPONSE_CONNECT_RETRIES is 2 -> at most 3 total attempts.
-  const MAX_ATTEMPTS = 3;
+  // The budget is env-driven (AI_STREAM_PRE_RESPONSE_RETRIES, default 4 -> 5
+  // total attempts). We PIN it to 2 here so the exhaustion test is fast and
+  // deterministic regardless of the default; total attempts = retries + 1 = 3.
+  const RETRIES = 2;
+  const MAX_ATTEMPTS = RETRIES + 1;
+  const ORIG_RETRIES = process.env.AI_STREAM_PRE_RESPONSE_RETRIES;
   let server: http.Server;
   let url: string;
   let requests = 0;
@@ -194,6 +270,13 @@ describe('withPreResponseRetry', () => {
   beforeEach(() => {
     requests = 0;
     resetMode = 'first';
+    process.env.AI_STREAM_PRE_RESPONSE_RETRIES = String(RETRIES);
+  });
+
+  afterEach(() => {
+    if (ORIG_RETRIES === undefined)
+      delete process.env.AI_STREAM_PRE_RESPONSE_RETRIES;
+    else process.env.AI_STREAM_PRE_RESPONSE_RETRIES = ORIG_RETRIES;
   });
 
   it('retries a pre-response reset on a fresh connection and succeeds', async () => {
@@ -216,12 +299,28 @@ describe('withPreResponseRetry', () => {
     expect(caught).toBeDefined();
     // A retryable connection error reached the caller (not swallowed).
     expect(isRetryableConnectError(caught)).toBe(true);
-    // Bounded: exactly PRE_RESPONSE_CONNECT_RETRIES + 1 attempts hit the server
+    // Bounded: exactly AI_STREAM_PRE_RESPONSE_RETRIES + 1 attempts hit the server
     // (pins both the limit and that the final error propagates — guards an
     // off-by-one or an infinite loop).
     expect(requests).toBe(MAX_ATTEMPTS);
   });
 
+  it('honours a raised AI_STREAM_PRE_RESPONSE_RETRIES (more attempts before giving up)', async () => {
+    // Env-driven budget: 4 retries -> 5 total attempts against a persistently
+    // resetting connect.
+    process.env.AI_STREAM_PRE_RESPONSE_RETRIES = '4';
+    resetMode = 'all';
+    let caught: unknown;
+    try {
+      await retryingFetch()(url);
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeDefined();
+    expect(isRetryableConnectError(caught)).toBe(true);
+    expect(requests).toBe(5);
+  });
+
   it('does NOT retry an aborted request (no retry storm)', async () => {
     resetMode = 'all';
     const ctrl = new AbortController();

apps/server/src/integrations/ai/ai-streaming-fetch.ts

@@ -19,7 +19,7 @@ import { Agent } from 'undici';
 const DEFAULT_STREAM_TIMEOUT_MS = 900_000;
 
 /**
- * Default keep-alive recycle window (10s). A pooled connection idle longer than
+ * Default keep-alive recycle window (4s). A pooled connection idle longer than
  * this is CLOSED rather than reused.
  *
  * Long agent turns leave gaps of tens of seconds between provider calls (one
@@ -30,17 +30,70 @@ const DEFAULT_STREAM_TIMEOUT_MS = 900_000;
  * the resets correlate with idleSincePrevCall ~42s, while a direct path to the
  * provider does NOT reset). Recycling idle sockets well below such a drop window
  * means a long-gap call opens a fresh connection instead of reusing a stale one.
+ * Kept comfortably under common ~5s upstream/middlebox idle cutoffs so undici
+ * recycles the socket before the network kills it, while still long enough to
+ * reuse a connection within a single burst of back-to-back calls (#310).
  * `keepAliveMaxTimeout` also caps a server-advertised keep-alive so the provider
  * cannot push the reuse window back up.
  */
-const DEFAULT_STREAM_KEEPALIVE_MS = 10_000;
+const DEFAULT_STREAM_KEEPALIVE_MS = 4_000;
 
 /**
- * How many times to retry a PRE-RESPONSE connection failure (a reset/timeout
- * before ANY response byte) on a fresh connection. Safe because `fetch()` only
- * rejects before the Response resolves — a started stream is never replayed.
+ * Default number of times to retry a PRE-RESPONSE connection failure (a
+ * reset/timeout before ANY response byte) on a fresh connection. Safe because
+ * `fetch()` only rejects before the Response resolves — a started stream is
+ * never replayed.
+ *
+ * Raised from 2 to 4 (total 5 attempts) so a short BURST of upstream/middlebox
+ * resets is absorbed without exhausting the budget: prod saw 2 of 3 attempts
+ * burned on a single turn, leaving no headroom (#310). Override with
+ * `AI_STREAM_PRE_RESPONSE_RETRIES`.
  */
-const PRE_RESPONSE_CONNECT_RETRIES = 2;
+const DEFAULT_PRE_RESPONSE_CONNECT_RETRIES = 4;
+
+/**
+ * Configured PRE-RESPONSE retry budget. Override with
+ * `AI_STREAM_PRE_RESPONSE_RETRIES`; a missing/invalid/negative value falls back
+ * to {@link DEFAULT_PRE_RESPONSE_CONNECT_RETRIES}. Total attempts = value + 1.
+ * 0 disables the retry (a single attempt).
+ */
+export function preResponseConnectRetries(): number {
+  // Read the raw string first: an empty/whitespace value coerces to 0 via
+  // Number(), which is a VALID setting here (0 = single attempt), so it must be
+  // treated as "unset" rather than "disable the retry".
+  const rawStr = process.env.AI_STREAM_PRE_RESPONSE_RETRIES;
+  if (rawStr === undefined || rawStr.trim() === '') {
+    return DEFAULT_PRE_RESPONSE_CONNECT_RETRIES;
+  }
+  const raw = Number(rawStr);
+  return Number.isFinite(raw) && raw >= 0
+    ? Math.floor(raw)
+    : DEFAULT_PRE_RESPONSE_CONNECT_RETRIES;
+}
+
+/** Base backoff before the first PRE-RESPONSE retry (ms). */
+const PRE_RESPONSE_BACKOFF_BASE_MS = 150;
+
+/** Cap on the exponential backoff window before jitter (ms). */
+const PRE_RESPONSE_BACKOFF_CAP_MS = 2_000;
+
+/**
+ * Backoff (ms) to wait before PRE-RESPONSE retry number `attempt` (0-based).
+ *
+ * Capped exponential with FULL jitter: `delay = random in [0, min(base*2^attempt,
+ * cap)]`. Full jitter spreads concurrent retries across the whole window so a
+ * burst of turns that all reset at once do not reconnect in lock-step and
+ * hammer the upstream in a thundering herd (#310); the exponential growth backs
+ * off harder as resets persist, and the cap keeps the wait bounded.
+ */
+export function preResponseBackoffMs(
+  attempt: number,
+  rand: () => number = Math.random,
+): number {
+  const exp = PRE_RESPONSE_BACKOFF_BASE_MS * 2 ** attempt;
+  const capped = Math.min(exp, PRE_RESPONSE_BACKOFF_CAP_MS);
+  return rand() * capped;
+}
 
 /** undici cause codes for a connection-level failure that occurred PRE-RESPONSE. */
 const RETRYABLE_CONNECT_CODES = new Set([
@@ -177,20 +230,19 @@ export function createStreamingFetch(): typeof fetch {
  */
 export function withPreResponseRetry(baseFetch: typeof fetch): typeof fetch {
   return (async (input: Parameters<typeof fetch>[0], init?: RequestInit) => {
+    const maxRetries = preResponseConnectRetries();
     for (let attempt = 0; ; attempt++) {
       try {
         return await baseFetch(input, init);
       } catch (err) {
         const aborted = init?.signal?.aborted === true;
-        if (
-          aborted ||
-          attempt >= PRE_RESPONSE_CONNECT_RETRIES ||
-          !isRetryableConnectError(err)
-        ) {
+        if (aborted || attempt >= maxRetries || !isRetryableConnectError(err)) {
           throw err;
         }
-        // Brief backoff before the fresh-connection retry.
-        await new Promise((resolve) => setTimeout(resolve, 150 * (attempt + 1)));
+        // Jittered backoff before the fresh-connection retry (anti-thundering-herd).
+        await new Promise((resolve) =>
+          setTimeout(resolve, preResponseBackoffMs(attempt)),
+        );
       }
     }
   }) as typeof fetch;

packages/mcp/build/index.js

@@ -76,6 +76,10 @@ export function createDocmostMcpServer(config) {
         return jsonContent(spaces);
     });
     // Tool: list_pages
+    // INTENTIONAL per-transport divergence (not in the shared registry): this
+    // transport exposes a `tree:true` mode that returns the full nested hierarchy;
+    // the in-app copy keeps the same tree option but is worded for the in-app agent.
+    // Kept per-layer so each side can tune its own guidance.
     server.registerTool("list_pages", {
         description: "List most recent pages in a space ordered by updatedAt (descending). " +
             "Returns a bounded list (default 50, max 100) — use search for lookups " +
@@ -143,6 +147,10 @@ export function createDocmostMcpServer(config) {
         return jsonContent(result);
     });
     // Tool: table_insert_row
+    // NOT in the shared registry: this transport names the table argument `table`,
+    // while the in-app tool names it `tableRef` (ai-chat-tools.service.ts). Sharing
+    // one buildShape would rename a public MCP parameter, so the table row/cell
+    // tools stay per-transport by design.
     server.registerTool("table_insert_row", {
         description: "Insert a row of plain-text cells into a table. `table` = `#<index>` or " +
             "a block id inside it. `cells` = text per column (padded to the table's " +
@@ -159,6 +167,8 @@ export function createDocmostMcpServer(config) {
         return jsonContent(result);
     });
     // Tool: table_delete_row
+    // NOT shared — same `table` (here) vs `tableRef` (in-app) parameter-name
+    // divergence as table_insert_row.
     server.registerTool("table_delete_row", {
         description: "Delete the row at 0-based `index` from a table (`table` = `#<index>` or " +
             "a block id inside it). Refuses to delete the table's only row. An " +
@@ -174,6 +184,8 @@ export function createDocmostMcpServer(config) {
         return jsonContent(result);
     });
     // Tool: table_update_cell
+    // NOT shared — same `table` (here) vs `tableRef` (in-app) parameter-name
+    // divergence as table_insert_row.
     server.registerTool("table_update_cell", {
         description: "Set the plain-text content of cell [row,col] (0-based) in a table " +
             "(`table` = `#<index>` or a block id inside it). Replaces the cell's " +
@@ -317,62 +329,17 @@ export function createDocmostMcpServer(config) {
             },
         };
     });
-    // Tool: patch_node
-    server.registerTool("patch_node", {
-        description: "Replaces a single block identified by its attrs.id WITHOUT resending the " +
-            "whole document. Get the block id from get_page_json, then pass a " +
-            "ProseMirror node to put in its place. Example node: a paragraph " +
-            '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
-            'heading {"type":"heading","attrs":{"level":2},"content":' +
-            '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
-            '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
-            "JSON object or a JSON string (both accepted). Cheaper and safer than " +
-            "update_page_json for one-block structural edits.",
-        inputSchema: {
-            pageId: z.string().min(1),
-            nodeId: z.string().min(1),
-            node: z
-                .any()
-                .describe("ProseMirror node to put in place of the node with this id, e.g. " +
-                '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
-                "JSON object or JSON string both accepted."),
-        },
-    }, async ({ pageId, nodeId, node }) => {
+    // Tool: patch_node — schema + description from the shared registry (identical
+    // across both transports). The execute body keeps its own parseNodeArg
+    // normalization (the model sometimes serializes `node` as a JSON string).
+    registerShared(SHARED_TOOL_SPECS.patchNode, async ({ pageId, nodeId, node }) => {
         const parsedNode = parseNodeArg(node);
         const result = await docmostClient.patchNode(pageId, nodeId, parsedNode);
         return jsonContent(result);
     });
-    // Tool: insert_node
-    server.registerTool("insert_node", {
-        description: "Insert a block before/after another block (by attrs.id or anchor text) " +
-            "or append at the end. Get anchor block ids from get_page_json. Avoids " +
-            "resending the whole document. Can also insert table structure: to add a " +
-            "tableRow, pass a tableRow node with position before/after and anchor " +
-            "INSIDE the target table — anchorNodeId of any block/cell in it, or " +
-            "anchorText matching the table; to add a tableCell/tableHeader, use " +
-            "anchorNodeId of a block inside the target row (anchorText only resolves " +
-            "top-level blocks, so it cannot target a row). `anchorText` is matched " +
-            "against the block's literal rendered plain text (no markdown); " +
-            "markdown/emoji are tolerated as a fallback; prefer plain text or " +
-            "anchorNodeId. Note: append is top-level " +
-            "only and rejects structural table nodes. Example node: a paragraph " +
-            '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
-            'heading {"type":"heading","attrs":{"level":2},"content":' +
-            '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
-            '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
-            "JSON object or a JSON string (both accepted).",
-        inputSchema: {
-            pageId: z.string().min(1),
-            node: z
-                .any()
-                .describe("ProseMirror node to insert, e.g. " +
-                '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
-                "JSON object or JSON string both accepted."),
-            position: z.enum(["before", "after", "append"]),
-            anchorNodeId: z.string().optional(),
-            anchorText: z.string().optional(),
-        },
-    }, async ({ pageId, node, position, anchorNodeId, anchorText }) => {
+    // Tool: insert_node — schema + description from the shared registry. As with
+    // patch_node, the execute body retains parseNodeArg on the incoming node.
+    registerShared(SHARED_TOOL_SPECS.insertNode, async ({ pageId, node, position, anchorNodeId, anchorText }) => {
         const parsedNode = parseNodeArg(node);
         const result = await docmostClient.insertNode(pageId, parsedNode, {
             position,
@@ -453,6 +420,10 @@ export function createDocmostMcpServer(config) {
         return jsonContent(result);
     });
     // Tool: share_page
+    // INTENTIONAL per-transport divergence (not shared): the in-app copy adds a
+    // security-confirmation framing ("only share when the user explicitly asked,
+    // since this exposes the page to anyone with the link") tuned for the in-app
+    // agent; this transport keeps the plain public-URL wording.
     server.registerTool("share_page", {
         description: "Make a page publicly accessible (idempotent) and return its public " +
             "URL. The URL format is <app>/share/<key>/p/<slugId>.",
@@ -539,6 +510,9 @@ export function createDocmostMcpServer(config) {
         return jsonContent(comments);
     });
     // Tool: create_comment
+    // INTENTIONAL per-transport divergence (not shared): the in-app copy tunes the
+    // guidance for the in-app agent (e.g. "retry with a corrected EXACT selection"
+    // and "Reversible via the comment UI"); this transport keeps its own wording.
     server.registerTool("create_comment", {
         description: "Create a new comment on a page. The comment is ALWAYS inline and is " +
             "anchored to (highlights) its `selection` text — there are no page-level " +
@@ -652,6 +626,10 @@ export function createDocmostMcpServer(config) {
         return jsonContent(result);
     });
     // Tool: search
+    // INTENTIONAL per-transport divergence (not shared): the in-app `searchPages`
+    // runs a semantic + keyword hybrid (RRF) with in-process access control and a
+    // different schema (limit 1-20); this transport is a plain REST full-text search
+    // (limit up to 100). Different behaviour AND schema, so kept per-layer.
     server.registerTool("search", {
         description: "Search for pages and content. Results are bounded by `limit` " +
             "(default applied by the client, max 100).",
@@ -672,6 +650,10 @@ export function createDocmostMcpServer(config) {
         return jsonContent(result);
     });
     // Tool: docmost_transform
+    // INTENTIONAL per-transport divergence (not shared): the in-app `transformPage`
+    // deliberately omits the `deleteComments` schema field (comment-deletion
+    // guardrail) and carries a much shorter description; this transport exposes the
+    // full helper catalogue. Different schema, so kept per-layer.
     server.registerTool("docmost_transform", {
         description: "Edit a page by running an arbitrary JS transform `(doc, ctx) => doc` " +
             "against its LIVE ProseMirror document, with a diff preview and page " +

packages/mcp/build/tool-specs.js

@@ -80,6 +80,86 @@ export const SHARED_TOOL_SPECS = {
             nodeId: z.string().min(1),
         }),
     },
+    // --- single-block structural write (patch / insert) ---
+    //
+    // CANONICAL description merges both layers: the MCP copy's "WITHOUT resending
+    // the whole document" + "cheaper/safer than a full-document replace" guidance
+    // AND the in-app copy's "keeps the same node id" + "Reversible via page
+    // history" framing — nothing either side conveyed is dropped. Sibling tools are
+    // named in transport-neutral prose ("the page-JSON view", "a full-document
+    // replace") to match the rest of the registry, since the two layers expose
+    // those siblings under different (snake_case vs camelCase) identifiers.
+    patchNode: {
+        mcpName: 'patch_node',
+        inAppKey: 'patchNode',
+        description: 'Replace a single content block identified by its attrs.id with a new ' +
+            'ProseMirror node, WITHOUT resending the whole document; the replacement ' +
+            'keeps the same node id. Get the block id from the page-JSON view, then ' +
+            'pass a ProseMirror node to put in its place. Example node: a paragraph ' +
+            '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
+            'heading {"type":"heading","attrs":{"level":2},"content":' +
+            '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
+            '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
+            'JSON object or a JSON string (both accepted). Cheaper and safer than ' +
+            'replacing the whole document for one-block structural edits. Reversible: ' +
+            'the previous version is kept in page history.',
+        buildShape: (z) => ({
+            pageId: z.string().min(1).describe('ID of the page containing the block'),
+            nodeId: z
+                .string()
+                .min(1)
+                .describe('attrs.id of the block to replace (from the page outline or ' +
+                'page-JSON view)'),
+            node: z
+                .any()
+                .describe('ProseMirror node to put in place of the node with this id, e.g. ' +
+                '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
+                'JSON object or JSON string both accepted.'),
+        }),
+    },
+    insertNode: {
+        mcpName: 'insert_node',
+        inAppKey: 'insertNode',
+        description: 'Insert a block before/after another block (by attrs.id or anchor text) ' +
+            'or append it at the end (top level). For before/after you MUST provide ' +
+            'EXACTLY ONE of anchorNodeId or anchorText. Get anchor block ids from the ' +
+            'page-JSON view. Avoids resending the whole document. Can also insert ' +
+            'table structure: to add a tableRow, pass a tableRow node with position ' +
+            'before/after and anchor INSIDE the target table — anchorNodeId of any ' +
+            'block/cell in it, or anchorText matching the table; to add a ' +
+            'tableCell/tableHeader, use anchorNodeId of a block inside the target row ' +
+            '(anchorText only resolves top-level blocks, so it cannot target a row). ' +
+            "`anchorText` is matched against the block's literal rendered plain text " +
+            '(no markdown); markdown/emoji are tolerated as a fallback; prefer plain ' +
+            'text or anchorNodeId. Note: append is top-level only and rejects ' +
+            'structural table nodes. Example node: a paragraph ' +
+            '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
+            'heading {"type":"heading","attrs":{"level":2},"content":' +
+            '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
+            '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
+            'JSON object or a JSON string (both accepted). Reversible via page history.',
+        buildShape: (z) => ({
+            pageId: z.string().min(1),
+            node: z
+                .any()
+                .describe('ProseMirror node to insert, e.g. ' +
+                '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
+                'JSON object or JSON string both accepted.'),
+            position: z
+                .enum(['before', 'after', 'append'])
+                .describe('Where to insert relative to the anchor.'),
+            anchorNodeId: z
+                .string()
+                .optional()
+                .describe('Anchor block id (for before/after).'),
+            anchorText: z
+                .string()
+                .optional()
+                .describe("Anchor text fragment (for before/after), matched against the " +
+                "block's literal rendered plain text (no markdown). Markdown/emoji " +
+                'are tolerated as a fallback; prefer plain text or anchorNodeId.'),
+        }),
+    },
     // --- share management ---
     unsharePage: {
         mcpName: 'unshare_page',

packages/mcp/src/index.ts

@@ -105,6 +105,10 @@ export function createDocmostMcpServer(config: DocmostMcpConfig): McpServer {
   });
 
 // Tool: list_pages
+// INTENTIONAL per-transport divergence (not in the shared registry): this
+// transport exposes a `tree:true` mode that returns the full nested hierarchy;
+// the in-app copy keeps the same tree option but is worded for the in-app agent.
+// Kept per-layer so each side can tune its own guidance.
 server.registerTool(
   "list_pages",
   {
@@ -195,6 +199,10 @@ server.registerTool(
 );
 
 // Tool: table_insert_row
+// NOT in the shared registry: this transport names the table argument `table`,
+// while the in-app tool names it `tableRef` (ai-chat-tools.service.ts). Sharing
+// one buildShape would rename a public MCP parameter, so the table row/cell
+// tools stay per-transport by design.
 server.registerTool(
   "table_insert_row",
   {
@@ -222,6 +230,8 @@ server.registerTool(
 );
 
 // Tool: table_delete_row
+// NOT shared — same `table` (here) vs `tableRef` (in-app) parameter-name
+// divergence as table_insert_row.
 server.registerTool(
   "table_delete_row",
   {
@@ -243,6 +253,8 @@ server.registerTool(
 );
 
 // Tool: table_update_cell
+// NOT shared — same `table` (here) vs `tableRef` (in-app) parameter-name
+// divergence as table_insert_row.
 server.registerTool(
   "table_update_cell",
   {
@@ -445,32 +457,11 @@ server.registerTool(
   },
 );
 
-// Tool: patch_node
-server.registerTool(
-  "patch_node",
-  {
-    description:
-      "Replaces a single block identified by its attrs.id WITHOUT resending the " +
-      "whole document. Get the block id from get_page_json, then pass a " +
-      "ProseMirror node to put in its place. Example node: a paragraph " +
-      '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
-      'heading {"type":"heading","attrs":{"level":2},"content":' +
-      '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
-      '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
-      "JSON object or a JSON string (both accepted). Cheaper and safer than " +
-      "update_page_json for one-block structural edits.",
-    inputSchema: {
-      pageId: z.string().min(1),
-      nodeId: z.string().min(1),
-      node: z
-        .any()
-        .describe(
-          "ProseMirror node to put in place of the node with this id, e.g. " +
-            '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
-            "JSON object or JSON string both accepted.",
-        ),
-    },
-  },
+// Tool: patch_node — schema + description from the shared registry (identical
+// across both transports). The execute body keeps its own parseNodeArg
+// normalization (the model sometimes serializes `node` as a JSON string).
+registerShared(
+  SHARED_TOOL_SPECS.patchNode,
   async ({ pageId, nodeId, node }) => {
     const parsedNode = parseNodeArg(node);
     const result = await docmostClient.patchNode(pageId, nodeId, parsedNode);
@@ -478,42 +469,10 @@ server.registerTool(
   },
 );
 
-// Tool: insert_node
-server.registerTool(
-  "insert_node",
-  {
-    description:
-      "Insert a block before/after another block (by attrs.id or anchor text) " +
-      "or append at the end. Get anchor block ids from get_page_json. Avoids " +
-      "resending the whole document. Can also insert table structure: to add a " +
-      "tableRow, pass a tableRow node with position before/after and anchor " +
-      "INSIDE the target table — anchorNodeId of any block/cell in it, or " +
-      "anchorText matching the table; to add a tableCell/tableHeader, use " +
-      "anchorNodeId of a block inside the target row (anchorText only resolves " +
-      "top-level blocks, so it cannot target a row). `anchorText` is matched " +
-      "against the block's literal rendered plain text (no markdown); " +
-      "markdown/emoji are tolerated as a fallback; prefer plain text or " +
-      "anchorNodeId. Note: append is top-level " +
-      "only and rejects structural table nodes. Example node: a paragraph " +
-      '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
-      'heading {"type":"heading","attrs":{"level":2},"content":' +
-      '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
-      '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
-      "JSON object or a JSON string (both accepted).",
-    inputSchema: {
-      pageId: z.string().min(1),
-      node: z
-        .any()
-        .describe(
-          "ProseMirror node to insert, e.g. " +
-            '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
-            "JSON object or JSON string both accepted.",
-        ),
-      position: z.enum(["before", "after", "append"]),
-      anchorNodeId: z.string().optional(),
-      anchorText: z.string().optional(),
-    },
-  },
+// Tool: insert_node — schema + description from the shared registry. As with
+// patch_node, the execute body retains parseNodeArg on the incoming node.
+registerShared(
+  SHARED_TOOL_SPECS.insertNode,
   async ({ pageId, node, position, anchorNodeId, anchorText }) => {
     const parsedNode = parseNodeArg(node);
     const result = await docmostClient.insertNode(pageId, parsedNode, {
@@ -619,6 +578,10 @@ server.registerTool(
 );
 
 // Tool: share_page
+// INTENTIONAL per-transport divergence (not shared): the in-app copy adds a
+// security-confirmation framing ("only share when the user explicitly asked,
+// since this exposes the page to anyone with the link") tuned for the in-app
+// agent; this transport keeps the plain public-URL wording.
 server.registerTool(
   "share_page",
   {
@@ -746,6 +709,9 @@ server.registerTool(
 );
 
 // Tool: create_comment
+// INTENTIONAL per-transport divergence (not shared): the in-app copy tunes the
+// guidance for the in-app agent (e.g. "retry with a corrected EXACT selection"
+// and "Reversible via the comment UI"); this transport keeps its own wording.
 server.registerTool(
   "create_comment",
   {
@@ -911,6 +877,10 @@ server.registerTool(
 );
 
 // Tool: search
+// INTENTIONAL per-transport divergence (not shared): the in-app `searchPages`
+// runs a semantic + keyword hybrid (RRF) with in-process access control and a
+// different schema (limit 1-20); this transport is a plain REST full-text search
+// (limit up to 100). Different behaviour AND schema, so kept per-layer.
 server.registerTool(
   "search",
   {
@@ -937,6 +907,10 @@ server.registerTool(
 );
 
 // Tool: docmost_transform
+// INTENTIONAL per-transport divergence (not shared): the in-app `transformPage`
+// deliberately omits the `deleteComments` schema field (comment-deletion
+// guardrail) and carries a much shorter description; this transport exposes the
+// full helper catalogue. Different schema, so kept per-layer.
 server.registerTool(
   "docmost_transform",
   {

packages/mcp/src/tool-specs.ts

@@ -119,6 +119,98 @@ export const SHARED_TOOL_SPECS = {
     }),
   },
 
+  // --- single-block structural write (patch / insert) ---
+  //
+  // CANONICAL description merges both layers: the MCP copy's "WITHOUT resending
+  // the whole document" + "cheaper/safer than a full-document replace" guidance
+  // AND the in-app copy's "keeps the same node id" + "Reversible via page
+  // history" framing — nothing either side conveyed is dropped. Sibling tools are
+  // named in transport-neutral prose ("the page-JSON view", "a full-document
+  // replace") to match the rest of the registry, since the two layers expose
+  // those siblings under different (snake_case vs camelCase) identifiers.
+  patchNode: {
+    mcpName: 'patch_node',
+    inAppKey: 'patchNode',
+    description:
+      'Replace a single content block identified by its attrs.id with a new ' +
+      'ProseMirror node, WITHOUT resending the whole document; the replacement ' +
+      'keeps the same node id. Get the block id from the page-JSON view, then ' +
+      'pass a ProseMirror node to put in its place. Example node: a paragraph ' +
+      '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
+      'heading {"type":"heading","attrs":{"level":2},"content":' +
+      '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
+      '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
+      'JSON object or a JSON string (both accepted). Cheaper and safer than ' +
+      'replacing the whole document for one-block structural edits. Reversible: ' +
+      'the previous version is kept in page history.',
+    buildShape: (z) => ({
+      pageId: z.string().min(1).describe('ID of the page containing the block'),
+      nodeId: z
+        .string()
+        .min(1)
+        .describe(
+          'attrs.id of the block to replace (from the page outline or ' +
+            'page-JSON view)',
+        ),
+      node: z
+        .any()
+        .describe(
+          'ProseMirror node to put in place of the node with this id, e.g. ' +
+            '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
+            'JSON object or JSON string both accepted.',
+        ),
+    }),
+  },
+
+  insertNode: {
+    mcpName: 'insert_node',
+    inAppKey: 'insertNode',
+    description:
+      'Insert a block before/after another block (by attrs.id or anchor text) ' +
+      'or append it at the end (top level). For before/after you MUST provide ' +
+      'EXACTLY ONE of anchorNodeId or anchorText. Get anchor block ids from the ' +
+      'page-JSON view. Avoids resending the whole document. Can also insert ' +
+      'table structure: to add a tableRow, pass a tableRow node with position ' +
+      'before/after and anchor INSIDE the target table — anchorNodeId of any ' +
+      'block/cell in it, or anchorText matching the table; to add a ' +
+      'tableCell/tableHeader, use anchorNodeId of a block inside the target row ' +
+      '(anchorText only resolves top-level blocks, so it cannot target a row). ' +
+      "`anchorText` is matched against the block's literal rendered plain text " +
+      '(no markdown); markdown/emoji are tolerated as a fallback; prefer plain ' +
+      'text or anchorNodeId. Note: append is top-level only and rejects ' +
+      'structural table nodes. Example node: a paragraph ' +
+      '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]} or a ' +
+      'heading {"type":"heading","attrs":{"level":2},"content":' +
+      '[{"type":"text","text":"Title"}]}. Bold is a mark: ' +
+      '{"type":"text","text":"x","marks":[{"type":"bold"}]}. The node may be a ' +
+      'JSON object or a JSON string (both accepted). Reversible via page history.',
+    buildShape: (z) => ({
+      pageId: z.string().min(1),
+      node: z
+        .any()
+        .describe(
+          'ProseMirror node to insert, e.g. ' +
+            '{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}. ' +
+            'JSON object or JSON string both accepted.',
+        ),
+      position: z
+        .enum(['before', 'after', 'append'])
+        .describe('Where to insert relative to the anchor.'),
+      anchorNodeId: z
+        .string()
+        .optional()
+        .describe('Anchor block id (for before/after).'),
+      anchorText: z
+        .string()
+        .optional()
+        .describe(
+          "Anchor text fragment (for before/after), matched against the " +
+            "block's literal rendered plain text (no markdown). Markdown/emoji " +
+            'are tolerated as a fallback; prefer plain text or anchorNodeId.',
+        ),
+    }),
+  },
+
   // --- share management ---
 
   unsharePage: {

packages/mcp/test/unit/tool-specs.test.mjs

@@ -83,6 +83,63 @@ test("getNode builder produces exactly { pageId, nodeId }", () => {
   assert.deepEqual(Object.keys(shape).sort(), ["nodeId", "pageId"]);
 });
 
+test("patchNode spec exists, merges BOTH descriptions, builds { pageId, nodeId, node }", () => {
+  const spec = SHARED_TOOL_SPECS.patchNode;
+  assert.ok(spec, "patchNode spec missing");
+  assert.equal(spec.mcpName, "patch_node");
+  assert.equal(spec.inAppKey, "patchNode");
+
+  // The canonical description must carry the key guidance from BOTH originals:
+  //  - MCP-only: "WITHOUT resending the whole document" + the cheaper/safer note.
+  //  - in-app-only: "keeps the same node id" + the "Reversible ... page history"
+  //    framing the MCP copy lacked.
+  assert.match(spec.description, /WITHOUT resending the whole document/);
+  assert.match(spec.description, /Cheaper and safer/);
+  assert.match(spec.description, /keeps the same node id/i);
+  assert.match(spec.description, /Reversible/i);
+  assert.match(spec.description, /page history/i);
+
+  const shape = spec.buildShape(z);
+  assert.deepEqual(Object.keys(shape).sort(), ["node", "nodeId", "pageId"]);
+  // A minimal valid input parses (node accepts an arbitrary object via z.any()).
+  const parsed = z.object(shape).parse({
+    pageId: "p1",
+    nodeId: "n1",
+    node: { type: "paragraph" },
+  });
+  assert.equal(parsed.pageId, "p1");
+  assert.equal(parsed.nodeId, "n1");
+});
+
+test("insertNode spec exists, merges BOTH descriptions, builds the full anchor shape", () => {
+  const spec = SHARED_TOOL_SPECS.insertNode;
+  assert.ok(spec, "insertNode spec missing");
+  assert.equal(spec.mcpName, "insert_node");
+  assert.equal(spec.inAppKey, "insertNode");
+
+  // Canonical description must keep BOTH sides' nuance:
+  //  - in-app-only: "EXACTLY ONE of anchorNodeId or anchorText" + "Reversible".
+  //  - MCP-only: the table-structure (tableRow/tableCell) insertion guidance.
+  assert.match(spec.description, /EXACTLY ONE of anchorNodeId or anchorText/);
+  assert.match(spec.description, /tableRow/);
+  assert.match(spec.description, /append is top-level only/);
+  assert.match(spec.description, /Reversible via page history/);
+
+  const shape = spec.buildShape(z);
+  assert.deepEqual(
+    Object.keys(shape).sort(),
+    ["anchorNodeId", "anchorText", "node", "pageId", "position"],
+  );
+  // before/after/append are the only accepted positions; anchors are optional.
+  const schema = z.object(shape);
+  assert.doesNotThrow(() =>
+    schema.parse({ pageId: "p1", node: { type: "paragraph" }, position: "append" }),
+  );
+  assert.throws(() =>
+    schema.parse({ pageId: "p1", node: {}, position: "sideways" }),
+  );
+});
+
 test("no-arg specs (getWorkspace/listSpaces/listShares) omit buildShape", () => {
   for (const key of ["getWorkspace", "listSpaces", "listShares"]) {
     assert.equal(SHARED_TOOL_SPECS[key].buildShape, undefined, `${key} should be no-arg`);