@bevel-software/platform-core-backend 0.25.2 → 0.27.0

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

@@ -8,6 +8,8 @@ import {
   ListToolsRequestSchema,
   ListPromptsRequestSchema,
   GetPromptRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
   McpError,
   ErrorCode,
   isInitializeRequest,
@@ -39,6 +41,9 @@ import {
   retiredToolMessage,
   needsAuthorizationResult,
   skillPromptText,
+  toListedResource,
+  toReadResourceResult,
+  type McpAppManifest,
   type ProxiedTool,
   type SkillSummary,
   type LoadedSkill,
@@ -53,6 +58,7 @@ import {
 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 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 { IAgentEventRecorder } from '../audit/audit.contract.js';
@@ -60,16 +66,17 @@ 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';
+import { ToolSchemaGuard, type ScreenedHiddenTool } from './tool-schema-guard.js';
 import { DownstreamRefreshGuard, isDownstreamTokenRejection } from './downstream-token-refresh.js';
 import { printable } from '../../shared/printable.js';
 import {
   composeAgentInstructions,
   prefixToolDescription,
   PREFIXED_TOOLS,
-  sharedRulesPointer,
   type AgentPreambleReader,
   type ComposedAgentInstructions,
 } from '../agent-instructions/index.js';
+import { guideFirstDescription } from '../tool-registry/guide-first.js';
 
 /**
  * Configuration for the loopback proxy. `loopbackBaseUrl` is the backend's own
@@ -95,8 +102,8 @@ export interface McpProxyOptions {
   readAgentPreamble?: AgentPreambleReader;
   /**
    * The layout in effect, read per request: the shared file rules name the
-   * managed guide, and a deployment may rename it after boot (the setup save
-   * applies a name without a restart). A GETTER, so nothing snapshots the
+   * guide by the name a deployment saved for it, and the setup save applies
+   * a layout without a restart. A GETTER, so nothing snapshots the
    * pre-setup default. Absent, the rules name `AGENTS.md`.
    */
   kbLayout?: () => KbLayout;
@@ -166,6 +173,14 @@ interface RequestSurface {
    * They differ only when the name holds a non-word character (`my-server`).
    */
   catalogNames: ReadonlyMap<string, string>;
+  /**
+   * The tools this request's load took OFF the surface for an invalid schema,
+   * by the name an agent would have called them by. Carried on the surface
+   * rather than read back out of the guard: it is this caller's own load, so a
+   * call answered from it cannot answer about a schema some other caller's
+   * connection was shown.
+   */
+  hidden: ReadonlyMap<string, ScreenedHiddenTool>;
 }
 
 /** A manual off the surface for want of a sign-in — see {@link RequestSurface.unavailable}. */
@@ -273,6 +288,15 @@ export class McpService {
    */
   private readonly knownDownstreamTools = new Map<string, { definition: string; tools: UtcpTool[] }>();
 
+  /**
+   * The JSON Schema check on connected tools, and the memory of what it found.
+   * Process-wide rather than per request, because a schema's validity is a
+   * property of the server and not of the caller — and because the point of
+   * remembering is that the check runs when a server's tools are loaded, not
+   * once per request and never on a tool call. See {@link ToolSchemaGuard}.
+   */
+  private readonly toolSchemas = new ToolSchemaGuard();
+
   // The downstream connection pool for `mcp` manuals — see the class doc.
   private readonly downstream: DownstreamPool<PooledDownstream>;
 
@@ -296,6 +320,18 @@ export class McpService {
     // 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,
+    /**
+     * The MCP Apps this deployment serves — the views a tool's `_meta` names
+     * and `resources/list` / `resources/read` answer for.
+     *
+     * Optional, and absence is a real state rather than a test convenience:
+     * with no manifest the endpoint declares no `resources` capability and
+     * every tool is listed exactly as before, which is also what a
+     * deployment whose packaged view could not be read must look like. A
+     * `resourceUri` advertised without a resource behind it would have a
+     * host preload a failure and show an empty frame.
+     */
+    private readonly mcpApps?: { manifest(): Promise<McpAppManifest> },
   ) {
     this.downstream = new DownstreamPool<PooledDownstream>({
       ...opts.downstreamPool,
@@ -402,10 +438,24 @@ export class McpService {
       }));
 
     const initializing = (Array.isArray(messages) ? messages : [messages]).some((m) => isInitializeRequest(m));
+    // 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
+    // resources and be told the method does not exist.
+    const apps = this.mcpApps ? await this.mcpApps.manifest().catch(() => null) : null;
+    const servesApps = (apps?.resources.length ?? 0) > 0;
     const server = new Server(
       { name: 'bevel-mcp', version: '0.1.0' },
       {
-        capabilities: { tools: {}, prompts: {} },
+        capabilities: {
+          tools: {},
+          prompts: {},
+          // Resources exist here for ONE purpose: serving the MCP App views
+          // the tools carry. The knowledge base's own files are not
+          // resources — they are what the file TOOLS read, under the access
+          // rules, which a resource listing has no way to express.
+          ...(servesApps ? { resources: {} } : {}),
+        },
         // `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 } : {}),
@@ -445,7 +495,12 @@ export class McpService {
       const direct: McpTool[] = [];
       const examplePool: ProxiedTool[] = [];
       for (const t of listed) {
-        const entry = toListedTool(t); // logs its own reason on a name/schema drop
+        // The MCP App view this tool's result renders in, by tool name. Not
+        // part of the UTCP manual the tool was discovered from (UTCP has no
+        // 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
         if (!entry) {
           dropped.push(t.mcpName);
           continue;
@@ -486,14 +541,17 @@ export class McpService {
       // different name, and one fixed example is necessarily wrong on one of the
       // two surfaces.
       //
-      // The chain's description ends with the same pointer every file tool ends
-      // with: what a chain does with a failure, a large result or an image is
-      // stated once, in the shared rules, and the clients that drop
-      // `instructions` have the description and the guide to go on. Composed
-      // here because the guide's name is this deployment's setting.
+      // What a chain does with a failure, a large result or an image is
+      // stated once, in the shared rules — in the guide and in the handshake
+      // instructions — and not on the chain itself (an EMPTY pointer is how
+      // `mcp-core` is told the rules are served elsewhere). Like every tool of
+      // the platform's own, each meta-tool opens with the one sentence saying
+      // what to do before any of them, which is where those rules are. The
+      // registry puts the sentence on the tools it lists; the meta-tools are
+      // built here, so here it is.
       const metaTools = codeModeMetaTools(EXTERNAL_KB_MANUAL_NAME, examplePool, {
-        sharedRulesPointer: sharedRulesPointer(this.opts.kbLayout?.()),
-      });
+        sharedRulesPointer: '',
+      }).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
       // it by rejecting the whole response.
@@ -509,8 +567,27 @@ export class McpService {
       };
     });
 
+    // The MCP App views. Registered only when this deployment serves one, so
+    // the handlers and the declared capability agree.
+    if (servesApps && apps) {
+      server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: apps.resources.map((r) => toListedResource(r)),
+      }));
+      server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const resource = apps.resources.find((r) => r.uri === request.params.uri);
+        if (!resource) {
+          throw new McpError(
+            ErrorCode.InvalidParams,
+            `No resource at ${request.params.uri}. This endpoint serves the MCP App views its tools ` +
+              `name and nothing else: ${apps.resources.map((r) => r.uri).join(', ')}.`,
+          );
+        }
+        return toReadResourceResult(resource);
+      });
+    }
+
     server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
-      const { client, tools, unavailable, catalogNames } = await requestSurface();
+      const { client, tools, unavailable, catalogNames, hidden: hiddenTools } = await requestSurface();
       const toolName = request.params.name;
       const args = request.params.arguments ?? {};
       if (META_TOOL_NAMES.has(toolName)) {
@@ -551,6 +628,24 @@ export class McpService {
       };
       const proxied = tools.find((t) => t.mcpName === toolName);
       if (!proxied) {
+        // A tool this process hid for an invalid schema: say that, rather than
+        // "Unknown tool" about a tool the agent has every reason to think
+        // exists. The place and the reason are deliberately NOT here — they are
+        // for the people who manage the server, who are the only ones who can
+        // act on them.
+        const hidden = hiddenTools.get(toolName);
+        if (hidden) {
+          // The UTCP name, as every other audit path records a tool: the
+          // flattened agent name loses the server segment of a multi-segment
+          // `<manual>.<server>.<tool>`, and an audit trail that names a
+          // different tool than the rest of the trail is worse than none.
+          if (audit) await audit.denied(hidden.utcpName, args);
+          return toolError(
+            `The "${toolName}" tool is hidden from agents because its schema is invalid, so it cannot be ` +
+              `called. The people who manage its server can see the place in the schema and the reason, on ` +
+              `the tool's page in Hexis and through \`list_tool_setup\`.`,
+          );
+        }
         // Not on the surface — but if the name belongs to a manual that is off
         // it only because this caller's sign-in is gone (and nothing in this
         // process has seen its tools yet), the honest answer is the sign-in
@@ -570,7 +665,10 @@ export class McpService {
         if (audit) await audit.denied(proxied.utcpName, args);
         return needsAuth;
       }
-      const run = () => this.dispatch(client, proxied, request, extra);
+      // A tool with an MCP App view answers structured content too — the
+      // view reads its fields from there.
+      const structured = apps !== null && Object.hasOwn(apps.tools, proxied.mcpName);
+      const run = () => this.dispatch(client, proxied, request, extra, structured);
       return audit ? audit.call(proxied.utcpName, args, run, isErrorResult) : run();
     });
 
@@ -626,7 +724,7 @@ export class McpService {
     const manuals = await this.fetchManualTemplates(loopbackBearer);
     const catalogMs = performance.now() - started;
     const client = await this.buildClient(loopbackBearer, userId, manuals);
-    const { tools, unavailable, catalogNames } = await this.discoverTools(client, manuals, userId);
+    const { tools, unavailable, catalogNames, hidden } = await this.discoverTools(client, manuals, userId);
     const totalMs = performance.now() - started;
     // Per user: on a shape change or once per interval, never per request —
     // see SurfaceLogThrottle for why both halves matter.
@@ -641,7 +739,7 @@ export class McpService {
           (decision.suppressed > 0 ? ` [+${decision.suppressed} identical rebuild(s) since last line]` : ''),
       );
     }
-    return { client, tools, unavailable, catalogNames };
+    return { client, tools, unavailable, catalogNames, hidden };
   }
 
   /**
@@ -798,13 +896,37 @@ export class McpService {
     client: CodeModeUtcpClient,
     manuals: CallTemplate[],
     userId: string,
-  ): Promise<{ tools: ProxiedTool[]; unavailable: UnavailableManual[]; catalogNames: Map<string, string> }> {
+  ): Promise<{
+    tools: ProxiedTool[];
+    unavailable: UnavailableManual[];
+    catalogNames: Map<string, string>;
+    hidden: Map<string, ScreenedHiddenTool>;
+  }> {
     const routes = new Map<string, DownstreamRoute>();
     const unavailable: UnavailableManual[] = [];
+    // Taken BEFORE a single manual is registered, so it ranks this load by the
+    // freshness of what it is about to read — see ToolSchemaGuard.beginLoad.
+    const loadId = this.toolSchemas.beginLoad();
     const catalogNames = new Map<string, string>();
     for (const m of manuals) {
       if (m.call_template_type === 'mcp') catalogNames.set(utcpManualName(m), String(m.name));
     }
+    // Every manual's catalog name, which is how the owner-facing surfaces know
+    // it. `catalogNames` above is the credential catalog's map and covers `mcp`
+    // manuals only; the schema check is about the tools of every connected
+    // server, so it needs the whole list. Taken HERE, before registration:
+    // registering a manual renames the template in place, so `m.name` read
+    // afterwards is the rewritten identifier and `my-server` would be recorded
+    // as `my_server` — a name no tool page ever looks up.
+    // Keyed by the rewritten name, which two manuals can share (the collision
+    // handled below): the KB manual's entry is the one that stays, since it is
+    // the one that is registered when a `.tool` collides with it.
+    const manualCatalogNames = new Map<string, string>();
+    for (const m of manuals) {
+      const rewritten = utcpManualName(m);
+      if (manualCatalogNames.get(rewritten) === EXTERNAL_KB_MANUAL_NAME) continue;
+      manualCatalogNames.set(rewritten, String(m.name));
+    }
     // The shared layer rewrites every manual name (`[^\w]` → `_`) and tools
     // route by the rewritten prefix, so two manuals whose names rewrite to one
     // identifier would silently share it. Sequential registration used to
@@ -884,11 +1006,65 @@ export class McpService {
     if (kbFailure && !kbFailure.ok) throw new Error(`Bevel tool discovery failed: ${kbFailure.error}`);
     if (routes.size > 0) routeToDownstream(client, routes);
     const utcpTools = await client.getTools();
-    return {
-      tools: utcpTools.map((tool: UtcpTool) => flattenManualTool(tool, EXTERNAL_KB_MANUAL_NAME)),
-      unavailable,
-      catalogNames,
-    };
+    const flattened = utcpTools.map((tool: UtcpTool) => flattenManualTool(tool, EXTERNAL_KB_MANUAL_NAME));
+    const { tools, hidden } = await this.hideInvalidSchemas(client, flattened, manualCatalogNames, userId, loadId);
+    return { tools, unavailable, catalogNames, hidden };
+  }
+
+  /**
+   * Check the input schema of every tool the servers just advertised, and take
+   * the invalid ones OFF the client's tool repository.
+   *
+   * The repository is the single place `tools/list`, `list_tools`/`tools_info`
+   * and the TypeScript interfaces `call_tool_chain` generates are all built
+   * from, so removing a tool here removes it from all three — which is what
+   * "not offered to agents" has to mean. Its siblings are untouched: the check
+   * is per tool, so one bad schema costs that tool and nothing else of the
+   * server.
+   *
+   * A client would otherwise drop such a tool itself, silently, and the agent
+   * would be left without it and without a reason. Hidden here, the reason
+   * reaches the people who manage the server (see {@link ToolSchemaGuard}).
+   */
+  private async hideInvalidSchemas(
+    client: CodeModeUtcpClient,
+    tools: ProxiedTool[],
+    catalogNames: ReadonlyMap<string, string>,
+    userId: string,
+    loadId: number,
+  ): Promise<{ tools: ProxiedTool[]; hidden: Map<string, ScreenedHiddenTool> }> {
+    const byManual = new Map<string, ProxiedTool[]>();
+    // EVERY manual of this surface is screened, including the ones that
+    // advertised nothing. A server that removed its last invalid tool, and one
+    // whose tools never loaded at all (a sign-in that has gone), both come
+    // through here with an empty group — and an empty group is what clears the
+    // marker. Screening only the groups that have tools would leave the tool
+    // page, `list_tool_setup` and the hidden-tool answer on a call all
+    // reporting a defect this process can no longer see.
+    for (const manual of catalogNames.values()) byManual.set(manual, []);
+    for (const tool of tools) {
+      const manual = catalogNames.get(tool.manualName) ?? tool.manualName;
+      byManual.set(manual, [...(byManual.get(manual) ?? []), tool]);
+    }
+    const found = this.toolSchemas.screen(userId, loadId, byManual);
+    const hidden = new Map<string, ScreenedHiddenTool>();
+    for (const tool of found.values()) hidden.set(tool.name, tool);
+    if (found.size === 0) return { tools, hidden };
+    for (const utcpName of found.keys()) {
+      await client.config.tool_repository.removeTool(utcpName);
+    }
+    // Logged every time rather than throttled: a hidden tool is the one thing
+    // about this surface that a person has to act on, and it is rare.
+    log.warn(
+      `hiding ${found.size} connected tool(s) whose input schema is not valid JSON Schema: ` +
+        `${[...found.values()].map((t) => `${t.name} (${t.path}: ${t.reason})`).join(', ')}`,
+    );
+    return { tools: tools.filter((tool) => !found.has(tool.utcpName)), hidden };
+  }
+
+  /** The schema findings the owner-facing surfaces report — see {@link ToolSchemaGuard}. */
+  get hiddenTools(): HiddenToolSource {
+    return this.toolSchemas;
   }
 
   /**
@@ -1244,17 +1420,23 @@ export class McpService {
     // payload without a `progressToken` is accepted — same approach the prior
     // handler used; the strict ServerNotification type requires the token.
     extra: { sendNotification: (n: any) => Promise<void> },
+    structured = false,
   ): Promise<CallToolResult> {
     const progressToken = request.params._meta?.progressToken;
-    return dispatchToolCall(client, tool, request.params.arguments ?? {}, (progress, message) =>
-      extra.sendNotification({
-        method: 'notifications/progress',
-        params: {
-          ...(progressToken !== undefined ? { progressToken } : {}),
-          progress,
-          message,
-        },
-      }),
+    return dispatchToolCall(
+      client,
+      tool,
+      request.params.arguments ?? {},
+      (progress, message) =>
+        extra.sendNotification({
+          method: 'notifications/progress',
+          params: {
+            ...(progressToken !== undefined ? { progressToken } : {}),
+            progress,
+            message,
+          },
+        }),
+      { structured },
     );
   }
 
@@ -1328,6 +1510,11 @@ function templateFingerprint(template: CallTemplate): string {
  * until the consumer finishes or abandons it (`for await` returns the
  * generator, which runs the `finally`).
  *
+ * No guard is re-installed over this wrapper, and none is needed: a routed call
+ * is made on the POOLED client, which had the guards installed on it when its
+ * own manual was registered (`registerManual`). Nothing in this module checks a
+ * call or shapes its failure — it forwards the call and returns the answer.
+ *
  * A call the downstream refuses for its token (401 / `invalid_token`) goes to
  * the route's `afterFailure`, which may refresh the token and ask for ONE retry
  * on a fresh connection. Retrying is safe for the same reason session recovery

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

@@ -20,6 +20,7 @@ import type {
   OAuthTokenRevocationRequest,
   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 { TokenCrypto } from '../../../shared/token-crypto.js';
@@ -57,6 +58,12 @@ export interface BevelOAuthProviderDeps {
   publicFrontendUrl: string;
   /** Access-token plaintext prefix, e.g. `bevel-mcp_`. */
   tokenPrefix: string;
+  /**
+   * Where the FIRST use of an agent connection is announced to its owner
+   * (`agent-connected`, see {@link BevelOAuthProvider.noteConnectionUse}).
+   * Optional: without it the stamp is written and nobody is told.
+   */
+  events?: { emit(event: AgentConnectedEvent): void };
 }
 
 /**
@@ -511,11 +518,42 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     const last = this.connectionTouchedAt.get(connectionId);
     if (last !== undefined && now - last < CONNECTION_TOUCH_INTERVAL_MS) return;
     this.connectionTouchedAt.set(connectionId, now);
-    this.deps.db
+    this.stampConnectionUse(connectionId, new Date(now)).catch((err) =>
+      log.warn('touch connection lastUsedAt failed:', { err }),
+    );
+  }
+
+  /**
+   * The stamp itself, and the one thing it tells: a connection stamped for
+   * the FIRST time is an agent that has just reached the platform — the
+   * `initialize` every client sends on connecting — which is what the
+   * onboarding waits for, so its owner is told (`agent-connected`) for
+   * exactly that stamp and never again.
+   *
+   * The first stamp is CLAIMED in one statement (`… where last_used_at is
+   * null … returning`): of two requests racing it — a parallel
+   * `initialize` and `tools/list`, or two replicas — the database hands the
+   * row to exactly one, and only that one announces. The loser, and every
+   * later use, stamps the ordinary way. Both sit behind the throttle above,
+   * so the hot path pays nothing for them.
+   */
+  private async stampConnectionUse(connectionId: string, at: Date): Promise<void> {
+    const [first] = await 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 }));
+      .set({ lastUsedAt: at })
+      .where(and(eq(agentConnections.id, connectionId), isNull(agentConnections.lastUsedAt)))
+      .returning({ userId: agentConnections.userId, client: agentConnections.clientName });
+    if (first) {
+      this.deps.events?.emit({
+        kind: 'agent-connected',
+        forUserId: first.userId,
+        client: first.client ?? 'Unnamed agent',
+        agentKind: 'agent',
+        at: at.toISOString(),
+      });
+      return;
+    }
+    await this.deps.db.update(agentConnections).set({ lastUsedAt: at }).where(eq(agentConnections.id, connectionId));
   }
 
   /**

package/src/modules/mcp/tool-schema-guard.ts

@@ -0,0 +1,196 @@
+/**
+ * The schema check for connected tools, and the memory of what it found.
+ *
+ * An AI client that is handed a tool whose input schema is not valid JSON
+ * Schema drops that tool and says nothing: it is simply missing for the agent,
+ * with nothing in Hexis to look at. So Hexis runs the same check itself, when a
+ * server's tools are LOADED, and:
+ *
+ *  - keeps such a tool off every agent surface, so the agent's picture of what
+ *    it can do matches what it can actually call;
+ *  - remembers the finding for the people who manage that server, who are the
+ *    only ones who can get it fixed (the tool page, `list_tool_setup`).
+ *
+ * WHEN it runs is the point. The verdict is remembered per DISTINCT SCHEMA, so
+ * a server whose tools are unchanged costs one hash and one map lookup per
+ * tool: the JSON Schema check happens when a server's tools are first loaded
+ * and when a refresh brings a schema this process has not seen, and never on a
+ * tool call — which re-derives the surface from those same unchanged schemas.
+ *
+ * It never REPAIRS anything. The proxy passes a connected server's schema
+ * through as sent; an invalid one is reported, and the server's owner decides.
+ */
+
+import { createHash } from 'node:crypto';
+import { inputSchemaDefect, schemaDefectMarker, type SchemaDefect } from '@bevel-software/platform-mcp-core';
+import type { HiddenTool, HiddenToolSource } from '../../shared/hidden-tools.js';
+
+/** What {@link ToolSchemaGuard.screen} needs of a freshly loaded tool. */
+export interface ScreenedTool {
+  /** The UTCP name (`<manual>.<server>.<tool>`) — how the tool repository knows it. */
+  utcpName: string;
+  /** The flattened name an agent addresses it by. */
+  mcpName: string;
+  /** The input schema exactly as the connected server sent it. */
+  inputSchema: unknown;
+}
+
+/**
+ * A finding as the LOADING side needs it. The owner-facing `HiddenTool` is
+ * about a tool by the name an agent would have called it; the proxy also has to
+ * take the tool out of its repository and record it in the audit trail, and
+ * both of those know a tool by its UTCP name. Kept off `HiddenTool` so the
+ * owner-facing payload stays exactly what its surfaces declare.
+ */
+export interface ScreenedHiddenTool extends HiddenTool {
+  /** The UTCP name (`<manual>.<server>.<tool>`) the tool repository knows it by. */
+  utcpName: string;
+}
+
+/**
+ * How many schema verdicts to remember. Each is a hash and a verdict, so the
+ * cap is about a deployment that edits servers all day rather than about size;
+ * past it the whole table is cleared instead of evicted entry by entry, since
+ * the next load simply re-checks.
+ */
+const MAX_REMEMBERED_SCHEMAS = 5000;
+
+/** How many callers' pictures to hold at once — see `screen` for what happens past it. Exported for the tests that fill it. */
+export const MAX_REMEMBERED_CALLERS = 2000;
+
+export class ToolSchemaGuard implements HiddenToolSource {
+  /** Verdict per distinct schema: `null` means valid, so `undefined` means unchecked. */
+  private readonly verdicts = new Map<string, SchemaDefect | null>();
+  /**
+   * The findings, per CALLER and then per manual by catalog name.
+   *
+   * Keyed by caller because that is what a load is: discovery runs on the
+   * requesting user's own connection to the server, and two callers can be
+   * shown different tools by the same server. A single table keyed by manual
+   * would let one caller's load erase another's finding — the owner page would
+   * then show a defect from whichever request happened to be last, or none at
+   * all. Keyed by caller, a load replaces only what that caller can see, and
+   * `hiddenFor` reports the union, since the finding is about the server.
+   */
+  private readonly hidden = new Map<string, Map<string, ScreenedHiddenTool[]>>();
+  /** The newest load whose picture has been applied, per caller — see {@link beginLoad}. */
+  private readonly applied = new Map<string, number>();
+  /** Hands out {@link beginLoad} tickets; monotonic for the life of the process. */
+  private loads = 0;
+
+  /** `check` is injected only by tests, to observe how often the check runs. */
+  constructor(private readonly check: (schema: unknown) => SchemaDefect | null = inputSchemaDefect) {}
+
+  /**
+   * A ticket for a load that is ABOUT TO READ a server's tools, to be handed
+   * back to {@link screen} with what it found.
+   *
+   * Requests overlap: a caller's surface is rebuilt on every one of them, and
+   * two can be dialling the same server at once. Without an order, a load that
+   * started while a schema was still broken could land after the load that saw
+   * it corrected, and put the marker back on a tool that is fine — until some
+   * later request happened to clear it again. The ticket is taken BEFORE the
+   * read, so it ranks loads by the freshness of what they saw, and `screen`
+   * ignores a picture older than the one already applied.
+   */
+  beginLoad(): number {
+    this.loads += 1;
+    return this.loads;
+  }
+
+  /**
+   * Screen everything one caller's request just loaded — every manual on their
+   * surface, with the tools that manual advertised — and replace that caller's
+   * whole picture. Returns the tools to keep off the agent surfaces, keyed by
+   * UTCP name.
+   *
+   * WHOLE is the point, and why this takes every manual rather than one. A
+   * manual whose group is EMPTY has nothing hidden: its server dropped the
+   * offending tool, or it failed to attach at all and its tools are not loaded.
+   * A manual absent from `groups` is no longer on this caller's surface. Either
+   * way the marker goes, with nothing to clear by hand — and nothing claims a
+   * tool is hidden for a schema this process can no longer see.
+   *
+   * `loadId` comes from {@link beginLoad}, taken before the tools were read. A
+   * load that is already out of date still gets its own answer — the request
+   * that ran it must not offer a tool it has just judged invalid — but it does
+   * not write that answer into what everyone else reads.
+   */
+  screen(
+    userId: string,
+    loadId: number,
+    groups: ReadonlyMap<string, readonly ScreenedTool[]>,
+  ): Map<string, ScreenedHiddenTool> {
+    const found = new Map<string, ScreenedHiddenTool>();
+    const picture = new Map<string, ScreenedHiddenTool[]>();
+    for (const [manual, tools] of groups) {
+      const ofManual: ScreenedHiddenTool[] = [];
+      for (const tool of tools) {
+        const defect = this.verdict(tool.inputSchema);
+        if (!defect) continue;
+        const hidden: ScreenedHiddenTool = {
+          manual,
+          name: tool.mcpName,
+          utcpName: tool.utcpName,
+          path: defect.path,
+          reason: defect.reason,
+          marker: schemaDefectMarker(defect),
+        };
+        found.set(tool.utcpName, hidden);
+        ofManual.push(hidden);
+      }
+      if (ofManual.length > 0) picture.set(manual, ofManual);
+    }
+    // Stale: a load that read the server earlier than one already applied for
+    // THIS caller. Its own answer stands, the shared picture does not move.
+    //
+    // Per caller, and nothing wider. An evicted caller's watermark goes with
+    // their picture, and that loses nothing: once nothing of theirs is held,
+    // whichever of their loads lands next is the newest picture this process
+    // has of them, and it restores the watermark that rejects any older one
+    // landing after it. A floor shared across callers would instead reject
+    // some OTHER caller's newest load for having begun before an unrelated
+    // eviction, and the owner's page would miss that caller's finding.
+    if (loadId < (this.applied.get(userId) ?? 0)) return found;
+    // Not about size — each entry is a handful of strings — but about a
+    // deployment with many callers never growing these without bound. Evicted
+    // one caller at a time, the longest unseen first, so every other caller's
+    // findings stay on the owner's page; the next load of the evicted surface
+    // puts its own back. (Re-inserted on every load, so a Map's insertion
+    // order is the order of last sight.)
+    while (this.applied.size >= MAX_REMEMBERED_CALLERS && !this.applied.has(userId)) {
+      const oldest = this.applied.keys().next().value as string;
+      this.applied.delete(oldest);
+      this.hidden.delete(oldest);
+    }
+    this.applied.delete(userId);
+    this.applied.set(userId, loadId);
+    if (picture.size > 0) this.hidden.set(userId, picture);
+    else this.hidden.delete(userId);
+    return found;
+  }
+
+  hiddenFor(manual: string): HiddenTool[] {
+    const union = new Map<string, HiddenTool>();
+    for (const picture of this.hidden.values()) {
+      for (const { manual: of, name, path, reason, marker } of picture.get(manual) ?? []) {
+        // One entry per distinct defect: two callers shown the same broken tool
+        // have found one thing, and its owner should read it once. Projected to
+        // the owner-facing shape, so nothing of the loading side rides along.
+        union.set(`${name}\u0000${path}\u0000${reason}`, { manual: of, name, path, reason, marker });
+      }
+    }
+    return [...union.values()];
+  }
+
+  /** The check itself, once per distinct schema. */
+  private verdict(schema: unknown): SchemaDefect | null {
+    const key = createHash('sha1').update(JSON.stringify(schema) ?? 'undefined').digest('hex');
+    const remembered = this.verdicts.get(key);
+    if (remembered !== undefined) return remembered;
+    const defect = this.check(schema);
+    if (this.verdicts.size >= MAX_REMEMBERED_SCHEMAS) this.verdicts.clear();
+    this.verdicts.set(key, defect);
+    return defect;
+  }
+}