@bevel-software/platform-core-backend 0.32.0 → 0.34.0

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

@@ -37,6 +37,7 @@ import {
   installSessionRecovery,
   flattenManualTool,
   toListedTool,
+  withReadOnlyOverride,
   toolError,
   retiredToolMessage,
   needsAuthorizationResult,
@@ -49,18 +50,13 @@ import {
   type LoadedSkill,
 } from '@bevel-software/platform-mcp-core';
 import type { KbLayout } from '@bevel-software/platform-shared';
-import { bevelSecretsLoaderConfig } from '../secrets-vault/index.js';
-import {
-  scopesCovered,
-  type ForcedRefreshOutcome,
-  type ISecretsVaultService,
-} from '../secrets-vault/secrets-vault.contract.js';
-import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/tool-manuals.contract.js';
-import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.js';
-import type { SpillStore } from '../workspace/spill-store.js';
+import { bevelSecretsLoaderConfig, type ForcedRefreshOutcome, type ISecretsVaultService, scopesCovered } 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';
 import type { HiddenToolSource } from '../../shared/hidden-tools.js';
 import { seedBevelHostedManualVars } from '../../shared/utcp-namespace.js';
-import type { InternalTokenService } from '../tool-auth/internal-token.service.js';
+import type { InternalTokenService } from '../tool-auth/index.js';
 import { RequestAudit, type IAgentEventRecorder, type RecordedPrincipal } from '../audit/index.js';
 import { ManualFailureMemo } from './manual-failure-memo.js';
 import { DownstreamPool, POOL_KEY_SEPARATOR, type DownstreamPoolOptions, type Lease } from './downstream-pool.js';
@@ -78,7 +74,17 @@ import {
   type AgentPreambleReader,
   type ComposedAgentInstructions,
 } from '../agent-instructions/index.js';
-import { guideFirstDescription } from '../tool-registry/guide-first.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
@@ -123,6 +129,16 @@ export interface McpProxyOptions {
    * knowledge base's.
    */
   secretsScope?: string;
+  /**
+   * The deployment's read-only overrides, by tool name, read per listing so an
+   * admin's change on the Tools page is in the next `tools/list`. Joined on
+   * here, at listing time, for the platform tools and the code-mode meta-tools
+   * alike: the platform tools' BUILT-IN hint arrives as the manual's
+   * `read-only` tag, in a surface that is cached across requests, so an
+   * override baked into it would outlive the toggle that set it. Absent, every
+   * tool lists its built-in hint.
+   */
+  readOnlyOverrides?: () => Promise<Readonly<Record<string, boolean>>>;
 }
 
 /** Who a request is from — everything the proxy needs, resolved from that request's own bearer. */
@@ -136,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;
   /**
@@ -216,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 } : {};
 }
 
 /**
@@ -484,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
@@ -528,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
@@ -548,12 +607,26 @@ 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 }] = await Promise.all([requestSurface(), agentInstructions()]);
+      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.
+        this.opts.readOnlyOverrides?.().catch((err: unknown) => {
+          log.warn('tools/list: could not read the read-only overrides; listing built-in hints.', { err });
+          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.
@@ -590,7 +663,9 @@ export class McpService {
         // place for it), so it is joined on here — the one point where a
         // discovered tool becomes a listing entry.
         const ui = apps && Object.hasOwn(apps.tools, t.mcpName) ? apps.tools[t.mcpName] : undefined;
-        const entry = toListedTool(ui ? { ...t, ui } : t); // logs its own reason on a name/schema drop
+        // An admin's override of a platform tool's hint, read for THIS listing.
+        const hinted = withReadOnlyOverride(t, readOnly);
+        const entry = toListedTool(ui ? { ...hinted, ui } : hinted); // logs its own reason on a name/schema drop
         if (!entry) {
           dropped.push(t.mcpName);
           continue;
@@ -641,6 +716,7 @@ export class McpService {
       // built here, so here it is.
       const metaTools = codeModeMetaTools(EXTERNAL_KB_MANUAL_NAME, examplePool, {
         sharedRulesPointer: '',
+        ...(readOnly ? { readOnly } : {}),
       }).map((tool) => ({ ...tool, description: guideFirstDescription(tool.description) }));
       // Log only when a tool was dropped (name/schema/duplicate) — that's the
       // anomaly worth surfacing, since a downstream client would otherwise hide
@@ -677,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.
@@ -752,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) {
@@ -862,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'),
@@ -876,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}` },
@@ -887,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 };
     }
   }
 
@@ -918,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);
@@ -943,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 } : {}) };
   }
 
   /**
@@ -1022,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 : [];
 
@@ -1045,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. */

package/src/modules/mcp/oauth/bevel-oauth-provider.ts

@@ -21,8 +21,8 @@ import type {
   OAuthTokens,
 } from '@modelcontextprotocol/sdk/shared/auth.js';
 import type { AgentConnectedEvent } from '@bevel-software/platform-shared';
-import type { Database } from '../../database/connection.js';
-import { agentConnections, oauthAuthCodes, oauthClients, oauthTokens, users } from '../../database/schema.js';
+import type { Database } from '../../database/index.js';
+import { agentConnections, oauthAuthCodes, oauthClients, oauthTokens, users } from '../../database/index.js';
 import type { TokenCrypto } from '../../../shared/token-crypto.js';
 import { signAuthRequest, type McpAuthRequestState } from './oauth-state.js';
 
@@ -199,10 +199,16 @@ export class BevelOAuthProvider implements OAuthServerProvider {
    * Called by the Finish endpoint once an authenticated user completes the
    * /connect step: bind a one-time code to (user, client, redirect_uri, PKCE
    * challenge) and hand back the client redirect the browser should follow.
+   *
+   * @param agentPath The "Connect as" choice — an agent configuration the consent
+   *   route has already checked the person may choose — or null for
+   *   Everything. Carried on the code to the exchange, which records it on
+   *   the agent connection.
    */
   async issueAuthCode(
     userId: string,
     st: McpAuthRequestState,
+    agentPath: string | null = null,
   ): Promise<{ redirectTo: string }> {
     // A state without a PKCE challenge is a Claude-link request, which the
     // marketplace bridge finishes; it must never reach the SDK's code store.
@@ -217,6 +223,7 @@ export class BevelOAuthProvider implements OAuthServerProvider {
       scope: st.sc ?? null,
       resource: st.rs ?? null,
       expiresAt: new Date(Date.now() + CODE_TTL_MS),
+      ...(agentPath ? { agentPath } : {}),
     });
     const redirect = new URL(st.r);
     redirect.searchParams.set('code', code);
@@ -269,7 +276,7 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     if (redirectUri && redirectUri !== row.redirectUri) {
       throw new InvalidGrantError('redirect_uri does not match the authorization request');
     }
-    return this.mintTokens(row.userId, row.clientId, row.scope, row.resource);
+    return this.mintTokens(row.userId, row.clientId, row.scope, row.resource, undefined, undefined, row.agentPath ?? null);
   }
 
   async exchangeRefreshToken(
@@ -463,6 +470,7 @@ export class BevelOAuthProvider implements OAuthServerProvider {
         id: oauthTokens.id,
         clientId: oauthTokens.clientId,
         connectionId: oauthTokens.connectionId,
+        agentPath: agentConnections.agentPath,
         scope: oauthTokens.scope,
         resource: oauthTokens.resource,
         expiresAt: oauthTokens.expiresAt,
@@ -507,6 +515,10 @@ export class BevelOAuthProvider implements OAuthServerProvider {
         // Null on a token minted before connections existed; the auth
         // middleware then binds no agent and the call goes unrecorded.
         connectionId: row.connectionId,
+        // The connection's "Connect as" choice, read off the row on every
+        // verification, so a re-consent with another choice reaches the
+        // agent's very next request. Null is Everything.
+        agentPath: row.agentPath ?? null,
       },
     };
   }
@@ -575,6 +587,9 @@ export class BevelOAuthProvider implements OAuthServerProvider {
    *   first mint, which finds or makes the live connection for (user, client).
    * @param tx The transaction the insert belongs to, when the mint must land
    *   with the statement that consumed the token it replaces (a refresh).
+   * @param agentPath The consent's "Connect as" choice, recorded on the
+   *   connection the pair is bound to (null: Everything). Only a first mint —
+   *   a consent — passes it; a refresh leaves the connection's choice alone.
    *   The prune is then the caller's, before the transaction opens: a
    *   best-effort statement that fails inside a transaction would abort the
    *   mint it is meant to spare, and one on the pool from inside it would
@@ -587,6 +602,7 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     resource: string | null,
     connectionId?: string,
     tx?: Tx,
+    agentPath?: string | null,
   ): Promise<OAuthTokens> {
     const accessToken = this.deps.tokenPrefix + randomBytes(TOKEN_BYTES).toString('base64url');
     const refreshToken = this.refreshPrefix + randomBytes(TOKEN_BYTES).toString('base64url');
@@ -594,7 +610,7 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     // A mint of its own (a sign-in) prunes here; a refresh pruned before its
     // transaction opened.
     if (!tx) await this.pruneTokenTables(now);
-    const boundTo = connectionId ?? (await this.ensureConnection(userId, clientId));
+    const boundTo = connectionId ?? (await this.ensureConnection(userId, clientId, agentPath));
     const sink: Tx | Database = tx ?? this.deps.db;
     await sink.insert(oauthTokens).values({
       accessTokenHash: hashToken(accessToken),
@@ -665,12 +681,23 @@ export class BevelOAuthProvider implements OAuthServerProvider {
    * revoke. A read, not a write: the use is stamped separately, throttled.
    */
   async isConnectionLive(connectionId: string): Promise<boolean> {
+    return (await this.liveConnectionChoice(connectionId)) !== null;
+  }
+
+  /**
+   * A live agent connection's current "Connect as" choice (`agentPath` null
+   * = Everything), or null when the connection is gone or revoked. Read on
+   * every request through the local server's exchanged grant: that token is
+   * stateless and outlives a re-consent, so the choice it was minted with is
+   * not the one it is served as — the row's is.
+   */
+  async liveConnectionChoice(connectionId: string): Promise<{ agentPath: string | null } | null> {
     const [row] = await this.deps.db
-      .select({ id: agentConnections.id })
+      .select({ agentPath: agentConnections.agentPath })
       .from(agentConnections)
       .where(and(eq(agentConnections.id, connectionId), isNull(agentConnections.revokedAt)))
       .limit(1);
-    return row !== undefined;
+    return row ? { agentPath: row.agentPath ?? null } : null;
   }
 
   /**
@@ -737,8 +764,13 @@ export class BevelOAuthProvider implements OAuthServerProvider {
    * the other's `ON CONFLICT DO NOTHING` returns no row, and it re-reads the
    * winner's. The client's display name is snapshotted from its registration
    * at that moment.
+   *
+   * `agentPath` is a consent's "Connect as" choice: written on the row made,
+   * and on the live row found — the person's latest consent is what the agent
+   * connects as. `undefined` (a refresh of a token from before connections
+   * existed) leaves a found row's choice as it is.
    */
-  private async ensureConnection(userId: string, clientId: string): Promise<string> {
+  private async ensureConnection(userId: string, clientId: string, agentPath?: string | null): Promise<string> {
     const [client] = await this.deps.db
       .select({ clientName: oauthClients.clientName })
       .from(oauthClients)
@@ -758,11 +790,17 @@ export class BevelOAuthProvider implements OAuthServerProvider {
           ),
         )
         .limit(1);
+    const choose = async (id: string): Promise<string> => {
+      if (agentPath !== undefined) {
+        await this.deps.db.update(agentConnections).set({ agentPath }).where(eq(agentConnections.id, id));
+      }
+      return id;
+    };
     const [existing] = await live();
-    if (existing) return existing.id;
+    if (existing) return choose(existing.id);
     const [inserted] = await this.deps.db
       .insert(agentConnections)
-      .values({ userId, clientId, clientName, agentKey })
+      .values({ userId, clientId, clientName, agentKey, ...(agentPath ? { agentPath } : {}) })
       .onConflictDoNothing({
         target: [agentConnections.userId, agentConnections.agentKey],
         where: sql`${agentConnections.revokedAt} is null`,
@@ -771,7 +809,7 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     if (inserted) return inserted.id;
     const [winner] = await live();
     if (!winner) throw new Error('agent connection vanished between insert and re-read');
-    return winner.id;
+    return choose(winner.id);
   }
 }
 

package/src/modules/mcp/oauth/oauth-consent.routes.ts

@@ -4,7 +4,8 @@ import { logger } from '../../../shared/logging.js';
 const log = logger('mcp-oauth');
 import type { BevelOAuthProvider } from './bevel-oauth-provider.js';
 import { verifyAuthRequest, type McpAuthRequestState } from './oauth-state.js';
-import '../../auth/auth.middleware.js'; // Express Request augmentation (req.userId / req.userEmail)
+import type { IAgentScopeResolver } from '../../agent-scope/index.js';
+import '../../auth/index.js'; // Express Request augmentation (req.userId / req.userEmail)
 
 export interface OAuthConsentRoutesDeps {
   provider: BevelOAuthProvider;
@@ -21,8 +22,17 @@ export interface OAuthConsentRoutesDeps {
     clientNameFor(st: McpAuthRequestState): string;
     completeConsent(userId: string, st: McpAuthRequestState): Promise<{ redirectTo: string }>;
   };
+  /**
+   * The "Connect as" choices: the agent configurations the person may connect an
+   * MCP client as, offered below Everything. Absent, the consent offers
+   * Everything alone and Finish refuses any other choice.
+   */
+  agents?: Pick<IAgentScopeResolver, 'listChoices' | 'choosable'>;
 }
 
+/** The refusal of a choice that is not one of the person's — one answer for missing and unreadable. */
+export const NOT_AN_AGENT_CHOICE = 'That agent is not one you can connect as. Choose Everything or one of the agents listed.';
+
 /**
  * The authenticated tail of the MCP OAuth flow. `/authorize` (SDK-owned)
  * validated the client's request, packed it into a signed state, and sent the
@@ -49,10 +59,25 @@ export function createOAuthConsentRoutes(deps: OAuthConsentRoutesDeps): express.
       return;
     }
     const client = await deps.provider.clientsStore.getClient(st.c);
+    // Everything is not in the list: it is the choice every consent has, and
+    // the one the page selects. A failure to read the agents costs the choice
+    // of an agent, never the consent itself — but it is SAID
+    // (`agentsUnavailable`), so the page does not pass an empty list off as
+    // "you have no agents" and approve Everything unasked.
+    let agentsUnavailable = false;
+    const agents = deps.agents && req.userEmail
+      ? await deps.agents.listChoices(req.userEmail).catch((err: unknown) => {
+          log.warn('listing the agents to connect as failed:', { detail: err instanceof Error ? err.message : String(err) });
+          agentsUnavailable = true;
+          return [];
+        })
+      : [];
     res.json({
       clientName: client?.client_name ?? null,
       scope: st.sc ?? null,
       resource: st.rs ?? null,
+      agents,
+      ...(agentsUnavailable ? { agentsUnavailable: true } : {}),
     });
   });
 
@@ -65,10 +90,25 @@ export function createOAuthConsentRoutes(deps: OAuthConsentRoutesDeps): express.
     const st = raw ? verifyAuthRequest(deps.stateSecret, raw) : null;
     if (!st) return void res.status(400).json({ error: 'Invalid or expired authorization request. Restart the connection from your agent.' });
     if (st.gh && !deps.facade) return void res.status(400).json({ error: NO_FACADE });
+    // "Connect as": absent, null or empty is Everything. Anything else must be
+    // an agent the person may choose right now — checked here, at the only
+    // place a choice is made, so the token exchange records it as given.
+    const asked: unknown = (req.body ?? {}).agentPath;
+    if (asked !== undefined && asked !== null && typeof asked !== 'string') {
+      return void res.status(400).json({ error: NOT_AN_AGENT_CHOICE });
+    }
+    const choosing = typeof asked === 'string' && asked.trim() !== '';
+    // An account linked through the GitHub facade has no agent connection to
+    // record a choice on.
+    if (choosing && (st.gh || !deps.agents || !req.userEmail)) {
+      return void res.status(400).json({ error: NOT_AN_AGENT_CHOICE });
+    }
     try {
+      const agentPath = choosing && deps.agents && req.userEmail ? await deps.agents.choosable(req.userEmail, asked as string) : null;
+      if (choosing && agentPath === null) return void res.status(400).json({ error: NOT_AN_AGENT_CHOICE });
       const { redirectTo } = st.gh && deps.facade
         ? await deps.facade.completeConsent(userId, st)
-        : await deps.provider.issueAuthCode(userId, st);
+        : await deps.provider.issueAuthCode(userId, st, agentPath);
       res.json({ redirectTo });
     } catch (err) {
       // Message only — the raw error object can carry sensitive context

package/src/modules/onboarding/onboarding.routes.ts

@@ -3,7 +3,7 @@ import type { AuthUser } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
 import type { IStarterPackService } from './onboarding.contract.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation (req.userId)
+import '../auth/index.js'; // Express Request augmentation (req.userId)
 
 const log = logger('starter-packs');
 

package/src/modules/onboarding/starter-pack.service.ts

@@ -64,11 +64,10 @@ import {
 import { logger } from '../../shared/logging.js';
 import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../shared/domain-errors.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { IAdminAccessService } from '../admin/admin.interface.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
-import type { FileChangeNotifier } from '../kb-fs/file-change-notifier.js';
-import { LockingFilesystem } from '../kb-fs/locking-filesystem.js';
-import type { WorkspaceMutex } from '../kb-fs/mutex.js';
+import type { IAdminAccessService } from '../admin/index.js';
+import type { IAccessControl } from '../access/index.js';
+import type { FileChangeNotifier, WorkspaceMutex } from '../kb-fs/index.js';
+import { LockingFilesystem } from '../kb-fs/index.js';
 import type { IFsProbe, ITreeWalker } from '../../shared/fs.contract.js';
 import {
   isUntouchedStarterPage,
@@ -76,7 +75,7 @@ import {
   type FirstRunStarter,
   type FirstRunStarterSource,
   type MayRead,
-} from '../workspace/first-run.js';
+} from '../workspace/index.js';
 import { pluginAccessMd, withCreatorGrants, type PluginSource } from '../plugins/index.js';
 import {
   NO_STARTER_PACK,

package/src/modules/plugins/__tests__/bundle-dialect.e2e.test.ts

@@ -8,6 +8,7 @@ import { testKbContext } from '../../../__tests__/kb-context.js';
 
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import { AccessControlService } from '../../access/access-control.service.js';
+import { AccessMutationService } from '../../access/access-mutation.service.js';
 import { SkillService } from '../../skills/skills.service.js';
 import { ToolManualService } from '../../tool-manuals/tool-manuals.service.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
@@ -103,7 +104,7 @@ describe('bundle dialect, end to end', () => {
     links = new PluginLinkIndex(workspaceService, skills, access, kb, source);
     index = new PluginIndexService(workspaceService, access, skills, tools, kb, source, Date.now, links);
     compiler = new MarketplaceCompilerService(workspaceService, access, skills, links, kb, { name: 'acme', owner: 'Acme' }, source, disk, new NodeGitRunner());
-    linkService = new PluginLinksService(workspaceService, { runPendingCommit: async () => undefined }, access, skills, links, kb);
+    linkService = new PluginLinksService(workspaceService, { runPendingCommit: async () => undefined }, access, new AccessMutationService(workspaceService, access, kb.kbDirName), skills, links, kb);
   });
   afterEach(async () => {
     await fs.rm(root, { recursive: true, force: true });

package/src/modules/plugins/__tests__/plugin-links.service.test.ts

@@ -8,6 +8,7 @@ import { DEFAULT_BRANCH, withLinkedSkillRoots, type AuthUser } from '@bevel-soft
 
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import { AccessControlService } from '../../access/access-control.service.js';
+import { AccessMutationService } from '../../access/access-mutation.service.js';
 import { SkillService } from '../../skills/skills.service.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { PluginLinkIndex } from '../plugin-links.js';
@@ -98,7 +99,7 @@ describe('PluginLinksService', () => {
     const kb = testKbContext({ kbDirName: KB_DIR });
     skills = new SkillService(workspaceService, access, kb, disk);
     index = new PluginLinkIndex(workspaceService, skills, access, kb, new KbPluginSource(disk, kb));
-    svc = new PluginLinksService(workspaceService, driver, access, skills, index, kb);
+    svc = new PluginLinksService(workspaceService, driver, access, new AccessMutationService(workspaceService, access, kb.kbDirName), skills, index, kb);
   });
   afterEach(() => fs.rm(root, { recursive: true, force: true }));