@dotdrelle/wiki-manager 0.15.29 → 0.15.34

package/src/core/mcp.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { managerEnvFile, managerMcpEndpointsFile, readEnvFile } from './env.js';
 
-const WIKI_MANAGER_VERSION = '0.15.29';
+const WIKI_MANAGER_VERSION = '0.15.34';
 
 function envValue(key) {
   const filePath = managerEnvFile();
@@ -263,69 +263,122 @@ async function listMcpTools(endpoint) {
   return payload?.result?.tools ?? [];
 }
 
+// Streamable HTTP sessions are server-memory state that outlives the endpoint
+// objects: buildMcpStatus() rebuilds those from the endpoints file on every
+// refresh, so a session cached on the object itself would be thrown away and
+// re-negotiated on each call. Key the cache by transport identity (URL + the
+// credentials actually presented) so a token rotation or a URL change never
+// reuses a session negotiated under the previous identity.
+// Values are promises, not ids: several tool calls to the same agent can race
+// on a cold endpoint, and one handshake must serve them all instead of opening
+// (and leaking) a session per caller.
+const mcpSessions = new Map();
+
+function sessionKey(endpoint) {
+  return JSON.stringify([
+    endpoint.url,
+    endpoint.token ?? null,
+    Object.entries(endpoint.headers ?? {}).sort(),
+  ]);
+}
+
+// The MCP Streamable HTTP spec makes `initialize` mandatory before any other
+// request, and a stateful server is entitled to reject a cold `tools/list`.
+// Servers word that rejection however their SDK likes — "No valid session"
+// (Node SDK), "Missing session ID" (Python SDK), "Session not found" — so we
+// never parse the prose. We negotiate the session up front and, if the server
+// later revokes it, we re-negotiate on any 400/404 and replay once.
+function openMcpSession(endpoint, key, requestSignal, headersFor) {
+  const pending = negotiateMcpSession(endpoint, requestSignal, headersFor);
+  // Cache the promise immediately so a concurrent caller joins this handshake.
+  // Drop it on failure, otherwise every later call would replay the rejection.
+  mcpSessions.set(key, pending);
+  pending.catch(() => {
+    if (mcpSessions.get(key) === pending) mcpSessions.delete(key);
+  });
+  return pending;
+}
+
+async function negotiateMcpSession(endpoint, requestSignal, headersFor) {
+  const response = await fetch(endpoint.url, {
+    method: 'POST',
+    signal: requestSignal,
+    headers: headersFor(null),
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: 0,
+      method: 'initialize',
+      params: {
+        protocolVersion: '2025-06-18',
+        capabilities: {},
+        clientInfo: { name: 'wiki-manager', version: WIKI_MANAGER_VERSION },
+      },
+    }),
+  });
+  const text = await response.text();
+  if (!response.ok) {
+    throw new Error(`initialize failed: ${response.status} ${text.slice(0, 160)}`.trim());
+  }
+  // A stateless server completes `initialize` without issuing a session id and
+  // then serves every later request unsessioned. That is valid: remember the
+  // absence so we do not re-handshake before each call.
+  const sessionId = response.headers.get('mcp-session-id') ?? null;
+  if (sessionId) {
+    // Notification, not a request: the server owes no response, and blocking
+    // the caller on it would add a round-trip to every cold start.
+    fetch(endpoint.url, {
+      method: 'POST',
+      headers: headersFor(sessionId),
+      body: JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} }),
+    }).catch(() => {});
+  }
+  return sessionId;
+}
+
 async function mcpRequest(endpoint, method, params, signal, options = {}) {
   if (!endpoint.url) throw new Error('missing endpoint URL');
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 8000);
   const requestSignal = signal ? AbortSignal.any([controller.signal, signal]) : controller.signal;
+  const key = sessionKey(endpoint);
 
-  const buildHeaders = () => {
+  const headersFor = (sessionId) => {
     const h = {
       accept: 'application/json, text/event-stream',
       'content-type': 'application/json',
       ...(endpoint.headers ?? {}),
     };
     if (endpoint.token) h.authorization = `Bearer ${endpoint.token}`;
-    if (endpoint._sessionId) h['mcp-session-id'] = endpoint._sessionId;
+    if (sessionId) h['mcp-session-id'] = sessionId;
     return h;
   };
 
-  const doRequest = async (m, p) => {
+  const doRequest = async (sessionId) => {
     const response = await fetch(endpoint.url, {
       method: 'POST',
       signal: requestSignal,
-      headers: buildHeaders(),
-      body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: m, params: p }),
+      headers: headersFor(sessionId),
+      body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
     });
+    // Some servers rotate the session id mid-stream; always take the latest.
     const sid = response.headers.get('mcp-session-id');
-    if (sid) endpoint._sessionId = sid;
+    if (sid && sid !== sessionId) mcpSessions.set(key, Promise.resolve(sid));
     return response;
   };
 
   try {
-    let response = await doRequest(method, params);
+    const session = mcpSessions.get(key)
+      ?? openMcpSession(endpoint, key, requestSignal, headersFor);
+    let response = await doRequest(await session);
     let text = await response.text();
 
-    if (response.status === 400 && /session(?:\s+ID)?/i.test(text)) {
-      endpoint._sessionId = null;
-      const initResponse = await fetch(endpoint.url, {
-        method: 'POST',
-        signal: requestSignal,
-        headers: buildHeaders(),
-        body: JSON.stringify({
-          jsonrpc: '2.0',
-          id: 0,
-          method: 'initialize',
-          params: {
-            protocolVersion: '2025-06-18',
-            capabilities: {},
-            clientInfo: { name: 'wiki-manager', version: WIKI_MANAGER_VERSION },
-          },
-        }),
-      });
-      await initResponse.text();
-      const sessionId = initResponse.headers.get('mcp-session-id');
-      if (!initResponse.ok || !sessionId) {
-        throw new Error(`initialize failed: ${initResponse.status}`);
-      }
-      endpoint._sessionId = sessionId;
-      // Fire-and-forget: complete the handshake without blocking the retry
-      fetch(endpoint.url, {
-        method: 'POST',
-        headers: buildHeaders(),
-        body: JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} }),
-      }).catch(() => {});
-      response = await doRequest(method, params);
+    // The session is server-memory state: an agent restart drops it, and the
+    // server answers 400 or 404 depending on its SDK. Re-negotiate and replay
+    // once, without inspecting the message.
+    if (response.status === 400 || response.status === 404) {
+      mcpSessions.delete(key);
+      const sessionId = await openMcpSession(endpoint, key, requestSignal, headersFor);
+      response = await doRequest(sessionId);
       text = await response.text();
     }
 
@@ -407,6 +460,10 @@ export function resetMcpThrottleForTests() {
   mcpThrottleStarts.clear();
 }
 
+export function resetMcpSessionsForTests() {
+  mcpSessions.clear();
+}
+
 export function formatMcpToolResult(result) {
   if (!result) return 'No result.';
   const content = result.content;
@@ -619,6 +676,24 @@ export function formatMcpToolsForAgent(mcpStatus, { include } = {}) {
     // tool names here is what teaches the model to emit unqualified calls.
     sections.push(`${name}: ${tools.map((tool) => `${name}__${tool.name}`).join(', ')}`);
   }
+  // An agent that failed its probe is otherwise invisible here, and the model
+  // fills the silence by inferring the agent was never set up — it then asks
+  // the user for credentials that already exist. Name the agent, name the
+  // transport failure, and state explicitly that this says nothing about its
+  // configuration.
+  const unreachable = Object.entries(mcpStatus ?? {})
+    .filter(([, value]) => value.status !== 'connected' && value.toolError)
+    .map(([name, value]) => `${name} (${compactDescription(value.toolError)})`);
+  if (unreachable.length > 0) {
+    sections.push(
+      '',
+      `Unreachable right now: ${unreachable.join(', ')}.`,
+      'These agents are declared and may well be configured and running — the manager'
+      + ' simply failed to reach them. Report the connection failure as such; never'
+      + ' infer that such an agent is unconfigured, and never ask the user for its'
+      + ' credentials or URL on that basis.',
+    );
+  }
   return sections.length > 0 ? sections.join('\n') : 'No connected MCP tools discovered yet.';
 }
 

package/src/core/mcp.test.js

@@ -8,6 +8,7 @@ import {
   callMcpTool,
   discoverMcpTools,
   formatMcpToolsForAgent,
+  resetMcpSessionsForTests,
   resetMcpThrottleForTests,
   resolveRetryPolicy,
   resolveToolCallName,
@@ -366,8 +367,9 @@ test('callMcpTool throttles MCP traffic independently per endpoint', async () =>
   const originalFetch = globalThis.fetch;
   const originalWindow = process.env.WIKI_MANAGER_MCP_RATE_LIMIT_WINDOW_MS;
   const starts = [];
-  globalThis.fetch = async () => {
-    starts.push(Date.now());
+  globalThis.fetch = async (_url, init) => {
+    // Only tool traffic is throttled; the one-off session handshake is not.
+    if (JSON.parse(init.body).method === 'tools/call') starts.push(Date.now());
     return {
       ok: true,
       status: 200,
@@ -377,6 +379,7 @@ test('callMcpTool throttles MCP traffic independently per endpoint', async () =>
   };
   process.env.WIKI_MANAGER_MCP_RATE_LIMIT_WINDOW_MS = '30';
   resetMcpThrottleForTests();
+  resetMcpSessionsForTests();
 
   try {
     const status = {
@@ -523,18 +526,24 @@ test('discoverMcpTools downgrades connected endpoint when tool discovery fails',
   }
 });
 
-test('discoverMcpTools initializes SDK servers that report no valid session', async () => {
-  const originalFetch = globalThis.fetch;
-  const methods = [];
-  globalThis.fetch = async (_url, init) => {
+// A stateful server may reject any cold request, and every SDK words that
+// rejection differently ("No valid session" for the Node SDK, "Missing session
+// ID" for the Python one CME runs). The client must never read that prose: it
+// handshakes first, so the rejection is simply never provoked.
+function statefulMcpServer(rejectionMessage, { onMethod } = {}) {
+  return async (_url, init) => {
     const body = JSON.parse(init.body);
-    methods.push(body.method);
-    if (body.method === 'tools/list' && !init.headers['mcp-session-id']) {
+    onMethod?.(body.method, init.headers['mcp-session-id'] ?? null);
+    if (body.method !== 'initialize' && !init.headers['mcp-session-id']) {
       return {
         ok: false,
         status: 400,
         headers: { get: () => null },
-        text: async () => '{"jsonrpc":"2.0","error":{"code":-32000,"message":"No valid session"},"id":null}',
+        text: async () => JSON.stringify({
+          jsonrpc: '2.0',
+          error: { code: -32000, message: rejectionMessage },
+          id: null,
+        }),
       };
     }
     if (body.method === 'initialize') {
@@ -546,35 +555,166 @@ test('discoverMcpTools initializes SDK servers that report no valid session', as
       };
     }
     if (body.method === 'notifications/initialized') {
+      return { ok: true, status: 202, headers: { get: () => null }, text: async () => '' };
+    }
+    return {
+      ok: true,
+      status: 200,
+      headers: { get: () => null },
+      text: async () => '{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"cme_status"}]}}',
+    };
+  };
+}
+
+for (const rejection of ['No valid session', 'Missing session ID', 'Session not found']) {
+  test(`discoverMcpTools handshakes before the first call — server says "${rejection}"`, async () => {
+    const originalFetch = globalThis.fetch;
+    const methods = [];
+    resetMcpSessionsForTests();
+    globalThis.fetch = statefulMcpServer(rejection, { onMethod: (m) => methods.push(m) });
+
+    try {
+      const status = await discoverMcpTools({
+        cme: {
+          status: 'configured',
+          url: 'http://127.0.0.1:3336/mcp/',
+          headers: { authorization: 'Bearer token' },
+        },
+      });
+
+      assert.equal(status.cme.status, 'connected', status.cme.toolError ?? '');
+      assert.deepEqual(status.cme.tools.map((tool) => tool.name), ['cme_status']);
+      // initialize comes first: the cold rejection is never provoked, so its
+      // wording cannot matter.
+      assert.deepEqual(methods, ['initialize', 'notifications/initialized', 'tools/list']);
+    } finally {
+      globalThis.fetch = originalFetch;
+      resetMcpSessionsForTests();
+    }
+  });
+}
+
+test('discoverMcpTools reuses one handshake across concurrent endpoints', async () => {
+  const originalFetch = globalThis.fetch;
+  const methods = [];
+  resetMcpSessionsForTests();
+  globalThis.fetch = statefulMcpServer('Missing session ID', { onMethod: (m) => methods.push(m) });
+
+  try {
+    const endpoint = {
+      status: 'configured',
+      url: 'http://127.0.0.1:3336/mcp/',
+      headers: { authorization: 'Bearer token' },
+    };
+    await discoverMcpTools({ cme: endpoint });
+    await discoverMcpTools({ cme: { ...endpoint } });
+
+    // Second pass rebuilds the endpoint object from the endpoints file, yet the
+    // session is keyed by transport identity — no second handshake.
+    assert.deepEqual(
+      methods.filter((m) => m === 'initialize').length,
+      1,
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+    resetMcpSessionsForTests();
+  }
+});
+
+test('discoverMcpTools accepts a stateless server that issues no session id', async () => {
+  const originalFetch = globalThis.fetch;
+  const methods = [];
+  resetMcpSessionsForTests();
+  globalThis.fetch = async (_url, init) => {
+    const body = JSON.parse(init.body);
+    methods.push(body.method);
+    if (body.method === 'initialize') {
       return {
         ok: true,
-        status: 202,
+        status: 200,
         headers: { get: () => null },
-        text: async () => '',
+        text: async () => '{"jsonrpc":"2.0","id":0,"result":{"protocolVersion":"2025-06-18"}}',
       };
     }
     return {
       ok: true,
       status: 200,
       headers: { get: () => null },
-      text: async () => '{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"connectors_google_status"}]}}',
+      text: async () => '{"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"documents_convert_to_markdown"}]}}',
     };
   };
 
   try {
     const status = await discoverMcpTools({
-      connectors: {
-        status: 'configured',
-        url: 'http://127.0.0.1:3338/mcp/',
-        headers: { authorization: 'Bearer token' },
-      },
+      documents: { status: 'configured', url: 'http://127.0.0.1:3337/mcp/' },
     });
 
-    assert.equal(status.connectors.status, 'connected');
-    assert.deepEqual(status.connectors.tools.map((tool) => tool.name), ['connectors_google_status']);
-    assert.deepEqual(methods, ['tools/list', 'initialize', 'notifications/initialized', 'tools/list']);
+    assert.equal(status.documents.status, 'connected', status.documents.toolError ?? '');
+    // No session id issued: no notifications/initialized, and no re-handshake.
+    assert.deepEqual(methods, ['initialize', 'tools/list']);
   } finally {
     globalThis.fetch = originalFetch;
+    resetMcpSessionsForTests();
+  }
+});
+
+test('callMcpTool re-negotiates and replays once when the agent drops the session', async () => {
+  const originalFetch = globalThis.fetch;
+  const requests = [];
+  const sessions = ['stale-session', 'fresh-session'];
+  resetMcpSessionsForTests();
+  globalThis.fetch = async (_url, init) => {
+    const body = JSON.parse(init.body);
+    requests.push({
+      method: body.method,
+      sessionId: init.headers['mcp-session-id'] ?? null,
+    });
+    if (body.method === 'initialize') {
+      const issued = sessions.shift();
+      return {
+        ok: true,
+        status: 200,
+        headers: { get: (name) => name === 'mcp-session-id' ? issued : null },
+        text: async () => '{"jsonrpc":"2.0","id":0,"result":{"protocolVersion":"2025-06-18"}}',
+      };
+    }
+    if (body.method === 'notifications/initialized') {
+      return { ok: true, status: 202, headers: { get: () => null }, text: async () => '' };
+    }
+    // The agent restarted: the session it issued is gone. The body is
+    // deliberately opaque — recovery keys on the status code alone.
+    if (init.headers['mcp-session-id'] === 'stale-session') {
+      return {
+        ok: false,
+        status: 404,
+        headers: { get: () => null },
+        text: async () => 'Not Found',
+      };
+    }
+    return {
+      ok: true,
+      status: 200,
+      headers: { get: () => null },
+      text: async () => '{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"status: configured"}]}}',
+    };
+  };
+
+  try {
+    const endpoint = { status: 'connected', url: 'http://127.0.0.1:3336/mcp/' };
+    const result = await callMcpTool({ cme: endpoint }, 'cme', 'cme_status', { workspace: 'juno' });
+
+    assert.equal(result.content[0].text, 'status: configured');
+    assert.deepEqual(requests, [
+      { method: 'initialize', sessionId: null },
+      { method: 'notifications/initialized', sessionId: 'stale-session' },
+      { method: 'tools/call', sessionId: 'stale-session' },
+      { method: 'initialize', sessionId: null },
+      { method: 'notifications/initialized', sessionId: 'fresh-session' },
+      { method: 'tools/call', sessionId: 'fresh-session' },
+    ]);
+  } finally {
+    globalThis.fetch = originalFetch;
+    resetMcpSessionsForTests();
   }
 });
 
@@ -622,3 +762,24 @@ test('truncateToolResult keeps short results intact and bounds long ones head+ta
   assert.match(bounded, /-END$/);
   assert.match(bounded, /caractères tronqués/);
 });
+
+test('formatMcpToolsForAgent names unreachable agents instead of hiding them', () => {
+  const listing = formatMcpToolsForAgent({
+    documents: { status: 'connected', tools: [{ name: 'documents_convert_to_markdown' }] },
+    cme: { status: 'configured', toolError: '400 Bad Request: Missing session ID' },
+  });
+
+  assert.match(listing, /documents__documents_convert_to_markdown/);
+  assert.match(listing, /Unreachable right now: cme \(400 Bad Request: Missing session ID\)/);
+  // The model must not be able to read this as "not configured".
+  assert.match(listing, /never\s+infer that such an agent is unconfigured/);
+});
+
+test('formatMcpToolsForAgent stays silent about endpoints that simply are not running', () => {
+  const listing = formatMcpToolsForAgent({
+    wiki: { status: 'configured', runtime: 'not running' },
+    documents: { status: 'connected', tools: [{ name: 'documents_convert_to_markdown' }] },
+  });
+
+  assert.doesNotMatch(listing, /Unreachable/);
+});