@bevel-software/platform-core-backend 0.33.0 → 0.35.0

package/src/modules/mcp/__tests__/oauth-consent.connect-as.test.ts

@@ -0,0 +1,146 @@
+import express from 'express';
+import type { AddressInfo } from 'node:net';
+import type { Server } from 'node:http';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createOAuthConsentRoutes, NOT_AN_AGENT_CHOICE } from '../oauth/oauth-consent.routes.js';
+import { signAuthRequest } from '../oauth/oauth-state.js';
+import { agentFile, agentScopeOver, inMemoryKb } from '../../agent-scope/__tests__/in-memory-kb.js';
+
+/**
+ * The consent step's "Connect as" choice, through the two routes the
+ * /connect page calls: the request description offers the agents the person
+ * may read, and Finish hands the provider exactly the choice made — null for
+ * Everything — or refuses one that is not on offer, before any code is minted.
+ * The choice offered and checked is the REAL agent-scope service's, over a
+ * knowledge base held in memory.
+ */
+
+const SECRET = 'state-secret';
+const ADA = 'ada@example.com';
+
+let http: Server | null = null;
+afterEach(async () => {
+  if (http) await new Promise<void>((r) => http!.close(() => r()));
+  http = null;
+});
+
+const kb = inMemoryKb({
+  'Agents/mechanic.agent': agentFile('name: delivery-mechanic\ndescription: Moves code around.'),
+  'Agents/secret.agent': agentFile('name: secret'),
+});
+kb.hidden.add('Agents/secret.agent');
+
+async function mount(opts: { email?: string; agents?: Parameters<typeof createOAuthConsentRoutes>[0]['agents'] } = {}) {
+  const issueAuthCode = vi.fn(async () => ({ redirectTo: 'https://agent.example.com/cb?code=c1' }));
+  const completeConsent = vi.fn(async () => ({ redirectTo: 'https://claude.ai/cb?code=gh' }));
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    req.userId = 'u1';
+    req.userEmail = opts.email ?? ADA;
+    next();
+  });
+  app.use(
+    createOAuthConsentRoutes({
+      provider: {
+        issueAuthCode,
+        clientsStore: { getClient: async () => ({ client_name: 'Claude' }) },
+      } as never,
+      stateSecret: SECRET,
+      facade: {
+        isFacadeRequest: () => true,
+        clientNameFor: () => 'Claude',
+        completeConsent,
+      },
+      agents: opts.agents ?? agentScopeOver(kb),
+    }),
+  );
+  http = app.listen(0);
+  await new Promise<void>((r) => http!.once('listening', r));
+  const base = `http://127.0.0.1:${(http.address() as AddressInfo).port}`;
+  return { base, issueAuthCode, completeConsent };
+}
+
+const state = (extra: Record<string, unknown> = {}) =>
+  signAuthRequest(SECRET, { c: 'client-1', r: 'https://agent.example.com/cb', cc: 'challenge', ...extra });
+
+async function finish(base: string, body: Record<string, unknown>) {
+  return fetch(`${base}/mcp/oauth/complete`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+}
+
+describe('the consent step offers "Connect as"', () => {
+  it('lists the agents the person may read, by name with description and path — Everything is the page’s own', async () => {
+    const { base } = await mount();
+    const res = await fetch(`${base}/mcp/oauth/request?state=${encodeURIComponent(state())}`);
+    expect(await res.json()).toEqual({
+      clientName: 'Claude',
+      scope: null,
+      resource: null,
+      agents: [{ path: 'Agents/mechanic.agent', name: 'delivery-mechanic', description: 'Moves code around.' }],
+    });
+  });
+
+  it('says so when the agents cannot be listed, rather than passing it off as having none', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const failing = {
+      listChoices: async () => {
+        throw new Error('checkout unavailable');
+      },
+      choosable: async () => null,
+    };
+    const { base } = await mount({ agents: failing });
+    const res = await fetch(`${base}/mcp/oauth/request?state=${encodeURIComponent(state())}`);
+    expect(await res.json()).toEqual({
+      clientName: 'Claude',
+      scope: null,
+      resource: null,
+      agents: [],
+      agentsUnavailable: true,
+    });
+  });
+});
+
+describe('Finish records the choice', () => {
+  it('Everything — no choice, null or empty — reaches the provider as null, exactly as before', async () => {
+    const { base, issueAuthCode } = await mount();
+    for (const body of [{}, { agentPath: null }, { agentPath: '' }]) {
+      const st = state();
+      const res = await finish(base, { state: st, ...body });
+      expect(res.status).toBe(200);
+      expect(await res.json()).toEqual({ redirectTo: 'https://agent.example.com/cb?code=c1' });
+    }
+    expect(issueAuthCode).toHaveBeenCalledTimes(3);
+    for (const call of issueAuthCode.mock.calls as unknown as unknown[][]) expect(call[2]).toBeNull();
+  });
+
+  it('an agent on offer reaches the provider as its normalized path', async () => {
+    const { base, issueAuthCode } = await mount();
+    const res = await finish(base, { state: state(), agentPath: '/Agents/mechanic.agent' });
+    expect(res.status).toBe(200);
+    expect(issueAuthCode).toHaveBeenCalledWith('u1', expect.objectContaining({ c: 'client-1' }), 'Agents/mechanic.agent');
+  });
+
+  it.each([
+    ['a file the person may not read', 'Agents/secret.agent'],
+    ['a file that does not exist', 'Agents/none.agent'],
+    ['a path that is not an agent', 'notes.md'],
+    ['a value that is not a path', 42],
+  ])('refuses %s with one answer, minting nothing', async (_what, agentPath) => {
+    const { base, issueAuthCode } = await mount();
+    const res = await finish(base, { state: state(), agentPath });
+    expect(res.status).toBe(400);
+    expect(await res.json()).toEqual({ error: NOT_AN_AGENT_CHOICE });
+    expect(issueAuthCode).not.toHaveBeenCalled();
+  });
+
+  it('refuses a choice on an account linked through the GitHub facade, which has no connection to record it on', async () => {
+    const { base, completeConsent } = await mount();
+    const res = await finish(base, { state: state({ gh: true, cc: undefined }), agentPath: 'Agents/mechanic.agent' });
+    expect(res.status).toBe(400);
+    expect(completeConsent).not.toHaveBeenCalled();
+  });
+});

package/src/modules/mcp/mcp-auth.middleware.ts

@@ -24,6 +24,13 @@ declare global {
        * the page its call comes from (`X-Bevel-Page`).
        */
       mcpCallerKind?: McpCallerKind;
+      /**
+       * The agent configuration the MCP caller's credential connects as — a key's
+       * `api_tokens.agent_path`, an agent connection's
+       * `agent_connections.agent_path`, or the one an exchanged grant
+       * carries. Unset is Everything.
+       */
+      mcpAgentPath?: string;
     }
   }
 }
@@ -110,6 +117,7 @@ export function createMcpAuthMiddleware(
         req.userId = resolved.user.id;
         req.userEmail = resolved.user.email;
         req.externalApiKeyId = resolved.tokenId;
+        if (resolved.agentPath) req.mcpAgentPath = resolved.agentPath;
         req.mcpCallerKind = 'key';
         next();
         return;
@@ -137,6 +145,9 @@ export function createMcpAuthMiddleware(
         if (typeof info.extra?.connectionId === 'string') {
           req.agentConnectionId = info.extra.connectionId;
         }
+        if (typeof info.extra?.agentPath === 'string' && info.extra.agentPath) {
+          req.mcpAgentPath = info.extra.agentPath;
+        }
         if (!req.userId) {
           unauthorized(res, 'Invalid access token');
           return;
@@ -217,10 +228,13 @@ export function createMcpAuthMiddleware(
       // stamped too (throttled, off the request's path), so the Audit log's
       // "last used" follows the local server's calls, not only its sign-ins.
       // Carried on the request so those calls are logged under the agent.
+      // The same read answers what the connection is made as NOW: a
+      // re-consent changes the row, not the token, so the row's choice is
+      // the one served, never the one the token was minted with.
       if (claim.connectionId) {
-        let live: boolean;
+        let live: { agentPath: string | null } | null;
         try {
-          live = await oauthProvider.isConnectionLive(claim.connectionId);
+          live = await oauthProvider.liveConnectionChoice(claim.connectionId);
         } catch (err) {
           log.error('agent-connection check failed:', { err });
           res.status(500).json({ error: 'Authentication backend unavailable' });
@@ -232,6 +246,9 @@ export function createMcpAuthMiddleware(
         }
         oauthProvider.noteConnectionUse(claim.connectionId);
         req.agentConnectionId = claim.connectionId;
+        if (live.agentPath) req.mcpAgentPath = live.agentPath;
+      } else if (claim.agentPath) {
+        req.mcpAgentPath = claim.agentPath;
       }
       req.mcpCallerKind = 'internal';
       next();

package/src/modules/mcp/mcp.routes.ts

@@ -16,6 +16,8 @@ import type { BevelOAuthProvider } from './oauth/bevel-oauth-provider.js';
 import '../tool-auth/index.js'; // req.externalApiKeyId augmentation
 import './mcp-auth.middleware.js'; // req.mcpCallerKind augmentation
 import { isPagePath } from '../audit/index.js';
+import type { IAgentScopeResolver } from '../agent-scope/index.js';
+import { NOT_AN_AGENT_CHOICE } from './oauth/oauth-consent.routes.js';
 
 /** Pull the raw bearer token off an already-authenticated request. */
 function extractBearer(req: Request): string {
@@ -104,6 +106,11 @@ export function createMcpRoutes(
   // RFC 9728 pointer carried on this router's own 401 challenges (the
   // local-token exchange), same value McpAuthMiddleware advertises.
   resourceMetadataUrl: string,
+  /**
+   * The "Connect as" choices a key may be minted as (`modules/agent-scope`).
+   * Absent: keys are minted as Everything only, and no choices are listed.
+   */
+  agents?: Pick<IAgentScopeResolver, 'listChoices' | 'choosable'>,
 ): express.Router {
   const router = express.Router();
 
@@ -153,6 +160,10 @@ export function createMcpRoutes(
           // exchanged grant; undefined for keys/JWTs) — the Audit log's other
           // principal, resolved per request like the key id.
           connectionId: req.agentConnectionId ?? null,
+          // The agent configuration the credential connects as (a key's, an agent
+          // connection's, or the one an exchanged grant carries); null is
+          // Everything. Resolved per request like the ids above.
+          ...(req.mcpAgentPath ? { agentPath: req.mcpAgentPath } : {}),
           // The proxy authenticates its loopback calls with the SAME bearer the
           // client used here, so it acts on the request exactly as the caller would.
           bearer: extractBearer(req),
@@ -233,6 +244,17 @@ export function createMcpRoutes(
 
   // ── Connection-key management (JWT-only) ───────────────────────────────
 
+  // The agents a key may be minted as — the same choices the OAuth consent
+  // step offers below Everything, for the key-mint dialog.
+  router.get('/mcp/agent-choices', jwtAuthMiddleware, async (req, res) => {
+    try {
+      res.json({ agents: agents && req.userEmail ? await agents.listChoices(req.userEmail) : [] });
+    } catch (err) {
+      log.error('listing the agents to connect as failed:', { err });
+      res.status(500).json({ error: 'Failed to list the agents' });
+    }
+  });
+
   router.get('/mcp/external-api-keys', jwtAuthMiddleware, async (req, res) => {
     try {
       const tokens = await externalApiKeyService.listForUser(req.userId!);
@@ -264,12 +286,23 @@ export function createMcpRoutes(
         res.status(400).json({ error: 'JSON body required' });
         return;
       }
-      const { label } = req.body as { label?: string };
+      const { label, agentPath: asked } = req.body as { label?: string; agentPath?: unknown };
       if (!label) {
         res.status(400).json({ error: 'label is required' });
         return;
       }
-      const minted = await externalApiKeyService.mint(req.userId!, label);
+      // "Connect as", exactly as on the consent step: absent, null or empty is
+      // Everything; anything else must be an agent the owner may choose now.
+      let agentPath: string | null = null;
+      if (asked !== undefined && asked !== null && asked !== '') {
+        agentPath =
+          typeof asked === 'string' && agents && req.userEmail ? await agents.choosable(req.userEmail, asked) : null;
+        if (agentPath === null) {
+          res.status(400).json({ error: NOT_AN_AGENT_CHOICE });
+          return;
+        }
+      }
+      const minted = await externalApiKeyService.mint(req.userId!, label, agentPath ? { agentPath } : {});
       // The plaintext field is the *only* read path for the raw key. The
       // frontend must store it nowhere — it shows the dialog once and then
       // discards. Subsequent fetches return only `summary`-shaped rows.
@@ -428,8 +461,11 @@ export function createMcpRoutes(
       // The grant's agent connection rides along, so the local server's
       // calls with this token stay attributed to the agent in the Audit log.
       const connectionId = typeof info.extra?.connectionId === 'string' ? info.extra.connectionId : undefined;
+      // So does the agent the connection was made as: the local server's
+      // calls see the same narrowed surface as the hosted endpoint's.
+      const agentPath = typeof info.extra?.agentPath === 'string' && info.extra.agentPath ? info.extra.agentPath : undefined;
       const minted = internalTokens.mint(
-        { userId, externalProxy: true, ...(connectionId ? { connectionId } : {}) },
+        { userId, externalProxy: true, ...(connectionId ? { connectionId } : {}), ...(agentPath ? { agentPath } : {}) },
         ttlMs,
       );
       // The ACTUAL lifetime, not the constant — the caller schedules its

package/src/modules/mcp/mcp.service.ts

@@ -50,7 +50,7 @@ import {
   type LoadedSkill,
 } from '@bevel-software/platform-mcp-core';
 import type { KbLayout } from '@bevel-software/platform-shared';
-import { bevelSecretsLoaderConfig, type ForcedRefreshOutcome, type ISecretsVaultService, scopesCovered } from '../secrets-vault/index.js';
+import { bevelSecretsLoaderConfig, type ForcedRefreshOutcome, type ISecretsVaultService, userSecretGap } from '../secrets-vault/index.js';
 import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/index.js';
 import type { IToolManualService } from '../tool-manuals/index.js';
 import type { SpillStore } from '../workspace/index.js';
@@ -75,6 +75,16 @@ import {
   type ComposedAgentInstructions,
 } from '../agent-instructions/index.js';
 import { guideFirstDescription } from '../tool-registry/index.js';
+import {
+  CONNECTION_META_KEY,
+  connectionRefusal,
+  connectionWireOf,
+  describeConnection,
+  type ConnectionScopeWire,
+} from '@bevel-software/platform-mcp-core';
+
+// Still offered from here, as this module's tests and callers learnt it.
+export { CONNECTION_META_KEY };
 
 /**
  * Configuration for the loopback proxy. `loopbackBaseUrl` is the backend's own
@@ -142,6 +152,14 @@ export interface McpCaller {
    * attributed in the Audit log; a request with neither records nothing.
    */
   connectionId?: string | null;
+  /**
+   * The agent configuration the caller's credential connects as (a connection
+   * key's, or an agent connection's), or null for Everything. It rides the
+   * request's loopback identity, so every agent surface behind the loopback
+   * narrows to that agent's scope (`modules/agent-scope`); here it only keys
+   * the surface and words the handshake.
+   */
+  agentPath?: string | null;
   /** The raw bearer the request carried. */
   bearer: string;
   /**
@@ -222,6 +240,24 @@ interface RequestSurface {
    * build, at the latest after an hour unused.
    */
   degraded: boolean;
+  /**
+   * The agent the catalog was narrowed to, as `all-tools` reported it —
+   * absent for Everything. A call to a tool not on a narrowed surface is
+   * refused by name and agent rather than as unknown, and a connection whose
+   * agent configuration cannot be used is served nothing, with the sentence that says
+   * why.
+   */
+  connection?: ConnectionScopeWire;
+}
+
+/**
+ * The `connection` a loopback answer (`all-tools`, `catalog-revision`)
+ * carries, as a field to spread: validated at the boundary by the MCP
+ * core's reader (HTTP loses the type), and absent for Everything.
+ */
+function connectionOf(body: unknown): { connection?: ConnectionScopeWire } {
+  const connection = connectionWireOf(body);
+  return connection ? { connection } : {};
 }
 
 /**
@@ -490,13 +526,26 @@ export class McpService {
     // verifier resolves it to `source: 'external'`: the caller IS an external
     // agent and must be treated like one (admitted to `start_session`/`ask`,
     // refused from internal-only tools).
+    // The agent the connection was made as rides that token too, so the
+    // surfaces behind the loopback narrow to its scope; a connection key
+    // carries its own.
+    const agentPath = caller.agentPath || null;
     const loopbackBearer =
       tokenId == null && this.internalTokens
-        ? this.internalTokens.mint({ userId, externalProxy: true }, MCP_LOOPBACK_TOKEN_TTL_MS)
+        ? this.internalTokens.mint(
+            { userId, externalProxy: true, ...(agentPath ? { agentPath } : {}) },
+            MCP_LOOPBACK_TOKEN_TTL_MS,
+          )
         : bearer;
 
     let instructions: Promise<ComposedAgentInstructions> | undefined;
     const agentInstructions = () => (instructions ??= this.composeAgentInstructions());
+    // What a narrowed connection is told about itself at the handshake: the
+    // agent it is connected as, or why it loads nothing. Read off the catalog
+    // revision (cheap), not the surface (a full discovery). Everything is
+    // told nothing new, so its handshake is exactly what it was.
+    const connectionLine = async (): Promise<string | null> =>
+      agentPath ? describeConnection((await this.fetchCatalogRevision(loopbackBearer)).connection) : null;
     // The Audit log's view of this request — only when the request can be
     // attributed to a key, an agent connection or a page. The catalog names
     // it classifies pooled tools by are the surface's, which is looked up
@@ -534,6 +583,10 @@ export class McpService {
       }));
 
     const initializing = (Array.isArray(messages) ? messages : [messages]).some((m) => isInitializeRequest(m));
+    const handshakeInstructions = async (): Promise<string> => {
+      const [{ instructions: text }, line] = await Promise.all([agentInstructions(), connectionLine()]);
+      return line ? `${text}\n\n${line}` : text;
+    };
     // The deployment's MCP Apps, read once per request. Declaring the
     // `resources` capability is what permits the two handlers below, and a
     // deployment with no view must not declare it — a client would then list
@@ -554,12 +607,12 @@ export class McpService {
         },
         // `instructions` rides the initialize result; clients that honour it
         // place the text in the model's system prompt without the model acting.
-        ...(initializing ? { instructions: (await agentInstructions()).instructions } : {}),
+        ...(initializing ? { instructions: await handshakeInstructions() } : {}),
       },
     );
 
     server.setRequestHandler(ListToolsRequestSchema, async () => inRequest(async () => {
-      const [{ tools, catalogNames }, { toolPrefix }, readOnly] = await Promise.all([
+      const [{ tools, catalogNames, connection }, { toolPrefix }, readOnly] = await Promise.all([
         requestSurface(),
         agentInstructions(),
         // A failed read lists the built-in hints rather than no listing at all.
@@ -568,6 +621,12 @@ export class McpService {
           return undefined;
         }),
       ]);
+      // A connection whose agent configuration cannot be used is served NOTHING — not
+      // Everything — and the one sentence saying why rides the listing's
+      // `_meta` (the handshake carries it too).
+      if (connection?.unavailable) {
+        return { tools: [], _meta: { [CONNECTION_META_KEY]: connection.unavailable } };
+      }
       // A discovered tool whose name collides with a meta-tool would be
       // listed but never callable (the dispatcher routes the name to the
       // meta-tool first), so drop it from the listing entirely.
@@ -694,7 +753,10 @@ export class McpService {
     }
 
     server.setRequestHandler(CallToolRequestSchema, async (request, extra) => inRequest(async () => {
-      const { client: shared, tools, unavailable, catalogNames, hidden: hiddenTools } = await requestSurface();
+      const { client: shared, tools, unavailable, catalogNames, hidden: hiddenTools, connection } = await requestSurface();
+      // Nothing is callable on a connection that loads nothing, meta-tools
+      // included: every call is answered with the reason.
+      if (connection?.unavailable) return toolError(connection.unavailable);
       // The person's client, as this request uses it: every call it makes —
       // a chain's too, which comes back from the isolate outside any async
       // context — carries this request's bearer and audit.
@@ -769,7 +831,16 @@ export class McpService {
         if (answer && owner && audit) {
           await audit.denied(`${owner.utcpName}.${toolName.slice(owner.utcpName.length + 1)}`, args);
         }
-        return answer ?? toolError(retiredToolMessage(toolName) ?? `Unknown tool "${toolName}".`);
+        // On a narrowed connection, a tool off the surface is one its agent
+        // does not load: refused by name and agent, never "unknown" — the tool
+        // may well exist, for this person, on another connection.
+        return (
+          answer ??
+          toolError(
+            retiredToolMessage(toolName) ??
+              (connection ? connectionRefusal(toolName, connection) : `Unknown tool "${toolName}".`),
+          )
+        );
       }
       const needsAuth = await needsAuthorization(proxied.manualName);
       if (needsAuth) {
@@ -879,9 +950,20 @@ export class McpService {
    */
   private async surfaceFor(caller: McpCaller, loopbackBearer: string): Promise<RequestSurface> {
     const { userId, tokenId } = caller;
-    const revision = await this.fetchCatalogRevision(loopbackBearer);
+    const { revision } = await this.fetchCatalogRevision(loopbackBearer);
     if (revision === null) return this.buildSurface(userId, tokenId, loopbackBearer, 'uncached');
-    const key = [userId, tokenId != null ? 'key' : 'person', caller.scope ?? 'write', revision].join(POOL_KEY_SEPARATOR);
+    // The agent the connection was made as is part of the key: two
+    // connections of one person made as different agents are two surfaces.
+    // (The revision already moves when the agent's FILE changes — it carries
+    // the file's digest — so an edit is a new build at the next request.)
+    // Everything adds nothing, and keeps the key it always had.
+    const key = [
+      userId,
+      tokenId != null ? 'key' : 'person',
+      caller.scope ?? 'write',
+      revision,
+      ...(caller.agentPath ? [caller.agentPath] : []),
+    ].join(POOL_KEY_SEPARATOR);
     const { value } = await this.surfaces.get(
       key,
       () => this.buildSurface(userId, tokenId, loopbackBearer, 'miss'),
@@ -893,10 +975,13 @@ export class McpService {
   /**
    * The caller's catalog revision (`GET /api/agent/catalog-revision`, the one
    * `hexis-mcp` polls), read with their bearer; null when it cannot be read.
+   * With it, the agent the caller's connection is narrowed to, when it is.
    * A deployment or a test that does not serve the route answers 404, which
    * is not worth a line in the log; anything else is.
    */
-  private async fetchCatalogRevision(bearer: string): Promise<string | null> {
+  private async fetchCatalogRevision(
+    bearer: string,
+  ): Promise<{ revision: string | null; connection?: ConnectionScopeWire }> {
     try {
       const res = await fetch(`${this.opts.loopbackBaseUrl}/api/agent/catalog-revision`, {
         headers: { Authorization: `Bearer ${bearer}` },
@@ -904,13 +989,16 @@ export class McpService {
       });
       if (!res.ok) {
         if (res.status !== 404) log.warn(`catalog-revision loopback failed: HTTP ${res.status}; building this request's surface uncached`);
-        return null;
+        return { revision: null };
       }
-      const body = (await res.json()) as { revision?: unknown };
-      return typeof body.revision === 'string' && body.revision ? body.revision : null;
+      const body = (await res.json()) as { revision?: unknown; connection?: unknown };
+      return {
+        revision: typeof body.revision === 'string' && body.revision ? body.revision : null,
+        ...connectionOf(body),
+      };
     } catch (err) {
       log.warn("catalog-revision loopback threw; building this request's surface uncached:", { err });
-      return null;
+      return { revision: null };
     }
   }
 
@@ -935,7 +1023,7 @@ export class McpService {
     // The list of manuals this caller gets: the KB manual + each `.tool` they
     // can read. Fetched over loopback with the caller's key, so ACL filtering
     // lives ONCE behind the REST surface.
-    const manuals = await this.fetchManualTemplates(loopbackBearer);
+    const { manuals, connection } = await this.fetchManualTemplates(loopbackBearer);
     const catalogMs = performance.now() - started;
     const client = await this.buildClient(userId, manuals);
     const discovered = await this.discoverTools(client, manuals, userId);
@@ -960,7 +1048,7 @@ export class McpService {
           (decision.suppressed > 0 ? ` [+${decision.suppressed} identical rebuild(s) since last line]` : ''),
       );
     }
-    return { ...discovered, client, tools };
+    return { ...discovered, client, tools, ...(connection ? { connection } : {}) };
   }
 
   /**
@@ -1039,11 +1127,13 @@ export class McpService {
    * request. HTTP transport loses the `CallTemplate` type, so we re-validate the
    * received JSON even though the producing endpoint already validated it.
    */
-  private async fetchManualTemplates(bearer: string): Promise<CallTemplate[]> {
+  private async fetchManualTemplates(
+    bearer: string,
+  ): Promise<{ manuals: CallTemplate[]; connection?: ConnectionScopeWire }> {
     // This is the REMOTE proxy, so ask for remote-capable manuals only — local-only
     // `.tool`s are surfaced instead via the `list_local_tools` tool in the KB manual.
     const body = (await this.loopbackJson(bearer, '/api/agent/all-tools?remote=true', 'all-tools')) as
-      | { manuals?: unknown }
+      | { manuals?: unknown; connection?: unknown }
       | null;
     const rawManuals: unknown[] = Array.isArray(body?.manuals) ? body.manuals : [];
 
@@ -1062,7 +1152,7 @@ export class McpService {
     }
     // Always include the KB manual, even if `all-tools` was unavailable/regressed.
     if (!hasKb) out.unshift(this.kbManualTemplate());
-    return out;
+    return { manuals: out, ...connectionOf(body) };
   }
 
   /** The KB manual's discovery template — the fallback if `all-tools` is unavailable. */
@@ -1600,41 +1690,11 @@ export class McpService {
     const statusMap = new Map(status.map((s) => [s.key, s]));
     const missing: { name: string; label?: string | null; brokenSignIn: boolean }[] = [];
     for (const v of userVars) {
-      const st = statusMap.get(v.key);
+      // The one readiness rule `list_tool_setup` reports from (`userSecretGap`).
       // A sign-in the caller already HAS a row for but that isn't (or is no
-      // longer) usable: dead/wiped grant, abandoned consent, missing scopes.
-      const brokenSignIn = Boolean(v.oauth && st?.userConfigured);
-      if (!st?.userConfigured) {
-        missing.push({ name: v.name, label: v.label, brokenSignIn }); // no row at all → needs a value / sign-in
-        continue;
-      }
-      // A row of the OTHER kind is not this credential: a `.tool` edited from
-      // an OAuth sign-in to a plain key (or back) leaves the old row behind,
-      // and serving a token where a key is declared — or a key where a
-      // sign-in is — fails opaquely at the provider. Not a broken sign-in
-      // either: nothing to reset, the user has to set the credential up as
-      // the manual now declares it.
-      const declaredKind = v.oauth ? 'oauth' : 'static';
-      if (st.userKind && st.userKind !== declaredKind) {
-        missing.push({ name: v.name, label: v.label, brokenSignIn: false });
-        continue;
-      }
-      // An OAuth-backed var whose row exists but has no token yet is NOT ready —
-      // the user has registered but not completed sign-in. Fail closed: anything
-      // other than a confirmed `true` (including a non-oauth row → undefined)
-      // counts as not-yet-authorized.
-      if (v.oauth && st.userAuthorized !== true) {
-        missing.push({ name: v.name, label: v.label, brokenSignIn });
-        continue;
-      }
-      // An OAuth-backed var the user signed in for, but whose token was granted
-      // fewer scopes than the tool now declares, is ALSO not ready — the call would
-      // otherwise fail opaquely at the provider. Compare the live required scopes
-      // against the token's recorded granted scopes; an under-scoped (or unknown)
-      // token needs re-authorization.
-      if (v.oauth && !scopesCovered(v.oauthScopes, st.grantedScopes)) {
-        missing.push({ name: v.name, label: v.label, brokenSignIn });
-      }
+      // longer) usable is a broken sign-in: abandoned consent, missing scopes.
+      const gap = userSecretGap(v, statusMap.get(v.key));
+      if (gap) missing.push({ name: v.name, label: v.label, brokenSignIn: gap === 'unauthorized' || gap === 'under-scoped' });
     }
     return missing;
   }