@bevel-software/platform-core-backend 0.13.6 → 0.14.0

package/src/modules/connection-probe/index.ts

@@ -0,0 +1,2 @@
+export * from './connection-probe.contract.js';
+export { ConnectionProbeService } from './connection-probe.service.js';

package/src/modules/diff/diff.routes.ts

@@ -3,7 +3,7 @@ import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared
 import type { IDiffService } from './diff.interface.js';
 import type { AuthService } from '../auth/auth.service.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
-import { toKbRelative, resolveReadableMap } from '../access-model/kb-read-filter.js';
+import { canReadWorkspacePath, toKbRelative, resolveReadableMap } from '../access-model/kb-read-filter.js';
 import { WorkflowDomainError, WorkflowValidationError } from '../../shared/domain-errors.js';
 import { LockingFilesystem } from '../kb-fs/locking-filesystem.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
@@ -138,10 +138,14 @@ export function createDiffRoutes(
   }
 
   /** Read gate for a single change path (mirrors GET /review/file). Returns true to proceed. */
-  async function canReadPath(workspaceId: string, email: string, pathParam: string): Promise<boolean> {
-    const rel = toKbRelative(pathParam, kbDirName);
-    // Non-KB paths (toKbRelative → null) carry no read rules and pass.
-    return rel === null || (await accessControl.canRead(workspaceId, email, rel));
+  function canReadPath(workspaceId: string, email: string, pathParam: string): Promise<boolean> {
+    return canReadWorkspacePath(
+      (w, e, p) => accessControl.canRead(w, e, p),
+      workspaceId,
+      email,
+      kbDirName,
+      pathParam,
+    );
   }
 
   router.get('/workspace/:id/review', async (req, res) => {

package/src/modules/kb-fs/__tests__/mutex.test.ts

@@ -8,6 +8,113 @@ function deferred<T = void>() {
 }
 
 describe('WorkspaceMutex', () => {
+  describe('runAll', () => {
+    /**
+     * The property nesting cannot provide: `run(a, () => run(b, fn))` releases
+     * nothing, but between taking `a` and taking `b` the second key is free,
+     * so a single-key task can slip in, run to completion, and be gone before
+     * the pair operation's body starts. `runAll` reserves the set in one
+     * synchronous step, so it cannot be interleaved that way.
+     */
+    it('reserves every key before any of them can be taken by another task', async () => {
+      const mtx = new WorkspaceMutex();
+      const order: string[] = [];
+      const release = deferred();
+
+      // Something already holds 'a', so the pair operation cannot start yet —
+      // this is the window a nested acquisition would leave 'b' open in.
+      const holder = mtx.run('a', async () => {
+        order.push('holder-start');
+        await release.promise;
+        order.push('holder-end');
+      });
+      await new Promise((r) => setImmediate(r));
+
+      const pair = mtx.runAll(['a', 'b'], async () => {
+        order.push('pair');
+      });
+      // Submitted while the pair is still waiting on 'a'. If 'b' were taken
+      // only after 'a' were granted, this would run first.
+      const single = mtx.run('b', async () => {
+        order.push('single-b');
+      });
+
+      release.resolve();
+      await Promise.all([holder, pair, single]);
+      expect(order).toEqual(['holder-start', 'holder-end', 'pair', 'single-b']);
+    });
+
+    it('lets a task on an unrelated key run in parallel', async () => {
+      const mtx = new WorkspaceMutex();
+      const order: string[] = [];
+      const release = deferred();
+
+      const holder = mtx.run('a', async () => {
+        await release.promise;
+        order.push('holder');
+      });
+      await new Promise((r) => setImmediate(r));
+
+      const pair = mtx.runAll(['a', 'b'], async () => void order.push('pair'));
+      const other = mtx.run('c', async () => void order.push('other'));
+
+      await other;
+      expect(order).toEqual(['other']);
+      release.resolve();
+      await Promise.all([holder, pair]);
+      expect(order).toEqual(['other', 'holder', 'pair']);
+    });
+
+    /**
+     * A failing task on ONE key must not release the others. `Promise.all`
+     * settles on the first rejection rather than waiting for the rest, so
+     * combining the predecessors without catching each one first would start
+     * this task while another key was still held.
+     */
+    it('waits for every predecessor even when one of them fails first', async () => {
+      const mtx = new WorkspaceMutex();
+      const order: string[] = [];
+      const failA = deferred();
+      const finishB = deferred();
+
+      const failing = mtx.run('a', async () => {
+        await failA.promise;
+        throw new Error('a-failed');
+      });
+      failing.catch(() => undefined); // handled below; keep the rejection quiet
+      const running = mtx.run('b', async () => {
+        await finishB.promise;
+        order.push('b-end');
+      });
+
+      // Queued while BOTH predecessors are still pending.
+      const pair = mtx.runAll(['a', 'b'], async () => void order.push('pair'));
+
+      failA.resolve();
+      await expect(failing).rejects.toThrow('a-failed');
+      await new Promise((r) => setImmediate(r));
+      // 'a' has failed, but 'b' still holds its key — the pair must wait.
+      expect(order).toEqual([]);
+
+      finishB.resolve();
+      await Promise.all([running, pair]);
+      expect(order).toEqual(['b-end', 'pair']);
+    });
+
+    it('releases every key when the body throws', async () => {
+      const mtx = new WorkspaceMutex();
+      await expect(mtx.runAll(['a', 'b'], async () => { throw new Error('boom'); })).rejects.toThrow('boom');
+      // Both keys must be usable again, or one failure wedges them forever.
+      await expect(mtx.run('a', async () => 'a-ok')).resolves.toBe('a-ok');
+      await expect(mtx.run('b', async () => 'b-ok')).resolves.toBe('b-ok');
+    });
+
+    it('collapses a duplicate key instead of waiting on itself', async () => {
+      const mtx = new WorkspaceMutex();
+      await expect(mtx.runAll(['a', 'a'], async () => 'done')).resolves.toBe('done');
+    });
+  });
+
   it('serializes tasks for the same key in submission order', async () => {
     const mtx = new WorkspaceMutex();
     const order: string[] = [];

package/src/modules/kb-fs/mutex.ts

@@ -8,14 +8,59 @@ export class WorkspaceMutex {
   private readonly tails = new Map<string, Promise<unknown>>();
 
   async run<T>(key: string, fn: () => Promise<T>): Promise<T> {
-    const prev = this.tails.get(key) ?? Promise.resolve();
-    const next = prev.catch(() => undefined).then(fn);
-    this.tails.set(key, next);
+    return this.runAll([key], fn);
+  }
+
+  /**
+   * Reserve SEVERAL keys for one operation, atomically.
+   *
+   * Nesting `run(a, () => run(b, fn))` does NOT do this: between taking `a`
+   * and taking `b` there is a gap in which another operation can take `b`,
+   * finish, and release it — so an operation holding both keys can still be
+   * interleaved with one holding just the second. For branch lifecycle that
+   * gap is the whole bug: a change request being opened `Y -> X` would hold
+   * one branch's key while the other was deleted out from under it.
+   *
+   * This reserves the set in ONE synchronous step. The tails are read and
+   * rewritten without an await between, so no other call can observe a
+   * half-taken set: a concurrent `run` on any of these keys either already
+   * sits in `prev` (it goes first) or chains onto `next` (it goes after).
+   * Within one call nothing is ever held while waiting for something else,
+   * so callers that do not nest need no ordering discipline and cannot
+   * deadlock.
+   *
+   * NESTING is the one way to reintroduce hold-and-wait, so never nest
+   * `run`/`runAll` calls on the same instance. An inner call chains behind
+   * everything already queued on its keys, which can include a `runAll` that
+   * is itself waiting for the outer call to finish: `run(b, () => run(a, …))`
+   * was harmless when every operation took a single key, but against a
+   * concurrent `runAll([a, b])` it deadlocks — outer waits inner, inner
+   * waits the pair, the pair waits outer. No caller nests today; keep it
+   * that way, or hand the full key set to one `runAll` at the top.
+   *
+   * Duplicate keys collapse; the operation waits on each distinct key once.
+   *
+   * Each predecessor is caught INDIVIDUALLY, before the `Promise.all`. A bare
+   * `Promise.all` settles on the first rejection rather than waiting for the
+   * rest, so one key's task failing early would start this one while another
+   * key was still held — a failure on any key would punch a hole in the
+   * mutual exclusion of every key beside it. Catching first makes the
+   * combined promise wait for all of them to settle, however each ends.
+   */
+  async runAll<T>(keys: string[], fn: () => Promise<T>): Promise<T> {
+    const distinct = [...new Set(keys)];
+    const prev = Promise.all(
+      distinct.map((k) => (this.tails.get(k) ?? Promise.resolve()).catch(() => undefined)),
+    );
+    const next = prev.then(fn);
+    for (const k of distinct) this.tails.set(k, next);
     try {
       return await next;
     } finally {
-      if (this.tails.get(key) === next) {
-        this.tails.delete(key);
+      for (const k of distinct) {
+        if (this.tails.get(k) === next) {
+          this.tails.delete(k);
+        }
       }
     }
   }

package/src/modules/secrets-vault/__tests__/connect-pending.route.test.ts

@@ -76,6 +76,10 @@ async function baseUrlWith(auth: { userId?: string; email?: string }): Promise<s
       secretsVault,
       toolManualService,
       accessControl,
+      // These tests are about the credential write, not the probe.
+      connectionProbe: {
+        probe: async () => ({ status: 'unverifiable' as const, detail: null, checkedAt: new Date() }),
+      },
       stateSecret: 'test-secret',
       publicBackendUrl: 'http://localhost:3000',
       publicFrontendUrl: 'http://localhost:5173',
@@ -174,6 +178,10 @@ describe('GET /api/connect/pending — OAuth scope coverage', () => {
         secretsVault: vaultWithGranted(grantedScopes),
         toolManualService: oauthTool,
         accessControl,
+        // These tests are about the credential write, not the probe.
+        connectionProbe: {
+          probe: async () => ({ status: 'unverifiable' as const, detail: null, checkedAt: new Date() }),
+        },
         stateSecret: 'test-secret',
         publicBackendUrl: 'http://localhost:3000',
         publicFrontendUrl: 'http://localhost:5173',
@@ -257,6 +265,10 @@ describe('GET /api/connect/pending — tool sign-ins are not double-listed as st
         secretsVault: vault,
         toolManualService: oauthTool,
         accessControl,
+        // These tests are about the credential write, not the probe.
+        connectionProbe: {
+          probe: async () => ({ status: 'unverifiable' as const, detail: null, checkedAt: new Date() }),
+        },
         stateSecret: 'test-secret',
         publicBackendUrl: 'http://localhost:3000',
         publicFrontendUrl: 'http://localhost:5173',

package/src/modules/secrets-vault/__tests__/oauth-return-to.route.test.ts

@@ -31,8 +31,7 @@ const TOOL_PATH = 'Tools/weather.tool';
 const USER = 'user@x.com';
 const RETURN_TO = '/skills-and-tools/tools/weather';
 
-const toolManualService = {
-  listAccessible: async () => [
+const MANUALS = [
     {
       slug: 'weather',
       name: 'weather',
@@ -51,7 +50,10 @@ const toolManualService = {
         },
       ],
     },
-  ],
+];
+
+const toolManualService = {
+  listAccessible: async () => MANUALS,
 } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['toolManualService'];
 
 const accessControl = {
@@ -65,10 +67,15 @@ const secretsVault = {
   completeOAuth,
 } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['secretsVault'];
 
+const connectionProbe = {
+  probe: async () => ({ status: 'unverifiable' as const, detail: null, checkedAt: new Date() }),
+} as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['connectionProbe'];
+
 const deps = {
   secretsVault,
   toolManualService,
   accessControl,
+  connectionProbe,
   stateSecret: STATE_SECRET,
   publicBackendUrl: 'http://localhost:3000',
   publicFrontendUrl: FRONTEND,

package/src/modules/secrets-vault/__tests__/tool-owner-gate.route.test.ts

@@ -28,6 +28,9 @@ const toolManualService = {
       setup: { kind: 'oauth-manual' as const, reason: 'no authorization-server metadata at https://weather.example' },
       variables: [
         { name: 'SHARED_KEY', scope: 'admin' as const, label: 'Org key' },
+        // A plain per-user key, so the user-scoped write path (and the
+        // per-user invalidation it owes) is exercised alongside the shared one.
+        { name: 'MY_KEY', scope: 'user' as const, label: 'Your key' },
         {
           name: 'SIGNIN',
           scope: 'user' as const,
@@ -56,9 +59,11 @@ const toolManualService = {
   ],
 } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['toolManualService'];
 
+const putStatic = vi.fn(async () => ({ id: 'u1' }));
 const putSharedStatic = vi.fn(async () => ({ id: 's1' }));
 const putSharedOAuthClientSecret = vi.fn(async () => {});
 const secretsVault = {
+  putStatic,
   putSharedStatic,
   putSharedOAuthClientSecret,
 } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['secretsVault'];
@@ -69,6 +74,10 @@ const accessControl = {
   canWrite: async (_ws: string, email: string, path: string) => email === WRITER && path === TOOL_PATH,
 } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['accessControl'];
 
+const connectionProbe = {
+  probe: async () => ({ status: 'unverifiable' as const, detail: null, checkedAt: new Date() }),
+} as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['connectionProbe'];
+
 let httpServer: HttpServer | undefined;
 
 async function baseUrlAs(email: string): Promise<string> {
@@ -85,6 +94,7 @@ async function baseUrlAs(email: string): Promise<string> {
       secretsVault,
       toolManualService,
       accessControl,
+      connectionProbe,
       stateSecret: 'test-secret',
       publicBackendUrl: 'http://localhost:3000',
       publicFrontendUrl: 'http://localhost:5173',
@@ -102,6 +112,7 @@ afterEach(async () => {
   httpServer = undefined;
   putSharedStatic.mockClear();
   putSharedOAuthClientSecret.mockClear();
+  putStatic.mockClear();
 });
 
 describe('tool owner gate — shared config requires WRITE on the `.tool` file', () => {
@@ -116,6 +127,21 @@ describe('tool owner gate — shared config requires WRITE on the `.tool` file',
     expect(putSharedStatic).toHaveBeenCalledWith(expect.objectContaining({ key: 'weather_SHARED_KEY' }));
   });
 
+  it('a mere READER may still set their OWN value for the same tool', async () => {
+    // The gate is on the SHARED value only. One person's own key says nothing
+    // about anyone else's, so needing write access to the `.tool` file to type
+    // your own credential would lock every reader out of the tools they can see.
+    const base = await baseUrlAs(READER);
+    const res = await fetch(`${base}/api/secrets/tools/weather/vars/MY_KEY/user`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ value: 'mine-123' }),
+    });
+    expect(res.status).toBe(201);
+    expect(putStatic).toHaveBeenCalledWith(expect.objectContaining({ key: 'weather_MY_KEY' }));
+    expect(putSharedStatic).not.toHaveBeenCalled();
+  });
+
   it('a non-writer is refused (403), even though they can READ the tool', async () => {
     const base = await baseUrlAs(READER);
     const res = await fetch(`${base}/api/secrets/tools/weather/vars/SHARED_KEY/admin`, {

package/src/modules/secrets-vault/db-secrets-vault.service.ts

@@ -97,7 +97,7 @@ export class DbSecretsVaultService implements ISecretsVaultService {
     if (!this.cryptoInstance) {
       if (!this.encKey) {
         throw new InvalidSecretError(
-          'Secrets require an encryption key — set CONNECTOR_CONFIG_ENC_KEY (or SHAREPOINT_TOKEN_ENC_KEY).',
+          'Secrets require an encryption key — set SECRETS_ENC_KEY.',
         );
       }
       this.cryptoInstance = new TokenCrypto(this.encKey);

package/src/modules/secrets-vault/secrets-vault.routes.ts

@@ -10,6 +10,7 @@ import {
   type ISecretsVaultService,
 } from './secrets-vault.contract.js';
 import type { IToolManualService, ToolManualSummary, ToolVariable } from '../tool-manuals/tool-manuals.contract.js';
+import type { IConnectionProbeService } from '../connection-probe/connection-probe.contract.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
@@ -21,6 +22,11 @@ export interface SecretsVaultRoutesDeps {
   toolManualService: IToolManualService;
   /** Gates who may set a tool's ADMIN (shared) secrets — writers of the `.tool` file. */
   accessControl: IAccessControl;
+  /**
+   * Verdicts of the last credential PROBE per tool — what makes the difference
+   * between "a key is stored" and "the key works" visible to the UI.
+   */
+  connectionProbe: IConnectionProbeService;
   /** HMAC secret for signing the OAuth `state` (reuse the connector state secret). */
   stateSecret: string;
   /** Public base URL of THIS backend — builds the OAuth redirect URI. */
@@ -69,7 +75,7 @@ export function isSafeReturnPath(returnTo: unknown): returnTo is string {
  * `req.userId` — secrets are private per user. Mounted behind the JWT middleware.
  */
 export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.Router {
-  const { secretsVault, toolManualService, accessControl } = deps;
+  const { secretsVault, toolManualService, accessControl, connectionProbe } = deps;
   const router = express.Router();
   // A FUNCTION, not a constant. Routers are constructed at boot, and on a
   // deployment configured through the setup screen the branch model does not
@@ -361,6 +367,10 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
         value: body.value,
         label: body.label,
       });
+      // No probe here, and nothing to invalidate: a verdict is never stored, so
+      // saving a key cannot leave a stale one behind. The caller follows this
+      // with an explicit check, which keeps the save fast and gives the UI a
+      // "Testing…" state to show instead of a frozen dialog.
       res.status(201).json({ secret });
     } catch (err) {
       mapError(err, res, 'set user var');
@@ -504,6 +514,30 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
     }
   });
 
+  /**
+   * Probe one tool's credential NOW and return the verdict.
+   *
+   * A POST because it has an effect on the world — it makes a real
+   * authenticated call to the provider — and because browsers and proxies are
+   * free to cache a GET, which for a freshness check would defeat the point.
+   *
+   * A probe outcome is never an HTTP error: a rejected credential is a
+   * successful check that found a problem, so it comes back 200 with
+   * `status: 'failed'`. Only a tool that can't be found or read 404s.
+   */
+  router.post('/secrets/tools/:slug/check', async (req, res) => {
+    const userId = req.userId;
+    const email = req.userEmail;
+    if (!userId || !email) return void res.status(401).json({ error: 'Not authenticated' });
+    try {
+      const verdict = await connectionProbe.probe(userId, email, req.params.slug);
+      if (!verdict) return void res.status(404).json({ error: 'Tool not found' });
+      res.json({ verdict });
+    } catch (err) {
+      mapError(err, res, 'check tool connection');
+    }
+  });
+
   return router;
 }
 

package/src/modules/tool-manuals/__tests__/mcp-json-discovery.test.ts

@@ -37,6 +37,17 @@ describe('descriptorsFromMcpJson', () => {
     ]);
   });
 
+  it('refuses an sse server rather than rebuilding it as a transport it is not', () => {
+    // The pinned MCP client has no sse transport; emitting `http` for an sse
+    // server configures a handshake the server does not speak.
+    const out = descriptorsFromMcpJson(
+      'GTM',
+      JSON.stringify({ mcpServers: { legacy: { type: 'sse', url: 'https://mcp.legacy.example/sse' } } }),
+      null,
+    );
+    expect(out).toEqual([]);
+  });
+
   it('merges extension auth over mcp.json literals and carries variables + description', () => {
     const out = descriptorsFromMcpJson(
       'GTM',

package/src/modules/tool-manuals/__tests__/tool-manuals.health-check.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest';
+import { normalizeToolManual } from '../tool-manuals.service.js';
+
+/**
+ * The `healthCheck:` block is a URL this SERVER will fetch with the caller's
+ * credential attached, unattended, on every save and re-check. That makes it a
+ * second fetch target on the same footing as the manual's own `url`, so it is
+ * policed by the same SSRF rule — and held to one extra rule of its own: it may
+ * not mutate.
+ */
+
+const toolFile = (body: string) => `---
+name: acme
+type: http
+url: https://api.acme.test/utcp
+headers:
+  Authorization: Bearer \${API_KEY}
+${body}---
+notes
+`;
+
+const parse = (body: string) => normalizeToolManual('acme', 'Plugins/acme.tool', toolFile(body));
+
+describe('`.tool` healthCheck', () => {
+  it('is absent when nothing is declared — the tool is simply unverifiable', () => {
+    expect(parse('').healthCheck).toBeUndefined();
+  });
+
+  it('inherits the manual\'s headers, so a one-line declaration still authenticates', () => {
+    // This is what makes the common case cheap: the credential already lives in
+    // `headers`, and re-typing it on the probe would be a chance to get it wrong.
+    expect(parse('healthCheck:\n  url: https://api.acme.test/me\n').healthCheck).toEqual({
+      url: 'https://api.acme.test/me',
+      headers: { Authorization: 'Bearer ${API_KEY}' },
+    });
+  });
+
+  it('keeps its own headers when it declares them', () => {
+    const hc = parse('healthCheck:\n  url: https://api.acme.test/me\n  headers:\n    X-Key: ${API_KEY}\n').healthCheck;
+    expect(hc?.headers).toEqual({ 'X-Key': '${API_KEY}' });
+  });
+
+  it("an INLINE manual's probe inherits NO top-level headers — execution never sends them", () => {
+    // An inline manual's real calls go through each embedded tool's own call
+    // template; nothing ever sends the manual's top-level `headers:`. A probe
+    // that inherited them proved a request no call makes — `Connected` about
+    // the wrong request. An inline probe declares its headers on the
+    // healthCheck itself, or sends none.
+    const inline = normalizeToolManual(
+      'acme',
+      'Plugins/acme.tool',
+      `---
+name: acme
+type: inline
+headers:
+  Authorization: Bearer \${API_KEY}
+healthCheck:
+  url: https://api.acme.test/me
+tools: []
+---
+`,
+    );
+    expect(inline.healthCheck?.headers).toBeUndefined();
+  });
+
+  it('refuses a method that could mutate', () => {
+    // Silently downgrading POST to GET would leave the author believing they had
+    // declared something we are not doing.
+    expect(() => parse('healthCheck:\n  url: https://api.acme.test/me\n  method: POST\n')).toThrow(
+      /may not mutate/,
+    );
+  });
+
+  it('refuses a probe pointed at an internal host', () => {
+    expect(() => parse('healthCheck:\n  url: http://169.254.169.254/latest/meta-data\n')).toThrow(
+      /not allowed/,
+    );
+  });
+
+  it('refuses a declaration with no url', () => {
+    expect(() => parse('healthCheck:\n  method: GET\n')).toThrow(/must have a `url`/);
+  });
+
+  /**
+   * A local-only `.tool` is never fetched by this server, so its probe is exempt
+   * from the guard for exactly the same reason its `url` is.
+   */
+  it('exempts a local-only tool, as it does for the manual url', () => {
+    const local = normalizeToolManual(
+      'acme',
+      'Plugins/acme.tool',
+      `---
+name: acme
+type: http
+remote: false
+url: http://localhost:9000/utcp
+healthCheck:
+  url: http://localhost:9000/me
+---
+`,
+    );
+    expect(local.healthCheck?.url).toBe('http://localhost:9000/me');
+  });
+});

package/src/modules/tool-manuals/__tests__/tool-manuals.service.test.ts

@@ -82,6 +82,62 @@ describe('ToolManualService', () => {
     expect(list.find((m) => m.name === 'billing')!.type).toBe('http');
   });
 
+  test('surfaces a variable referenced ONLY by a health check, and keeps the probe off the summary', async () => {
+    // Two halves of the same contract. The probe's `${VAR}` has to reach the
+    // secrets UI or nobody can ever fill it in and the tool reports
+    // `unverifiable` forever — but the probe's HEADERS must not ride the
+    // browser-facing summary, since a `.tool` may write a literal token there.
+    const tools = join(root, wsId, KB_DIR, 'Plugins');
+    await writeFile(
+      join(tools, 'probe.tool'),
+      JSON.stringify({
+        name: 'probe',
+        type: 'http',
+        url: 'https://api.example.com/utcp',
+        healthCheck: { url: 'https://api.example.com/me', headers: { 'X-Key': '${PROBE_ONLY_KEY}' } },
+      }),
+    );
+
+    const summary = (await svc().listAccessible('user@x.eu')).find((m) => m.name === 'probe')!;
+    expect(summary.variables?.map((v) => v.name)).toContain('PROBE_ONLY_KEY');
+    expect(summary).not.toHaveProperty('healthCheck');
+
+    // The server still reaches it, through the accessor that never serializes.
+    const target = await svc().probeTargetFor('user@x.eu', 'probe');
+    expect(target?.healthCheck?.headers).toEqual({ 'X-Key': '${PROBE_ONLY_KEY}' });
+  });
+
+  test('builds a call template only for the probe that actually dials one', async () => {
+    // The template is dialled by exactly one probe: an `mcp` manual, reachable
+    // from this process, that declared no health check. Building it for the
+    // others costs a validation pass per probe and warn-logs about a value
+    // nothing was going to use.
+    const tools = join(root, wsId, KB_DIR, 'Plugins');
+    await writeFile(
+      join(tools, 'chat.tool'),
+      JSON.stringify({ name: 'chat', type: 'mcp', url: 'https://mcp.example.com' }),
+    );
+    await writeFile(
+      join(tools, 'checked.tool'),
+      JSON.stringify({
+        name: 'checked',
+        type: 'mcp',
+        url: 'https://mcp.example.com',
+        healthCheck: { url: 'https://api.example.com/me' },
+      }),
+    );
+
+    const service = svc();
+    // Asserted through the template's own type, not `not.toBeNull()`: the
+    // optional chain yields `undefined` when the lookup itself fails, and
+    // `undefined` is not null — so the weaker form passes on no target at all.
+    expect((await service.probeTargetFor('user@x.eu', 'chat'))?.callTemplate?.call_template_type).toBe('mcp');
+    // A declared health check wins for every type, so this one never dials it.
+    expect((await service.probeTargetFor('user@x.eu', 'checked'))?.callTemplate).toBeNull();
+    // An http manual is probed only by what it declares, never by a handshake.
+    expect((await service.probeTargetFor('user@x.eu', 'billing'))?.callTemplate).toBeNull();
+  });
+
   test('ACL filters out manuals the user cannot read', async () => {
     const list = await svc(denyBilling).listAccessible('user@x.eu');
     expect(list.map((m) => m.name)).toEqual(['weather']);

package/src/modules/tool-manuals/mcp-json-discovery.ts

@@ -292,7 +292,19 @@ export function descriptorsFromMcpJson(
       continue;
     }
 
-    if (raw.type === 'streamable-http' || raw.type === 'sse') {
+    if (raw.type === 'sse') {
+      // The pinned `@utcp/mcp` speaks `stdio` and streamable `http` — there
+      // is no sse transport in its schema, so a template claiming one either
+      // fails validation or, worse, dials a handshake the server does not
+      // speak. Refusing here names the fix; silently rebuilding as http used
+      // to configure exactly that wrong handshake.
+      console.warn(
+        `[tool-manuals] skipping mcp server "${name}" in ${mcpJsonPath}: the MCP client has no \`sse\` transport — declare the server as \`streamable-http\` if it supports it.`,
+      );
+      continue;
+    }
+
+    if (raw.type === 'streamable-http') {
       if (typeof raw.url !== 'string' || raw.url.length === 0) {
         console.warn(`[tool-manuals] skipping mcp server "${name}" in ${mcpJsonPath}: no url.`);
         continue;