mixdog 1.3.5 → 1.4.0

package/src/runtime/agent/orchestrator/runtime-core/deferred-tool-delta.mjs

@@ -1,4 +1,6 @@
 import { clean } from './session-text.mjs';
+import { parseMcpToolName } from '../../../shared/tool-primitives.mjs';
+import { mcpServerLines } from '../context/deferred-tools.mjs';
 
 function compactDescription(value) {
   return String(value || '')
@@ -8,23 +10,36 @@ function compactDescription(value) {
     .slice(0, 240);
 }
 
+function addedEntry(entry) {
+  const name = clean(entry?.name);
+  return name ? { name, description: compactDescription(entry?.description) } : null;
+}
+
 function normalizedDelta(value) {
   const source = value && typeof value === 'object' ? value : {};
   const addedByName = new Map();
   for (const entry of Array.isArray(source.added) ? source.added : []) {
-    const name = clean(entry?.name);
-    if (name) addedByName.set(name, { name, description: compactDescription(entry?.description) });
+    const added = addedEntry(entry);
+    if (added) addedByName.set(added.name, added);
   }
-  const removed = new Set(
-    (Array.isArray(source.removed) ? source.removed : [])
-      .map((entry) => clean(typeof entry === 'string' ? entry : entry?.name))
-      .filter(Boolean)
+  const removed = new Set();
+  // Removed tool name → its server, for removals that came with one.
+  const removedServers = new Map(
+    Object.entries(source.removedServers && typeof source.removedServers === 'object' ? source.removedServers : {})
   );
+  for (const entry of Array.isArray(source.removed) ? source.removed : []) {
+    const name = clean(typeof entry === 'string' ? entry : entry?.name);
+    if (!name) continue;
+    removed.add(name);
+    if (typeof entry === 'object' && clean(entry?.server)) removedServers.set(name, clean(entry.server));
+  }
   for (const name of addedByName.keys()) removed.delete(name);
+  for (const name of [...removedServers.keys()]) if (!removed.has(name)) removedServers.delete(name);
   return {
     revision: Math.max(0, Number(source.revision) || 0),
     addedByName,
     removed,
+    removedServers,
   };
 }
 
@@ -33,19 +48,20 @@ export function mergePendingDeferredToolDelta(session, change = {}) {
   const current = normalizedDelta(session.pendingDeferredToolDelta);
   const nextRevision = Math.max(current.revision, Math.max(0, Number(session.deferredToolDeltaRevision) || 0)) + 1;
   for (const entry of Array.isArray(change.added) ? change.added : []) {
-    const name = clean(entry?.name);
-    if (!name) continue;
-    if (current.removed.delete(name)) continue;
-    current.addedByName.set(name, {
-      name,
-      description: compactDescription(entry?.description),
-    });
+    const added = addedEntry(entry);
+    if (!added) continue;
+    if (current.removed.delete(added.name)) {
+      current.removedServers.delete(added.name);
+      continue;
+    }
+    current.addedByName.set(added.name, added);
   }
   for (const entry of Array.isArray(change.removed) ? change.removed : []) {
     const name = clean(typeof entry === 'string' ? entry : entry?.name);
     if (!name) continue;
     if (current.addedByName.delete(name)) continue;
     current.removed.add(name);
+    if (typeof entry === 'object' && clean(entry?.server)) current.removedServers.set(name, clean(entry.server));
   }
   const added = [...current.addedByName.values()].sort((a, b) => a.name.localeCompare(b.name));
   const removed = [...current.removed].sort();
@@ -61,27 +77,88 @@ export function mergePendingDeferredToolDelta(session, change = {}) {
     revision: nextRevision,
     added,
     removed,
+    ...(current.removedServers.size
+      ? { removedServers: Object.fromEntries([...current.removedServers].sort(([a], [b]) => a.localeCompare(b))) }
+      : {}),
   };
   session.updatedAt = Date.now();
   return session.pendingDeferredToolDelta;
 }
 
+// MCP changes render one line per affected server, like the BP2 manifest; the tool-level sets stay exact in the snapshot for acknowledgement.
+// A tool's server comes from the session's catalog definitions (an added
+// tool) or the server recorded when it was removed; only a name neither knows
+// falls back to the recorded/`mcp__<server>__<tool>` parse. Other tools are
+// listed one by one.
+function deltaLines(session, added, removed, removedServers) {
+  const catalogServer = new Map();
+  for (const key of ['deferredToolCatalog', 'deferredLateToolCatalog', 'tools']) {
+    for (const tool of Array.isArray(session?.[key]) ? session[key] : []) {
+      const name = clean(tool?.name);
+      const server = name && parseMcpToolName(tool)?.server;
+      if (server) catalogServer.set(name, server);
+    }
+  }
+  const serverOf = (name, hint) => hint || catalogServer.get(name) || parseMcpToolName(name)?.server || '';
+  const items = [];
+
+  const addedServers = new Map();
+  for (const entry of added) {
+    const server = serverOf(entry.name);
+    if (!server) {
+      items.push({
+        label: entry.name,
+        line: entry.description ? `- ${entry.name}: ${entry.description}` : `- ${entry.name}`,
+      });
+    } else if (addedServers.has(server)) addedServers.get(server).push(entry);
+    else addedServers.set(server, [entry]);
+  }
+  const addedLines = mcpServerLines(addedServers, session?.mcpServerInstructions);
+  for (const line of addedLines) items.push({ label: line.label, line: `- ${line.label}: ${line.trigger}` });
+  // A server whose name cannot be listed safely is listed by its tools.
+  const listed = new Set(addedLines.map((line) => line.label));
+  for (const [server, entries] of addedServers) {
+    if (listed.has(`mcp__${server}`)) continue;
+    for (const entry of entries) items.push({ label: entry.name, line: `- ${entry.name}` });
+  }
+
+  const connected = Array.isArray(session?.deferredMcpToolNames) ? session.deferredMcpToolNames : null;
+  const liveServers = new Set((connected || []).map((name) => serverOf(clean(name))).filter(Boolean));
+  const removedByServer = new Map();
+  const removedItems = [];
+  for (const name of removed) {
+    const server = serverOf(name, removedServers.get(name));
+    if (!server) {
+      removedItems.push({ label: name, line: `- ${name}` });
+      continue;
+    }
+    if (removedByServer.has(server)) removedByServer.get(server).push(name);
+    else removedByServer.set(server, [name]);
+  }
+  // Gone only when the connected set is known and none of its tools is left.
+  for (const [server, names] of removedByServer) {
+    const label = `mcp__${server}`;
+    const gone = connected && !liveServers.has(server);
+    const plural = names.length === 1 ? '' : 's';
+    removedItems.push({
+      label,
+      line: gone ? `- ${label}` : `- ${label}: ${names.length} tool${plural} removed`,
+    });
+  }
+
+  const render = (list) => list.sort((a, b) => a.label.localeCompare(b.label)).map((item) => item.line);
+  return { added: render(items), removed: render(removedItems) };
+}
+
 export function snapshotPendingDeferredToolDelta(session) {
   const current = normalizedDelta(session?.pendingDeferredToolDelta);
   const added = [...current.addedByName.values()].sort((a, b) => a.name.localeCompare(b.name));
   const removed = [...current.removed].sort();
   if (!added.length && !removed.length) return null;
+  const rendered = deltaLines(session, added, removed, current.removedServers);
   const lines = ['<system-reminder>', '<deferred_tools_delta>'];
-  if (added.length) {
-    lines.push('Added deferred tools:');
-    for (const entry of added) {
-      lines.push(entry.description ? `- ${entry.name}: ${entry.description}` : `- ${entry.name}`);
-    }
-  }
-  if (removed.length) {
-    lines.push('Removed deferred tools:');
-    for (const name of removed) lines.push(`- ${name}`);
-  }
+  if (rendered.added.length) lines.push('Added deferred tools:', ...rendered.added);
+  if (rendered.removed.length) lines.push('Removed deferred tools:', ...rendered.removed);
   lines.push('</deferred_tools_delta>', '</system-reminder>');
   return {
     revision: current.revision,

package/src/runtime/agent/orchestrator/runtime-core/session-text.mjs

@@ -2,6 +2,7 @@
 import { clean } from '../../../shared/clean.mjs';
 import { stripInjectedBlocks } from '../../../shared/injected-display-text.mjs';
 import { CONTROL_MARKER_RE } from '../../../shared/tool-execution-contract.mjs';
+import { isRoutineQuietReply } from '../../../shared/routine-trigger.mjs';
 
 export function sessionMessageText(content) {
   if (content == null) return '';
@@ -69,6 +70,7 @@ export function isSessionPreviewNoise(text) {
   const value = String(text || '').trim();
   return (
     !value ||
+    isRoutineQuietReply(value) ||
     isSyntheticSessionText(value) ||
     !cleanSessionPreview(value) ||
     isLateToolAnnouncement(value) ||

package/src/runtime/agent/orchestrator/runtime-core/tool-bridge.mjs

@@ -26,7 +26,7 @@ import { providerToolExclusionReason, routeToolExclusionReason } from '../sessio
 
 export { isToolBridgeEnabled } from './tool-exposure.mjs';
 
-export const BRIDGE_LOAD_TOOL_NAME = 'load_tool';
+const BRIDGE_LOAD_TOOL_NAME = 'load_tool';
 export const BRIDGE_CALL_TOOL_NAME = 'call_tool';
 const DESCRIBE_MAX_NAMES = 8;
 // Most definitions one request resolves to: every name an alias of the widest
@@ -344,7 +344,9 @@ function largestChunk(text, offset, buildPage) {
   return low;
 }
 
-export function describeBridgeTools(session, args = {}, { mode } = {}) {
+// `instructionsFor(names)` (pure) returns the MCP instruction text the page
+// carries for those entries, counted inside the result budget.
+export function describeBridgeTools(session, args = {}, { mode, instructionsFor } = {}) {
   const syntaxHint = ' Use load_tool {"names":["exact_tool_name"]}; the required key is names, not name.';
   const invalid = unknownKeysError(args, DESCRIBE_KEYS, BRIDGE_LOAD_TOOL_NAME);
   if (invalid) {
@@ -409,11 +411,16 @@ export function describeBridgeTools(session, args = {}, { mode } = {}) {
   }
   const entries = [];
   const reserve = { names: reserveContinuation(docs.length, available.length) };
+  const instructionsOf = (list) => {
+    const text = instructionsFor?.(list.map((entry) => entry.name)) || '';
+    return text ? { mcpInstructions: text } : {};
+  };
   const page = (extra) => ({
     entries: [...entries, extra],
     missing,
     blocked,
     ...found,
+    ...instructionsOf([...entries, extra]),
     note: DESCRIBE_NOTE,
     continueWith: reserve,
   });
@@ -431,7 +438,15 @@ export function describeBridgeTools(session, args = {}, { mode } = {}) {
       // A document that fits on a page of its own starts the next page whole.
       if (
         entries.length &&
-        fits({ entries: [whole], missing, blocked, ...found, note: DESCRIBE_NOTE, continueWith: reserve })
+        fits({
+          entries: [whole],
+          missing,
+          blocked,
+          ...found,
+          ...instructionsOf([whole]),
+          note: DESCRIBE_NOTE,
+          continueWith: reserve,
+        })
       ) {
         nextPosition = [entryIndex, 0];
         break;
@@ -464,7 +479,7 @@ export function describeBridgeTools(session, args = {}, { mode } = {}) {
       'the remaining definitions cannot be continued; describe fewer tools at once.'
     );
   }
-  return { entries, missing, blocked, ...found, note: DESCRIBE_NOTE, continueWith };
+  return { entries, missing, blocked, ...found, ...instructionsOf(entries), note: DESCRIBE_NOTE, continueWith };
 }
 
 // ---------------------------------------------------------------------------

package/src/runtime/agent/orchestrator/runtime-core/tool-catalog.mjs

@@ -4,7 +4,11 @@
 import { clean } from './session-text.mjs';
 import { mergePendingDeferredToolDelta } from './deferred-tool-delta.mjs';
 import { applyInitialDeferredToolManifestToBp2 } from '../context/collect.mjs';
-import { listedDeferredToolNames } from '../context/deferred-tools.mjs';
+import {
+  listedDeferredToolNames,
+  mcpServerManifestLabel,
+  sanitizeMcpInstructionText,
+} from '../context/deferred-tools.mjs';
 import { parseMcpToolName } from '../../../shared/tool-primitives.mjs';
 import { getMcpServerInstructionsMap, getMcpTools, getMcpToolGeneration } from '../mcp/client.mjs';
 import { filterMcpToolsForSession } from './extension-scopes.mjs';
@@ -380,10 +384,35 @@ export function applyDeferredToolSurface(session, mode, extraTools = [], options
       session.deferredDiscoveredTools || []
     );
   }
+  const catalog = surfaceCatalog(session, extraTools, options);
+  const defaultNames = surfaceDefaultNames(session, catalog, mode);
+  const selected = new Set(surfaceSelectedNames(session, catalog, defaultNames, providerMode, bridge));
+  session.deferredToolCatalog = catalog;
+  session.deferredToolUsage = MEASURED_TOOL_USAGE;
+  session.deferredDefaultTools = sortedNamesByMeasuredUsage(defaultNames);
+  session.deferredProviderMode = providerMode;
+  session.deferredNativeTools = providerMode === 'native';
+  session.deferredSurfaceMode = mode;
+  const active = installSurfaceTools(session, catalog, selected, mode, bridge);
+  session.deferredCallableTools = sortedNamesByMeasuredUsage(active);
+  if (providerMode === 'native') {
+    const restored = previousExposure === TOOL_EXPOSURE_BRIDGE ? session.nativeDeferredDiscovery || [] : [];
+    delete session.nativeDeferredDiscovery;
+    const discovered = canonicalDeferredToolNames(catalog, [...(session.deferredDiscoveredTools || []), ...restored]);
+    session.deferredSelectedTools = active;
+    session.deferredDiscoveredTools = discovered.filter((name) => !selected.has(name));
+  } else {
+    setDeferredToolState(session, active);
+  }
+  refreshSurfaceManifest(session, exposureChanged);
+  return session;
+}
+
+// The surface's catalog, rebuilt from the full catalog, not just its eager
+// projection. Current definitions still take precedence over retained
+// definitions. Bridge definitions belong to the exposure, never to the catalog.
+function surfaceCatalog(session, extraTools, options) {
   const byName = new Map();
-  // Rebuild from the full catalog, not just its eager projection. Current
-  // definitions still take precedence over retained definitions. Bridge
-  // definitions belong to the exposure, never to the catalog.
   const candidates = filterDisallowedTools(
     filterModelEditTools(
       [...session.tools, ...(extraTools || []), ...deferredCatalogUnion(session)].filter(
@@ -398,7 +427,11 @@ export function applyDeferredToolSurface(session, mode, extraTools = [], options
     if (!name || byName.has(name)) continue;
     byName.set(name, activeToolForSurface(tool));
   }
-  const catalog = sortedCatalogByMeasuredUsage([...byName.values()]);
+  return sortedCatalogByMeasuredUsage([...byName.values()]);
+}
+
+// The mode's eager tools in `catalog`, less those the session keeps loadable.
+function surfaceDefaultNames(session, catalog, mode) {
   const defaultNames = defaultDeferredToolNames(catalog, mode);
   // Solo keeps `agent` in the deferred pool: loadable on request, never eager.
   // The mode the prompt was built with: a mid-conversation workflow or
@@ -413,19 +446,24 @@ export function applyDeferredToolSurface(session, mode, extraTools = [], options
   for (const name of Array.isArray(session.workflowOpenedTools) ? session.workflowOpenedTools : []) {
     defaultNames.delete(name);
   }
+  return defaultNames;
+}
+
+// The names the surface selects: the session's stored selection, else the
+// defaults.
+function surfaceSelectedNames(session, catalog, defaultNames, providerMode, bridge) {
   // Bridge sessions expose the mode's core only: a stored (legacy all-selected)
   // selection never widens the wire surface, and load_tool is the bridge's own.
   const storedNames = providerMode === 'native' || bridge ? [] : storedDeferredToolNames(session);
   let selectedNames = storedNames.length ? canonicalDeferredToolNames(catalog, storedNames) : [];
   if (!selectedNames.length || providerMode === 'native') selectedNames = sortedNamesByMeasuredUsage(defaultNames);
   if (bridge) selectedNames = selectedNames.filter((name) => name !== 'load_tool');
-  const selected = new Set(selectedNames);
-  session.deferredToolCatalog = catalog;
-  session.deferredToolUsage = MEASURED_TOOL_USAGE;
-  session.deferredDefaultTools = sortedNamesByMeasuredUsage(defaultNames);
-  session.deferredProviderMode = providerMode;
-  session.deferredNativeTools = providerMode === 'native';
-  session.deferredSurfaceMode = mode;
+  return selectedNames;
+}
+
+// Replace `session.tools` with the selected definitions (plus the bridge's
+// own) and record the exposure; returns the active tool names.
+function installSurfaceTools(session, catalog, selected, mode, bridge) {
   session.tools.length = 0;
   const active = [];
   for (const tool of catalog) {
@@ -439,16 +477,12 @@ export function applyDeferredToolSurface(session, mode, extraTools = [], options
   if (bridge && catalog.length) session.tools.push(...BRIDGE_SURFACE_TOOLS);
   if (bridge) session.toolExposureMode = TOOL_EXPOSURE_BRIDGE;
   else delete session.toolExposureMode;
-  session.deferredCallableTools = sortedNamesByMeasuredUsage(active);
-  if (providerMode === 'native') {
-    const restored = previousExposure === TOOL_EXPOSURE_BRIDGE ? session.nativeDeferredDiscovery || [] : [];
-    delete session.nativeDeferredDiscovery;
-    const discovered = canonicalDeferredToolNames(catalog, [...(session.deferredDiscoveredTools || []), ...restored]);
-    session.deferredSelectedTools = active;
-    session.deferredDiscoveredTools = discovered.filter((name) => !selected.has(name));
-  } else {
-    setDeferredToolState(session, active);
-  }
+  return active;
+}
+
+// Keep the system prompt's fixed deferred-tool block (BP2) and the announced
+// set in step with the surface.
+function refreshSurfaceManifest(session, exposureChanged) {
   if (exposureChanged && session.messages?.some((m) => m?.role === 'system')) {
     // Replace the previous exposure's fixed block once: the native deferred
     // manifest, or the bridge roster + guidance. History stays as is.
@@ -473,7 +507,6 @@ export function applyDeferredToolSurface(session, mode, extraTools = [], options
     // the startup pool.
     session.deferredAnnouncedTools = deferredPoolToolNames(session);
   }
-  return session;
 }
 
 export function rebuildDeferredToolSurfaceForProvider(session, provider) {
@@ -669,9 +702,8 @@ function reconcileDeferredMcpToolCatalogUncached(session, liveMcpTools) {
   const lateCatalog = Array.isArray(session.deferredLateToolCatalog) ? session.deferredLateToolCatalog : [];
   // A bridge session judges a removal by the definition it had before this
   // reconciliation (a disconnected late tool leaves the late pool below).
-  const knownBefore = isToolBridgeEnabled(session)
-    ? new Map(deferredCatalogUnion(session).map((tool) => [clean(tool?.name), tool]))
-    : null;
+  const catalogBefore = new Map(deferredCatalogUnion(session).map((tool) => [clean(tool?.name), tool]));
+  const knownBefore = isToolBridgeEnabled(session) ? catalogBefore : null;
   const active = persistentToolSurfaceNames(session);
 
   const liveMcpByName = new Map();
@@ -723,12 +755,14 @@ function reconcileDeferredMcpToolCatalogUncached(session, liveMcpTools) {
   for (const name of previousNames) {
     if (nextNames.has(name)) continue;
     if (knownBefore && !rosterPermits(session, knownBefore.get(name) || { name })) continue;
-    removed.push(name);
+    // The server comes from the definition the session had, so a shortened
+    // name never has to be parsed.
+    removed.push({ name, server: parseMcpToolName(catalogBefore.get(name) || name)?.server || '' });
   }
   if (!added.length && !removed.length) return null;
   mergePendingDeferredToolDelta(session, { added, removed });
   session.updatedAt = Date.now();
-  return [...added.map((entry) => entry.name), ...removed];
+  return [...added, ...removed].map((entry) => entry.name);
 }
 
 /**
@@ -742,6 +776,9 @@ function reconcileDeferredMcpToolCatalogUncached(session, liveMcpTools) {
  * Returns the re-armed names, or null when there are none.
  */
 export function rearmLateDeferredTools(session) {
+  // The compaction also drops the load results that carried a server's
+  // instruction text, so the next load of its tools delivers it again.
+  if (session) delete session.mcpInstructionsAnnounced;
   if (!session || !Array.isArray(session.tools) || fixedSurfaceSession(session)) return null;
   if (!Array.isArray(session.deferredMcpToolNames) || !Array.isArray(session.deferredAnnouncedTools)) return null;
   // Listed in the boot manifest, or already loaded/discovered: still visible.
@@ -797,7 +834,8 @@ export function selectDeferredTools(session, names, mode, { exact = false } = {}
         const key = clean(raw);
         if (byName.has(key) || byName.has(key.toLowerCase())) return [key];
         const members = mcpServerSelection(catalog, key).map((tool) => clean(tool?.name));
-        return members.length ? members : [key];
+        if (members.length) return members;
+        return [key];
       });
   for (const rawName of new Set(requested)) {
     const requestedName = clean(rawName);
@@ -878,14 +916,67 @@ function resolvableCatalog(session) {
   return filterSessionToolPolicy(tools, session);
 }
 
+// A server's instruction text rides the first load_tool naming any of its
+// tools (loaded now, already active, or described on the bridge), once until
+// compaction (`mcpInstructionsAnnounced`; rearmLateDeferredTools clears it with
+// the transcript that held the text): `## <server>` + body, sanitized and
+// capped like the BP2 block it replaces. No text, nothing sent or recorded.
+function pendingMcpInstructions(session, catalog, names) {
+  const map = session?.mcpServerInstructions;
+  if (!map || typeof map !== 'object' || !names.length) return [];
+  const byName = new Map(catalog.map((tool) => [clean(tool?.name), tool]));
+  const announced = new Set(Array.isArray(session.mcpInstructionsAnnounced) ? session.mcpInstructionsAnnounced : []);
+  const pending = [];
+  for (const name of names) {
+    const server = parseMcpToolName(byName.get(name) || name)?.server;
+    if (!server || announced.has(server) || !mcpServerManifestLabel(server)) continue;
+    const text = sanitizeMcpInstructionText(map[server]);
+    if (!text) continue;
+    announced.add(server);
+    pending.push({ server, block: `## ${server}\n${text}` });
+  }
+  return pending;
+}
+
+function announceMcpServers(session, pending) {
+  if (!pending.length) return;
+  session.mcpInstructionsAnnounced = [
+    ...new Set([...(session.mcpInstructionsAnnounced || []), ...pending.map((entry) => entry.server)]),
+  ];
+}
+
+function claimMcpServerInstructions(session, catalog, names) {
+  const pending = pendingMcpInstructions(session, catalog, names);
+  announceMcpServers(session, pending);
+  return pending.map((entry) => entry.block).join('\n');
+}
+
 // Pure loader. Input is exact deferred-tool names/aliases; output reports
 // loaded / already-active / missing / blocked tools PLUS pending/failed MCP
 // servers. No listing, no ranking, no substring filter. `options.mcpStatus` is
 // the runtime getter for per-server status.
 export function renderToolSearch(args = {}, session, mode = 'full', options = {}) {
   // Bridge mode: load_tool describes (bounded, paged) and never loads.
-  if (isToolBridgeEnabled(session)) return formatBridgeResult(describeBridgeTools(session, args, { mode }));
   const catalog = resolvableCatalog(session);
+  if (isToolBridgeEnabled(session)) {
+    // The page counts the instruction text inside its size budget; only the
+    // servers whose text made it into the returned page are marked announced.
+    const pendingFor = (names) => pendingMcpInstructions(session, catalog, names);
+    const described = describeBridgeTools(session, args, {
+      mode,
+      instructionsFor: (names) =>
+        pendingFor(names)
+          .map((entry) => entry.block)
+          .join('\n'),
+    });
+    if (!described.error && described.mcpInstructions) {
+      announceMcpServers(
+        session,
+        pendingFor((described.entries || []).map((entry) => clean(entry?.name)).filter(Boolean))
+      );
+    }
+    return formatBridgeResult(described);
+  }
   const requestedNames = parseToolSelection(args.names);
   const { pending: pendingMcpServers, failed: failedMcpServers } = pendingAndFailedMcpServers(options?.mcpStatus);
   const mcpFields = {
@@ -955,11 +1046,15 @@ export function renderToolSearch(args = {}, session, mode = 'full', options = {}
   if (missing.length && failedMcpServers.length) {
     notes.push('Some requested names may belong to a failed MCP server; those tools are unavailable.');
   }
+  // Tools the session already had active (loaded before, or eager) count too:
+  // their server's text may never have been delivered.
+  const mcpInstructions = claimMcpServerInstructions(session, catalog, [...loaded, ...alreadyActive]);
   return JSON.stringify(
     {
       // `selected` retained for back-compat consumers (mode is always 'select').
       selected: { mode: 'select', tools: toolSelection },
       ...(nativeToolSearch ? { nativeToolSearch } : {}),
+      ...(mcpInstructions ? { mcpInstructions } : {}),
       loaded,
       alreadyActive,
       ...(alreadyActiveSchemas.length ? { alreadyActiveSchemas } : {}),