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

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;

package/src/modules/tool-manuals/mcp-server-edit.service.ts

@@ -174,10 +174,19 @@ export class McpServerEditService {
     const servers = mcp.mcpServers as Record<string, unknown>;
     if (!(name in servers)) throw new McpServerEditError('No such server.', 404);
 
-    if (write.transport !== 'streamable-http' && write.transport !== 'sse' && write.transport !== 'stdio') {
-      // Persisting an unknown transport would save an entry discovery then
-      // refuses — an unusable server with no error at the moment it was made.
-      throw new McpServerEditError(`Unknown transport "${String(write.transport)}".`, 422);
+    if (write.transport !== 'streamable-http' && write.transport !== 'stdio') {
+      // Persisting a transport discovery refuses would save an entry that
+      // vanishes from the catalog the moment it is written — an unusable
+      // server with no error at the moment it was made. `sse` is refused BY
+      // NAME with the fix spelled out, because the pinned MCP client has no
+      // sse transport; an EXISTING sse entry stays readable here, so it can
+      // be edited to `streamable-http` rather than being stranded.
+      throw new McpServerEditError(
+        write.transport === 'sse'
+          ? 'The MCP client has no `sse` transport — declare the server as `streamable-http` if it supports it.'
+          : `Unknown transport "${String(write.transport)}".`,
+        422,
+      );
     }
     // The EFFECTIVE value of every field, PATCH-over-stored (see
     // McpServerWrite): `undefined` keeps what the files already say, a

package/src/modules/tool-manuals/tool-manuals.contract.ts

@@ -88,6 +88,57 @@ export interface ToolVariable {
   oauth?: ToolVariableOAuth;
 }
 
+/**
+ * An optional cheap, read-only call that proves a credential actually WORKS.
+ *
+ * A `type: mcp` manual needs none — its handshake is authenticated, so merely
+ * connecting already tests the token. `http` and `inline` manuals have no such
+ * moment: registering an `http` manual fetches its DESCRIPTION, which providers
+ * usually serve publicly, so a wrong key sails through; an `inline` manual's
+ * discovery template points at Bevel's own API and never touches the provider
+ * at all. Without a declaration there is genuinely nothing to call, and the
+ * platform reports the connection as unverified rather than guessing.
+ *
+ * NOT inferred from the manual's own tools. Picking one automatically would
+ * mean calling an arbitrary tool with invented arguments — a probe that could
+ * send a message or create a record is worse than no probe. The author names a
+ * safe endpoint or the tool stays unverified.
+ *
+ * `${VAR}` refs resolve from the caller's vault exactly as they do in `url` and
+ * `headers`, which is the whole point: the probe must carry the same credential
+ * the real calls carry. Any 2xx is a pass; 401/403 is a rejection; anything
+ * else is treated as the provider being unwell rather than the key being wrong.
+ */
+export interface ToolHealthCheck {
+  /** Absolute URL to call. May contain `${VAR}` refs; SSRF-checked like `url`. */
+  url: string;
+  /** Default `GET`. A health check may not mutate, so nothing else is allowed. */
+  method?: 'GET';
+  /** Defaults to the manual's own `headers` — usually where the credential is. */
+  headers?: Record<string, string>;
+}
+
+/**
+ * One manual, reduced to exactly what testing its credential requires.
+ *
+ * Server-internal, like {@link ToolHealthCheck} and for the same reason: both
+ * `healthCheck.headers` and `callTemplate` can carry a literal token.
+ */
+export interface ToolProbeTarget {
+  name: string;
+  type: ToolManualType;
+  /** `false` for a local-only tool this server is not the one that can reach it. */
+  remote?: boolean;
+  /** The probe the `.tool` declares, if any. */
+  healthCheck?: ToolHealthCheck;
+  /**
+   * The validated UTCP call template, or `null` when the manual doesn't produce
+   * a valid one. Only the `mcp` probe uses it — its handshake IS the test — but
+   * it is built here so the probe never has to walk the catalog again.
+   */
+  callTemplate: CallTemplate | null;
+}
+
 /**
  * For a `type: mcp` tool, what an admin must do to make the remote server
  * reachable — derived from OAuth auto-discovery, which a non-mcp tool has no
@@ -140,6 +191,15 @@ export interface ToolManualDescriptorBase {
   variables?: ToolVariable[];
   /** For `type: mcp`: the admin-facing setup requirement from auto-discovery. */
   setup?: ToolManualSetup;
+  /**
+   * Optional credential probe — see {@link ToolHealthCheck}. Declared on
+   * `http`/`inline` manuals, and honoured on `type: mcp` too, where it
+   * OVERRIDES the default handshake probe (a server whose health endpoint is
+   * cheaper or more truthful than a full MCP handshake says so here).
+   * INTERNAL: lives on the descriptor, never on {@link ToolManualSummary},
+   * because it carries `headers`.
+   */
+  healthCheck?: ToolHealthCheck;
 }
 
 /** The spawn spec of a stdio-declared MCP server (a plugin `mcp.json` entry). */
@@ -197,6 +257,10 @@ export interface ToolManualSummary {
   remote?: boolean;
   /** For `type: mcp`: the admin-facing setup requirement from auto-discovery. */
   setup?: ToolManualSetup;
+  // NOTE: no `healthCheck` here, deliberately. This type is serialized straight
+  // to the browser by the tool endpoints, and a probe carries `headers` — which
+  // a `.tool` author may write as a literal token rather than a `${VAR}` ref.
+  // The server reads probe config through `IToolManualService.probeTargetFor`.
 }
 
 /** One thing an `inline` manual's embedded tool list says the assistant can do. */
@@ -269,6 +333,31 @@ export interface IToolManualService {
    * a `resolve` reads the shared row or the caller's row.
    */
   scopeOfVariable(effectiveKey: string): Promise<ToolVariableScope>;
+  /**
+   * Everything the credential probe needs about one readable manual, resolved
+   * in a SINGLE catalog + ACL pass.
+   *
+   * One accessor rather than three because the probe needs three facts that all
+   * come from the same file — is it local-only, does it declare a health check,
+   * and what call template would reach it — and asking for them separately made
+   * one probe walk the catalog four times, building call templates for every
+   * manual in the workspace to use exactly one of them.
+   *
+   * Deliberately NOT reachable through {@link ToolManualSummary}: that type is
+   * serialized straight to the browser by the tool endpoints, and a probe
+   * carries `headers` — which a `.tool` author may write as a literal token
+   * rather than a `${VAR}` ref. Probe config is internal to the server, so it
+   * travels by its own accessor and never rides a public DTO.
+   *
+   * Addressed by SLUG, which is what the route has: resolving the slug here
+   * rather than making the caller map it to a name first is what reduces a
+   * probe to one pass. `ToolProbeTarget.name` carries the UTCP namespace back
+   * out, since that is what the probe's `${VAR}` lookups are keyed by.
+   *
+   * `null` when no such manual exists OR the caller can't read it — the two are
+   * indistinguishable on purpose, as everywhere else in this contract.
+   */
+  probeTargetFor(userEmail: string, slug: string): Promise<ToolProbeTarget | null>;
   /**
    * The per-user (`user`-scoped) variables a manual declares, each with the vault
    * key (`<manual>_<VAR>`) the caller's value is stored under, its bare name, and