@bevel-software/platform-core-backend 0.19.0 → 0.21.0

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

@@ -9,6 +9,7 @@ import type { InternalTokenService } from '../tool-auth/internal-token.service.j
 import { rejectConnectionKey } from '../tool-auth/connection-key-rejection.js';
 import type { BevelOAuthProvider } from './oauth/bevel-oauth-provider.js';
 import '../tool-auth/external-api-key.interface.js'; // Express Request augmentation (req.externalApiKeyId)
+import '../audit/audit.contract.js'; // Express Request augmentation (req.agentConnectionId)
 
 /**
  * Auth middleware for the MCP endpoint. Accepts any of:
@@ -111,6 +112,12 @@ export function createMcpAuthMiddleware(
         const info = await oauthProvider.verifyAccessToken(token);
         req.userId = String(info.extra?.userId ?? '');
         req.userEmail = String(info.extra?.userEmail ?? '');
+        // The agent behind the grant, for the Audit log. A token minted
+        // before connections existed carries none; the call then runs
+        // unattributed rather than refused.
+        if (typeof info.extra?.connectionId === 'string') {
+          req.agentConnectionId = info.extra.connectionId;
+        }
         if (!req.userId) {
           unauthorized(res, 'Invalid access token');
           return;
@@ -176,6 +183,30 @@ export function createMcpAuthMiddleware(
       }
       req.userId = user.id;
       req.userEmail = user.email;
+      // The local server's exchanged grant names its agent connection (see
+      // InternalTokenClaim.connectionId). The token itself is stateless and
+      // lives up to five hours, so the connection is asked on every request
+      // whether it still admits the agent — revoking the agent must reach
+      // this path as surely as it reaches the grant's own tokens. The use is
+      // 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.
+      if (claim.connectionId) {
+        let live: boolean;
+        try {
+          live = await oauthProvider.isConnectionLive(claim.connectionId);
+        } catch (err) {
+          log.error('agent-connection check failed:', { err });
+          res.status(500).json({ error: 'Authentication backend unavailable' });
+          return;
+        }
+        if (!live) {
+          unauthorized(res, 'Access for this agent was revoked');
+          return;
+        }
+        oauthProvider.noteConnectionUse(claim.connectionId);
+        req.agentConnectionId = claim.connectionId;
+      }
       next();
       return;
     }

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

@@ -115,6 +115,10 @@ export function createMcpRoutes(
           // undefined for OAuth/JWT) — resolved per request, so per-key metering
           // never depends on anything remembered from an earlier request.
           tokenId: req.externalApiKeyId ?? null,
+          // Agent-connection id (set for OAuth bearers and the local server's
+          // exchanged grant; undefined for keys/JWTs) — the Audit log's other
+          // principal, resolved per request like the key id.
+          connectionId: req.agentConnectionId ?? null,
           // 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),
@@ -355,7 +359,13 @@ export function createMcpRoutes(
         grantRemainingMs === undefined
           ? MCP_LOOPBACK_TOKEN_TTL_MS
           : Math.min(MCP_LOOPBACK_TOKEN_TTL_MS, grantRemainingMs);
-      const minted = internalTokens.mint({ userId, externalProxy: true }, ttlMs);
+      // 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;
+      const minted = internalTokens.mint(
+        { userId, externalProxy: true, ...(connectionId ? { connectionId } : {}) },
+        ttlMs,
+      );
       // The ACTUAL lifetime, not the constant — the caller schedules its
       // proactive renewal off this number.
       res.json({ token: minted, expiresInMs: ttlMs });

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

@@ -54,6 +54,8 @@ import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.j
 import type { SpillStore } from '../workspace/spill-store.js';
 import { seedBevelHostedManualVars } from '../../shared/utcp-namespace.js';
 import type { InternalTokenService } from '../tool-auth/internal-token.service.js';
+import type { IAgentEventRecorder } from '../audit/audit.contract.js';
+import { RequestAudit } from '../audit/request-audit.js';
 import { ManualFailureMemo } from './manual-failure-memo.js';
 import { DownstreamPool, POOL_KEY_SEPARATOR, type DownstreamPoolOptions, type Lease } from './downstream-pool.js';
 import { SurfaceLogThrottle } from './surface-log-throttle.js';
@@ -91,6 +93,13 @@ export interface McpProxyOptions {
   readAgentPreamble?: AgentPreambleReader;
   /** Bounds of the downstream (`mcp.json`) connection pool; defaults are 4h idle / 5000 entries. */
   downstreamPool?: Pick<DownstreamPoolOptions<unknown>, 'idleTtlMs' | 'maxEntries' | 'now'>;
+  /**
+   * The scope this knowledge base's secrets vault was registered under (see
+   * `secrets-variable-loader.ts`), so the UTCP clients built here resolve a
+   * caller's `${VAR}`s from that vault and no other's. Default: the single
+   * knowledge base's.
+   */
+  secretsScope?: string;
 }
 
 /** Who a request is from — everything the proxy needs, resolved from that request's own bearer. */
@@ -98,6 +107,12 @@ export interface McpCaller {
   userId: string;
   /** The connection-key id (per-key metering rides on it), or null for an OAuth/JWT bearer. */
   tokenId: string | null;
+  /**
+   * The agent connection behind an OAuth bearer (or the local server's
+   * exchanged grant), or null. With `tokenId`, the two ways a call is
+   * attributed in the Audit log; a request with neither records nothing.
+   */
+  connectionId?: string | null;
   /** The raw bearer the request carried. */
   bearer: string;
 }
@@ -268,6 +283,10 @@ export class McpService {
     // authorization when one of its TOOL sign-ins breaks. Optional: without
     // it, broken sign-ins surface only as the /connect link in the result.
     private readonly revokeOAuthAccess?: (bearer: string) => Promise<void>,
+    // The Audit log's recorder: every tool call, skill read and meta-tool run
+    // of a request that arrived with a key or an agent connection goes
+    // through it. Optional like the others; without it nothing is recorded.
+    private readonly auditRecorder?: IAgentEventRecorder,
   ) {
     this.downstream = new DownstreamPool<PooledDownstream>({
       ...opts.downstreamPool,
@@ -332,6 +351,7 @@ export class McpService {
    */
   async createRequestServer(caller: McpCaller, messages: unknown): Promise<Server> {
     const { userId, tokenId, bearer } = caller;
+    const connectionId = caller.connectionId ?? null;
     // The loopback surface (`/api/agent/*`) accepts connection keys and
     // internal tokens only. A connection-key request passes the caller's own
     // key through (per-key metering rides on it); an OAuth/JWT request's
@@ -347,8 +367,30 @@ export class McpService {
 
     let instructions: Promise<ComposedAgentInstructions> | undefined;
     const agentInstructions = () => (instructions ??= this.composeAgentInstructions());
+    // The Audit log's view of this request — only when the request can be
+    // attributed to a key or an agent connection. The catalog names it
+    // classifies pooled tools by are the surface's, which is built lazily
+    // below, so it reads them through a holder the surface fills in.
+    const catalogNamesHolder: { current: ReadonlyMap<string, string> } = { current: new Map() };
+    const principal = tokenId != null ? { kind: 'key' as const, id: tokenId } : connectionId ? { kind: 'agent' as const, id: connectionId } : null;
+    const audit =
+      this.auditRecorder && principal
+        ? new RequestAudit(this.auditRecorder, userId, principal, {
+            kbManualName: EXTERNAL_KB_MANUAL_NAME,
+            catalogNames: () => catalogNamesHolder.current,
+            loadSkills: () =>
+              this.fetchSkillList(loopbackBearer).then((skills) =>
+                skills.flatMap((s) => (s.path ? [{ name: s.name, path: s.path }] : [])),
+              ),
+          })
+        : null;
     let surface: Promise<RequestSurface> | undefined;
-    const requestSurface = () => (surface ??= this.buildSurface(userId, tokenId, loopbackBearer));
+    const requestSurface = () =>
+      (surface ??= this.buildSurface(userId, tokenId, loopbackBearer).then((built) => {
+        catalogNamesHolder.current = built.catalogNames;
+        audit?.instrumentChainCalls(built.client);
+        return built;
+      }));
 
     const initializing = (Array.isArray(messages) ? messages : [messages]).some((m) => isInitializeRequest(m));
     const server = new Server(
@@ -432,8 +474,12 @@ export class McpService {
     server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
       const { client, tools, unavailable, catalogNames } = await requestSurface();
       const toolName = request.params.name;
+      const args = request.params.arguments ?? {};
       if (META_TOOL_NAMES.has(toolName)) {
-        return this.dispatchMetaTool(client, toolName, request.params.arguments ?? {});
+        // A meta-tool is the platform's own; its inner tool calls (a chain's)
+        // are recorded one by one through the instrumented client.
+        const run = () => this.dispatchMetaTool(client, toolName, args);
+        return audit ? audit.call(toolName, args, run, isErrorResult) : run();
       }
       /**
        * The needs-authorization answer, when the caller's sign-in for the
@@ -476,11 +522,18 @@ export class McpService {
           .filter((m) => toolName.startsWith(`${m.utcpName}_`))
           .sort((a, b) => b.utcpName.length - a.utcpName.length)[0];
         const answer = owner ? await needsAuthorization(owner.utcpName) : null;
+        if (answer && owner && audit) {
+          await audit.denied(`${owner.utcpName}.${toolName.slice(owner.utcpName.length + 1)}`, args);
+        }
         return answer ?? toolError(retiredToolMessage(toolName) ?? `Unknown tool "${toolName}".`);
       }
       const needsAuth = await needsAuthorization(proxied.manualName);
-      if (needsAuth) return needsAuth;
-      return this.dispatch(client, proxied, request, extra);
+      if (needsAuth) {
+        if (audit) await audit.denied(proxied.utcpName, args);
+        return needsAuth;
+      }
+      const run = () => this.dispatch(client, proxied, request, extra);
+      return audit ? audit.call(proxied.utcpName, args, run, isErrorResult) : run();
     });
 
     // Prompts = skills. Each skill becomes a user-callable prompt (slash command
@@ -499,7 +552,14 @@ export class McpService {
     });
 
     server.setRequestHandler(GetPromptRequestSchema, async (request): Promise<GetPromptResult> => {
+      const started = performance.now();
       const skill = await this.fetchSkill(loopbackBearer, request.params.name);
+      // A prompt IS a skill read — the same event `get_skill` produces.
+      audit?.emit(
+        { kind: 'skill', manual: skill?.path ?? null, name: request.params.name },
+        skill ? 'ok' : 'error',
+        Math.round(performance.now() - started),
+      );
       if (!skill) {
         throw new McpError(ErrorCode.InvalidParams, `Unknown skill "${request.params.name}".`);
       }
@@ -674,7 +734,7 @@ export class McpService {
    */
   private async buildClient(bearer: string, userId: string, manuals: CallTemplate[]): Promise<CodeModeUtcpClient> {
     const variables = seedBevelHostedManualVars(manuals, this.opts.loopbackBaseUrl, bearer);
-    return CodeModeUtcpClient.create(process.cwd(), utcpClientConfig(userId, variables));
+    return CodeModeUtcpClient.create(process.cwd(), utcpClientConfig(userId, variables, this.opts.secretsScope));
   }
 
   /**
@@ -906,7 +966,7 @@ export class McpService {
   private async connectDownstream(userId: string, template: CallTemplate): Promise<PooledDownstream> {
     // Third-party manuals are never seeded loopback credentials (see
     // `buildClient`), so a pooled client carries no request-scoped bearer.
-    const client = await CodeModeUtcpClient.create(process.cwd(), utcpClientConfig(userId, {}));
+    const client = await CodeModeUtcpClient.create(process.cwd(), utcpClientConfig(userId, {}, this.opts.secretsScope));
     // Our own copy: registration renames the template in place, and recovery
     // re-registers from exactly what discovery used.
     const own = structuredClone(template);
@@ -1176,16 +1236,21 @@ export class McpService {
   }
 }
 
+/** Whether a tool result is the tool saying it failed — what the Audit log records as `error`. */
+function isErrorResult(result: CallToolResult): boolean {
+  return result.isError === true;
+}
+
 /**
  * The UTCP client config for `userId`: the given variables, plus the per-user
  * `bevel-secrets` loader that resolves every `${SECRET}` ref lazily. Shared by
  * request clients and pooled downstream clients, so both resolve a manual's
  * variables through exactly the same tiers.
  */
-function utcpClientConfig(userId: string, variables: Record<string, string>) {
+function utcpClientConfig(userId: string, variables: Record<string, string>, secretsScope?: string) {
   return new UtcpClientConfigSerializer().validateDict({
     variables,
-    load_variables_from: [bevelSecretsLoaderConfig(userId)],
+    load_variables_from: [bevelSecretsLoaderConfig(userId, secretsScope)],
   });
 }
 

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

@@ -2,7 +2,7 @@ import { createHash, randomBytes } from 'node:crypto';
 import { logger } from '../../../shared/logging.js';
 
 const log = logger('mcp-oauth');
-import { and, eq, gt, isNull, lt, or } from 'drizzle-orm';
+import { and, count, eq, gt, isNull, lt, or, sql } from 'drizzle-orm';
 import type { Response } from 'express';
 import type {
   AuthorizationParams,
@@ -21,7 +21,7 @@ import type {
   OAuthTokens,
 } from '@modelcontextprotocol/sdk/shared/auth.js';
 import type { Database } from '../../database/connection.js';
-import { oauthAuthCodes, oauthClients, oauthTokens, users } from '../../database/schema.js';
+import { agentConnections, oauthAuthCodes, oauthClients, oauthTokens, users } from '../../database/schema.js';
 import type { TokenCrypto } from '../../../shared/token-crypto.js';
 import { signAuthRequest, type McpAuthRequestState } from './oauth-state.js';
 
@@ -34,6 +34,13 @@ const TOKEN_BYTES = 32;
 const ACCESS_TTL_MS = 60 * 60_000; // 1 hour
 const REFRESH_TTL_MS = 30 * 24 * 60 * 60_000; // 30 days, rotated on use
 const CODE_TTL_MS = 60_000; // exchanged within seconds of Finish
+/**
+ * How often, at most, one process stamps an agent connection's `last_used_at`.
+ * The Audit log shows the instant relatively ("4 minutes ago"), so a minute's
+ * staleness is invisible, while a write per request on a chain-heavy session
+ * would serialise hundreds of requests a minute on one row.
+ */
+const CONNECTION_TOUCH_INTERVAL_MS = 60_000;
 
 export interface BevelOAuthProviderDeps {
   db: Database;
@@ -66,6 +73,8 @@ export interface BevelOAuthProviderDeps {
  */
 export class BevelOAuthProvider implements OAuthServerProvider {
   private readonly store: OAuthRegisteredClientsStore;
+  /** When this process last stamped each connection's use — see {@link noteConnectionUse}. */
+  private readonly connectionTouchedAt = new Map<string, number>();
 
   constructor(private readonly deps: BevelOAuthProviderDeps) {
     this.store = {
@@ -276,15 +285,36 @@ export class BevelOAuthProvider implements OAuthServerProvider {
       }
       scope = scopes.join(' ');
     }
-    return this.mintTokens(row.userId, row.clientId, scope, row.resource);
+    // A refresh STAYS on its token's agent connection and is refused once
+    // that connection is revoked. The connection is the authority on whether
+    // the agent may hold tokens at all: were a refresh to look the connection
+    // up afresh, one racing a revoke would find none live, make a new one and
+    // mint an unrevoked pair — the revoke undone by a millisecond. A token
+    // from before connections existed has none to stay on and is placed
+    // under one as a first mint would be.
+    if (row.connectionId) {
+      if (!(await this.isConnectionLive(row.connectionId))) {
+        throw new InvalidGrantError('Access for this agent was revoked');
+      }
+      this.noteConnectionUse(row.connectionId);
+    }
+    return this.mintTokens(row.userId, row.clientId, scope, row.resource, row.connectionId ?? undefined);
   }
 
   async verifyAccessToken(token: string): Promise<AuthInfo> {
     const now = new Date();
+    // The agent connection is joined so a token of a REVOKED connection fails
+    // here whatever its own row says: revoking an agent marks its tokens too,
+    // but the connection is the authority, and a token minted a moment after
+    // the revoke (a refresh that raced it) is dead on arrival rather than
+    // live until its own expiry. A token from before connections existed
+    // (null `connection_id`) has no connection to be revoked and verifies on
+    // its own row alone.
     const [row] = await this.deps.db
       .select({
         id: oauthTokens.id,
         clientId: oauthTokens.clientId,
+        connectionId: oauthTokens.connectionId,
         scope: oauthTokens.scope,
         resource: oauthTokens.resource,
         expiresAt: oauthTokens.expiresAt,
@@ -293,11 +323,13 @@ export class BevelOAuthProvider implements OAuthServerProvider {
       })
       .from(oauthTokens)
       .innerJoin(users, eq(oauthTokens.userId, users.id))
+      .leftJoin(agentConnections, eq(oauthTokens.connectionId, agentConnections.id))
       .where(
         and(
           eq(oauthTokens.accessTokenHash, hashToken(token)),
           isNull(oauthTokens.revokedAt),
           gt(oauthTokens.expiresAt, now),
+          or(isNull(oauthTokens.connectionId), isNull(agentConnections.revokedAt)),
         ),
       )
       .limit(1);
@@ -311,13 +343,22 @@ export class BevelOAuthProvider implements OAuthServerProvider {
       .set({ lastUsedAt: now })
       .where(eq(oauthTokens.id, row.id))
       .then(undefined, (err) => log.warn('touch lastUsedAt failed:', { err }));
+    // The agent connection's own "last used" — what the Audit log shows for
+    // the agent, across every token it has held. Throttled, never awaited.
+    if (row.connectionId) this.noteConnectionUse(row.connectionId);
     return {
       token,
       clientId: row.clientId,
       scopes: (row.scope ?? '').split(' ').filter(Boolean),
       expiresAt: Math.floor(row.expiresAt.getTime() / 1000),
       resource: row.resource ? new URL(row.resource) : undefined,
-      extra: { userId: row.userId, userEmail: row.userEmail },
+      extra: {
+        userId: row.userId,
+        userEmail: row.userEmail,
+        // Null on a token minted before connections existed; the auth
+        // middleware then binds no agent and the call goes unrecorded.
+        connectionId: row.connectionId,
+      },
     };
   }
 
@@ -343,7 +384,7 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     // RFC 7009: revoking an unknown/foreign/already-revoked token is a no-op.
     // The token may be either half of a pair — one UPDATE matching either hash.
     const hash = hashToken(request.token);
-    await this.deps.db
+    const revoked = await this.deps.db
       .update(oauthTokens)
       .set({ revokedAt: new Date() })
       .where(
@@ -352,14 +393,39 @@ export class BevelOAuthProvider implements OAuthServerProvider {
           isNull(oauthTokens.revokedAt),
           or(eq(oauthTokens.accessTokenHash, hash), eq(oauthTokens.refreshTokenHash, hash)),
         ),
-      );
+      )
+      .returning({ connectionId: oauthTokens.connectionId });
+    // A client revoking its own token is signing out. When that leaves the
+    // agent connection with no live token at all, the connection is over
+    // too — disconnected by its owner, as the Audit log then says — rather
+    // than listed as live forever with nothing behind it. (The proxy's own
+    // reset of a broken sign-in goes through `revokeByAccessToken`, not
+    // here, and must NOT close the connection: that agent is being sent
+    // back to re-authorise into the same one.)
+    const connectionId = revoked.find((r) => r.connectionId)?.connectionId;
+    if (!connectionId) return;
+    const [{ live }] = await this.deps.db
+      .select({ live: count() })
+      .from(oauthTokens)
+      .where(and(eq(oauthTokens.connectionId, connectionId), isNull(oauthTokens.revokedAt)));
+    if (Number(live) > 0) return;
+    await this.deps.db
+      .update(agentConnections)
+      .set({ revokedAt: new Date(), revokedBy: 'owner' })
+      .where(and(eq(agentConnections.id, connectionId), isNull(agentConnections.revokedAt)));
   }
 
+  /**
+   * @param connectionId The agent connection the pair belongs to, when the
+   *   caller already holds one (a refresh: the consumed token's). Absent on a
+   *   first mint, which finds or makes the live connection for (user, client).
+   */
   private async mintTokens(
     userId: string,
     clientId: string,
     scope: string | null,
     resource: string | null,
+    connectionId?: string,
   ): Promise<OAuthTokens> {
     const accessToken = this.deps.tokenPrefix + randomBytes(TOKEN_BYTES).toString('base64url');
     const refreshToken = this.refreshPrefix + randomBytes(TOKEN_BYTES).toString('base64url');
@@ -382,11 +448,13 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     } catch (err) {
       log.warn('token-table prune failed (non-fatal):', { err });
     }
+    const boundTo = connectionId ?? (await this.ensureConnection(userId, clientId));
     await this.deps.db.insert(oauthTokens).values({
       accessTokenHash: hashToken(accessToken),
       refreshTokenHash: hashToken(refreshToken),
       clientId,
       userId,
+      connectionId: boundTo,
       scope,
       resource,
       expiresAt: new Date(now + ACCESS_TTL_MS),
@@ -400,6 +468,116 @@ export class BevelOAuthProvider implements OAuthServerProvider {
       ...(scope ? { scope } : {}),
     };
   }
+
+  /**
+   * The live `agent_connections` row for (user, client) — found, or made on
+   * the first mint for the pair. A refresh finds the row the sign-in made, so
+   * one connection spans every token the agent ever holds; a mint after a
+   * revoke finds nothing live and makes a fresh row, which is what keeps the
+   * revoked one's history intact.
+   *
+   * Two concurrent first mints (a client racing its own token exchange) both
+   * miss the select; the partial unique index lets exactly one insert land,
+   * 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.
+   */
+  /**
+   * Whether an agent connection still admits requests: it exists and nobody
+   * has revoked it. Asked on every refresh, and by the MCP auth middleware on
+   * every request through the local server's exchanged grant — the one path
+   * where a token verifies statelessly and would otherwise outlive the
+   * revoke. A read, not a write: the use is stamped separately, throttled.
+   */
+  async isConnectionLive(connectionId: string): Promise<boolean> {
+    const [row] = await this.deps.db
+      .select({ id: agentConnections.id })
+      .from(agentConnections)
+      .where(and(eq(agentConnections.id, connectionId), isNull(agentConnections.revokedAt)))
+      .limit(1);
+    return row !== undefined;
+  }
+
+  /**
+   * Record that an agent connection is in use — its `last_used_at` on the
+   * Audit log — at most once a minute per connection per process, and never
+   * on the caller's critical path. The stamp is what the page shows; the
+   * liveness decision above never depends on it.
+   */
+  noteConnectionUse(connectionId: string): void {
+    const now = Date.now();
+    const last = this.connectionTouchedAt.get(connectionId);
+    if (last !== undefined && now - last < CONNECTION_TOUCH_INTERVAL_MS) return;
+    this.connectionTouchedAt.set(connectionId, now);
+    this.deps.db
+      .update(agentConnections)
+      .set({ lastUsedAt: new Date(now) })
+      .where(eq(agentConnections.id, connectionId))
+      .then(undefined, (err) => log.warn('touch connection lastUsedAt failed:', { err }));
+  }
+
+  /**
+   * The live `agent_connections` row for (user, agent) — found, or made on
+   * the first mint for the pair. The AGENT is the registered client's name,
+   * folded (see the schema): a client that registers itself afresh on every
+   * re-authorisation, as Claude does, lands every registration on the one
+   * row rather than a row per client id. A refresh finds the row the sign-in
+   * made, so one connection spans every token the agent ever holds; a mint
+   * after a revoke finds nothing live and makes a fresh row, which is what
+   * keeps the revoked one's history intact.
+   *
+   * Two concurrent first mints (a client racing its own token exchange) both
+   * miss the select; the partial unique index lets exactly one insert land,
+   * 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.
+   */
+  private async ensureConnection(userId: string, clientId: string): Promise<string> {
+    const [client] = await this.deps.db
+      .select({ clientName: oauthClients.clientName })
+      .from(oauthClients)
+      .where(eq(oauthClients.clientId, clientId))
+      .limit(1);
+    const clientName = client?.clientName ?? null;
+    const agentKey = agentKeyFor(clientName, clientId);
+    const live = () =>
+      this.deps.db
+        .select({ id: agentConnections.id })
+        .from(agentConnections)
+        .where(
+          and(
+            eq(agentConnections.userId, userId),
+            eq(agentConnections.agentKey, agentKey),
+            isNull(agentConnections.revokedAt),
+          ),
+        )
+        .limit(1);
+    const [existing] = await live();
+    if (existing) return existing.id;
+    const [inserted] = await this.deps.db
+      .insert(agentConnections)
+      .values({ userId, clientId, clientName, agentKey })
+      .onConflictDoNothing({
+        target: [agentConnections.userId, agentConnections.agentKey],
+        where: sql`${agentConnections.revokedAt} is null`,
+      })
+      .returning({ id: agentConnections.id });
+    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;
+  }
+}
+
+/**
+ * What an agent connection is keyed by: the registered client name, folded
+ * (case and surrounding whitespace are not identity), or the client id for
+ * a registration that carried no name. The SAME fold the migration applied
+ * to the rows that existed before the key did.
+ */
+export function agentKeyFor(clientName: string | null, clientId: string): string {
+  const folded = (clientName ?? '').trim().toLowerCase();
+  return folded || clientId;
 }
 
 function hashToken(plaintext: string): string {

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

@@ -3,7 +3,8 @@ import { NodeFs } from '../../kb-fs/node-fs.js';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { DEFAULT_BRANCH, DEFAULT_KB_LAYOUT, configureKbLayout } from '@bevel-software/platform-shared';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import { AccessControlService } from '../../access/access-control.service.js';
@@ -46,7 +47,8 @@ describe('bundle dialect, end to end', () => {
   };
 
   beforeEach(async () => {
-    configureKbLayout({ knowledgeBaseDir: 'docs', skillsDir: 'skills', pluginsDir: 'plugins' });
+    // The customer's root names, read by every consumer through one context.
+    const kb = testKbContext({ kbDirName: KB_DIR, layout: { knowledgeBaseDir: 'docs', skillsDir: 'skills', pluginsDir: 'plugins' } });
     root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-dialect-'));
     repo = path.join(root, wsId, KB_DIR);
     const workspaceService = {
@@ -94,17 +96,16 @@ describe('bundle dialect, end to end', () => {
     );
 
     const disk = new NodeFs();
-    const source = new KbPluginSource(disk);
-    access = new AccessControlService(workspaceService, KB_DIR, disk);
-    skills = new SkillService(workspaceService, access, KB_DIR, disk);
-    tools = new ToolManualService(workspaceService, access, KB_DIR, disk, source);
-    links = new PluginLinkIndex(workspaceService, skills, access, KB_DIR, source);
-    index = new PluginIndexService(workspaceService, access, skills, tools, KB_DIR, source, Date.now, links);
-    compiler = new MarketplaceCompilerService(workspaceService, access, skills, links, KB_DIR, { name: 'acme', owner: 'Acme' }, source, disk, new NodeGitRunner());
-    linkService = new PluginLinksService(workspaceService, { runPendingCommit: async () => undefined }, access, skills, links, KB_DIR);
+    const source = new KbPluginSource(disk, kb);
+    access = new AccessControlService(workspaceService, KB_DIR, disk, [], new NodeGitRunner(), kb);
+    skills = new SkillService(workspaceService, access, kb, disk);
+    tools = new ToolManualService(workspaceService, access, kb, disk, source);
+    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);
   });
   afterEach(async () => {
-    configureKbLayout({ ...DEFAULT_KB_LAYOUT });
     await fs.rm(root, { recursive: true, force: true });
   });
 

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

@@ -1,4 +1,5 @@
 import { describe, it, expect } from 'vitest';
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
@@ -147,7 +148,7 @@ describe('bundle: what it says about itself survives', () => {
         }),
       );
       const warnings: string[] = [];
-      const plugin = await readBundlePlugin(dir, 'plugins/ado', 'ado', null, warnings, []);
+      const plugin = await readBundlePlugin(dir, 'plugins/ado', 'ado', null, warnings, [], DEFAULT_KB_LAYOUT);
       expect(plugin?.manifest).toEqual({
         name: 'ado',
         version: '1.3.5',

package/src/modules/plugins/__tests__/compile-marketplace.test.ts

@@ -16,6 +16,7 @@ import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
 import express from 'express';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { registerSkillsTools } from '../../skills/skills.tools.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * Source in, distribution out — for one caller. The real resolver decides
@@ -90,17 +91,18 @@ describe('compileMarketplace', () => {
     await write('Skills/Sales/pitch/SKILL.md', '---\ndescription: Pitch.\n---\n');
 
     const disk = new NodeFs();
-    const source = new KbPluginSource(disk);
+    const kb = testKbContext({ kbDirName: KB_DIR });
+    const source = new KbPluginSource(disk, kb);
     const access = new AccessControlService(workspaceService, KB_DIR, disk);
-    const skills = new SkillService(workspaceService, access, KB_DIR, disk);
+    const skills = new SkillService(workspaceService, access, kb, disk);
     catalog = skills;
-    const links = new PluginLinkIndex(workspaceService, skills, access, KB_DIR, source);
+    const links = new PluginLinkIndex(workspaceService, skills, access, kb, source);
     compiler = new MarketplaceCompilerService(
       workspaceService,
       access,
       skills,
       links,
-      KB_DIR,
+      kb,
       {
         name: 'acme-hexis',
         owner: 'Acme',

package/src/modules/plugins/__tests__/join-request-jobs.service.test.ts

@@ -8,6 +8,7 @@ import {
 } from '../join-request-jobs.service.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { FakeJoinRequestStore } from './fake-join-request-store.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * The git half of a join request, on its own: what it does to the row it was
@@ -40,7 +41,7 @@ function harness(over: Partial<JoinRequestJobsDeps> = {}, sharedStore?: FakeJoin
   const jobs = new PluginJoinRequestJobs(store, {
     workflow: workflow as never,
     workspaceService: workspaceService as never,
-    kbDirName: KB,
+    kb: testKbContext({ kbDirName: KB }),
     target: async () => ({ folder: 'Plugins/Finance', displayName: 'Finance' }),
     requester: async (mail) => ({ ...ALI_USER, email: mail }),
     ...over,