@1mcp/agent 0.39.0-beta.3 → 0.39.0-beta.4

package/build/core/capabilities/capabilityCatalog.js

@@ -1,13 +1,20 @@
+import { createHash, randomUUID } from 'node:crypto';
 import { requestLegacyAdapter } from '../client/legacyAdapterRequest.js';
 import { ConnectionResolver } from '../server/connectionResolver.js';
 import { getDisabledSourceToolError, isSourceToolDisabled } from '../server/disabledTools.js';
+import { parseTemplateConnectionKey } from '../server/templateIdentity.js';
 import { applySourceToolDescription } from '../server/toolDescriptionOverrides.js';
 import { ClientStatus, } from '../types/index.js';
 import { SchemaBoundaryError } from '../validation/schemaBoundary.js';
 import { admitToolSchemas, prepareToolValidation, projectToolSchemas, schemaInputErrorResult, } from '../validation/toolSchemaBoundary.js';
 import { gatewayFailureFromUnknown } from '../../gateway/contracts/gatewayFailure.js';
+import { writeLocalDiagnostic } from '../../logger/localDiagnostics.js';
 import logger from '../../logger/logger.js';
-import { walkCapabilityPages, } from './capabilityPagination.js';
+import { ownData } from '../../observability/privacy/fields.js';
+import { ErrorCode } from '../../sdk/contracts/index.js';
+import { MCPError } from '../../utils/core/errorTypes.js';
+import { buildPublicToolName } from '../../utils/core/toolNames.js';
+import { CAPABILITY_PAGINATION_META_KEY, getCapabilityFailureFacts, getCapabilityPaginationGeneration, setCapabilityFailureFacts, walkCapabilityPages, } from './capabilityPagination.js';
 import { getCapabilityVisibleServerNames } from './capabilityVisibility.js';
 import { ToolRegistry } from './toolRegistry.js';
 const NEVER_REFRESH = {
@@ -16,12 +23,58 @@ const NEVER_REFRESH = {
     changed: false,
     shouldNotifyListChanged: false,
 };
+const catalogCursorOwners = new WeakMap();
+const contextCatalogCursorOwners = new WeakMap();
+const visibilityCatalogCursorOwners = new WeakMap();
+/** Listener-owned authority; never reconstructed from transport fields or serialized data. */
+export function createCatalogCursorOwner() {
+    const owner = Object.freeze({});
+    catalogCursorOwners.set(owner, Date.now() + TOOL_LISTING_TTL_MS);
+    return owner;
+}
+export function revokeCatalogCursorOwner(owner) {
+    catalogCursorOwners.delete(owner);
+}
+export function isCatalogCursorOwnerCurrent(owner) {
+    const expiresAt = catalogCursorOwners.get(owner);
+    return expiresAt !== undefined && expiresAt > Date.now();
+}
+export function bindCatalogCursorOwner(context, owner) {
+    if (!isCatalogCursorOwnerCurrent(owner))
+        throw new MCPError('Capability cursor owner is unavailable', ErrorCode.InvalidParams);
+    contextCatalogCursorOwners.set(context, owner);
+}
+export function attachCatalogCursorOwner(visibility, context) {
+    const owner = context && contextCatalogCursorOwners.get(context);
+    // Preserve revoked identity: a request cannot silently fall back to session authority.
+    if (owner)
+        visibilityCatalogCursorOwners.set(visibility, owner);
+}
+const TOOL_LISTING_TTL_MS = 15 * 60 * 1000;
+const MAX_TOOL_LISTING_SNAPSHOTS = 1000;
+const MAX_TOOL_LISTING_BYTES = 32 * 1024 * 1024;
+const MAX_VISIBILITY_TOOL_LISTINGS = 250;
+const MAX_VISIBILITY_TOOL_LISTING_BYTES = 8 * 1024 * 1024;
+const MAX_ACTIVE_TOOL_ADMISSIONS = 1000;
+const MAX_TOOL_ADMISSION_OUTCOMES = 32768;
+const toolListingStates = new WeakMap();
 export class CapabilityCatalog {
     deps;
     connectionResolver;
+    toolListings;
+    withheldTools;
+    listingState;
     constructor(deps) {
         this.deps = deps;
         this.connectionResolver = new ConnectionResolver(deps.outboundConnections, deps.templateHashProvider);
+        let state = toolListingStates.get(deps.outboundConnections);
+        if (!state) {
+            state = { listings: new Map(), withheldTools: new Map(), activeAttempts: new Set(), nextAttempt: 0 };
+            toolListingStates.set(deps.outboundConnections, state);
+        }
+        this.toolListings = state.listings;
+        this.withheldTools = state.withheldTools;
+        this.listingState = state;
     }
     /**
      * List one aggregate page while keeping provider traversal, cursor binding, and
@@ -85,49 +138,290 @@ export class CapabilityCatalog {
         });
     }
     async listVisibleTools(options = {}, visibility, queryOptions = {}) {
-        const refresh = await this.resolveRefreshFacts(queryOptions.refreshIntent ?? 'never', 'list');
-        const registry = await this.visibleToolRegistry(visibility, queryOptions.toolRegistry);
-        const admitted = [];
-        for (const tool of registry.getAllTools()) {
-            try {
+        const continuation = this.decodeToolListingCursor(options.cursor);
+        const effectiveVisibility = visibility ?? this.deps.defaultVisibility;
+        const owner = effectiveVisibility && visibilityCatalogCursorOwners.get(effectiveVisibility);
+        const assertOwnerCurrent = () => {
+            if (owner && !isCatalogCursorOwnerCurrent(owner)) {
+                throw new MCPError('Capability cursor owner is unavailable', ErrorCode.InvalidParams);
+            }
+        };
+        assertOwnerCurrent();
+        const visibilityKey = this.toolListingVisibility(visibility);
+        if (continuation) {
+            const snapshot = this.toolListings.get(continuation.walk);
+            if (!snapshot ||
+                snapshot.expiresAt <= Date.now() ||
+                snapshot.owner !== owner ||
+                snapshot.visibility !== visibilityKey ||
+                snapshot.generation !== getCapabilityPaginationGeneration(this.deps.outboundConnections, 'tools') ||
+                !snapshot.registry.isCurrent()) {
+                throw new MCPError('Invalid capability pagination cursor', ErrorCode.InvalidParams);
+            }
+            return this.toolListingPage(continuation.walk, snapshot, { ...options, cursor: continuation.cursor }, visibility);
+        }
+        await this.pruneToolAdmissionOutcomes(queryOptions.toolRegistry);
+        if (this.listingState.activeAttempts.size >= MAX_ACTIVE_TOOL_ADMISSIONS) {
+            throw new MCPError('Capability admission capacity exceeded', -32000);
+        }
+        const attempt = ++this.listingState.nextAttempt;
+        this.listingState.activeAttempts.add(attempt);
+        try {
+            const refresh = await this.resolveRefreshFacts(queryOptions.refreshIntent ?? 'never', 'list');
+            const sourceRegistry = queryOptions.toolRegistry ?? (await this.deps.getToolRegistry());
+            const registry = await this.visibleToolRegistry(visibility, sourceRegistry);
+            const admitted = [];
+            const timedOutSources = [];
+            const serverNames = Array.from(new Set(registry.getAllTools().map((tool) => tool.server))).sort();
+            const configSignature = this.toolListingConfigSignature(serverNames);
+            const currentConnections = new Map(registry.getAllTools().flatMap((tool) => {
+                const key = tool.connectionKey ?? tool.server;
+                const connection = this.deps.outboundConnections.get(key);
+                return connection ? [[key, connection]] : [];
+            }));
+            const currentAdapters = new Map(Array.from(currentConnections, ([key, connection]) => [key, connection.adapter]));
+            const isListingCurrent = () => registry.isCurrent() &&
+                this.toolListingConfigSignature(serverNames) === configSignature &&
+                Array.from(currentConnections).every(([key, connection]) => this.deps.outboundConnections.get(key) === connection &&
+                    connection.adapter === currentAdapters.get(key) &&
+                    connection.status === ClientStatus.Connected);
+            for (const tool of registry.getAllTools()) {
                 const key = tool.connectionKey ?? tool.server;
-                const definition = tool.definition ??
-                    this.deps.schemaCache.getIfCached(key, tool.name) ??
-                    (this.deps.loadSchema ? await this.deps.loadSchema(key, tool.name, queryOptions.signal) : undefined);
-                if (!definition)
-                    continue;
-                const contracts = await admitToolSchemas(definition, {
-                    routeKey: JSON.stringify([key, tool.name]),
-                    generation: this.deps.outboundConnections.get(key)?.adapter.connectionId ?? 'internal',
-                    sourceRevision: this.deps.outboundConnections.get(key)?.adapter.protocolRevision,
-                    signal: queryOptions.signal,
-                });
-                admitted.push({
-                    tool: projectToolSchemas(definition, contracts),
-                    server: tool.server,
-                    connectionKey: key,
-                    tags: tool.tags,
-                });
+                try {
+                    const definition = tool.definition ??
+                        this.deps.schemaCache.getIfCached(key, tool.name) ??
+                        (this.deps.loadSchema ? await this.deps.loadSchema(key, tool.name, queryOptions.signal) : undefined);
+                    if (!definition)
+                        continue;
+                    const contracts = await admitToolSchemas(definition, {
+                        routeKey: JSON.stringify([key, tool.name]),
+                        generation: this.deps.outboundConnections.get(key)?.adapter.connectionId ?? 'internal',
+                        sourceRevision: this.deps.outboundConnections.get(key)?.adapter.protocolRevision,
+                        signal: queryOptions.signal,
+                    });
+                    this.recordToolAdmission(JSON.stringify([key, tool.name]), attempt, false, sourceRegistry, currentConnections.get(key), currentAdapters.get(key));
+                    admitted.push({
+                        tool: projectToolSchemas(definition, contracts),
+                        server: tool.server,
+                        connectionKey: key,
+                        tags: tool.tags,
+                    });
+                }
+                catch (error) {
+                    if (!(error instanceof SchemaBoundaryError))
+                        throw error;
+                    if (tool.route?.origin === 'internal')
+                        throw error;
+                    if (!this.deps.outboundConnections.has(key))
+                        throw error;
+                    if (error.phase !== 'admission')
+                        throw error;
+                    if (error.code === 'schema_evaluation_unavailable')
+                        throw error;
+                    if (error.code === 'schema_evaluation_timeout') {
+                        timedOutSources.push(key);
+                        this.recordToolAdmission(JSON.stringify([key, tool.name]), attempt, true, sourceRegistry, currentConnections.get(key), currentAdapters.get(key));
+                        continue;
+                    }
+                    if (error.retryable)
+                        throw error;
+                }
             }
-            catch (error) {
-                if (!(error instanceof SchemaBoundaryError) || error.retryable)
-                    throw error;
+            assertOwnerCurrent();
+            if (!isListingCurrent()) {
+                throw new MCPError('Capability catalog changed during listing', -32000, { retryable: true });
             }
+            const generation = getCapabilityPaginationGeneration(this.deps.outboundConnections, 'tools');
+            const meta = this.toolAdmissionMeta(registry.getListingMeta(), timedOutSources, generation);
+            const snapshot = {
+                owner,
+                registry: ToolRegistry.fromToolsWithServer(admitted, meta).withConnections(registry.getConnections(), () => registry.isCurrent() &&
+                    this.toolListingConfigSignature(serverNames) === configSignature &&
+                    Array.from(currentConnections).every(([key, connection]) => this.deps.outboundConnections.get(key) === connection &&
+                        connection.adapter === currentAdapters.get(key) &&
+                        connection.status === ClientStatus.Connected)),
+                generation,
+                visibility: visibilityKey,
+                refresh,
+                expiresAt: Date.now() + TOOL_LISTING_TTL_MS,
+                bytes: 0,
+            };
+            const walk = randomUUID();
+            for (const [id, saved] of this.toolListings) {
+                if (saved.expiresAt <= Date.now() || (saved.owner && !isCatalogCursorOwnerCurrent(saved.owner)))
+                    this.toolListings.delete(id);
+            }
+            const result = this.toolListingPage(walk, snapshot, { ...options, cursor: undefined }, visibility);
+            if (result.nextCursor) {
+                snapshot.bytes = Buffer.byteLength(JSON.stringify(snapshot.registry.getAllTools()));
+                const visibilityListings = Array.from(this.toolListings.values()).filter((saved) => saved.owner === owner && saved.visibility === visibilityKey);
+                const visibilityBytes = visibilityListings.reduce((total, saved) => total + saved.bytes, 0);
+                if (visibilityListings.length >= MAX_VISIBILITY_TOOL_LISTINGS) {
+                    throw new MCPError('Capability cursor capacity exceeded', -32000);
+                }
+                if (visibilityBytes + snapshot.bytes > MAX_VISIBILITY_TOOL_LISTING_BYTES) {
+                    throw new MCPError('Capability cursor capacity exceeded', -32000);
+                }
+                const capturedBytes = Array.from(this.toolListings.values()).reduce((total, saved) => total + saved.bytes, 0);
+                if (capturedBytes + snapshot.bytes > MAX_TOOL_LISTING_BYTES) {
+                    throw new MCPError('Capability cursor capacity exceeded', -32000);
+                }
+                if (this.toolListings.size >= MAX_TOOL_LISTING_SNAPSHOTS) {
+                    throw new MCPError('Capability cursor capacity exceeded', -32000);
+                }
+                assertOwnerCurrent();
+                this.toolListings.set(walk, snapshot);
+                // Only publication of a new bounded walk grants its full issuance lifetime.
+                // Continuations retain their snapshot deadline and cannot renew authority.
+                if (owner)
+                    catalogCursorOwners.set(owner, Math.max(catalogCursorOwners.get(owner), snapshot.expiresAt));
+            }
+            return result;
+        }
+        finally {
+            this.listingState.activeAttempts.delete(attempt);
+            await this.pruneToolAdmissionOutcomes(queryOptions.toolRegistry);
+            assertOwnerCurrent();
+        }
+    }
+    async pruneToolAdmissionOutcomes(requestRegistry) {
+        const currentRegistry = requestRegistry ?? (await this.deps.getToolRegistry());
+        const oldestAttempt = Math.min(...this.listingState.activeAttempts);
+        for (const [key, outcome] of this.withheldTools) {
+            if (!outcome.withheld) {
+                if (outcome.attempt <= oldestAttempt)
+                    this.withheldTools.delete(key);
+                continue;
+            }
+            const [connectionKey] = JSON.parse(key);
+            const connection = this.deps.outboundConnections.get(connectionKey);
+            const obsolete = outcome.registry !== currentRegistry ||
+                outcome.connection !== connection ||
+                outcome.adapter !== connection?.adapter;
+            if (!obsolete)
+                continue;
+            if (outcome.attempt > oldestAttempt) {
+                this.withheldTools.set(key, { attempt: outcome.attempt, withheld: false });
+            }
+            else {
+                this.withheldTools.delete(key);
+            }
+        }
+    }
+    recordToolAdmission(key, attempt, withheld, registry, connection, adapter) {
+        const previous = this.withheldTools.get(key);
+        if (previous && previous.attempt > attempt)
+            return;
+        const [connectionKey] = JSON.parse(key);
+        const currentConnection = this.deps.outboundConnections.get(connectionKey);
+        if (connection !== currentConnection || adapter !== currentConnection?.adapter)
+            return;
+        if (!withheld && !Array.from(this.listingState.activeAttempts).some((active) => active < attempt)) {
+            this.withheldTools.delete(key);
+            return;
+        }
+        if (!this.withheldTools.has(key) && this.withheldTools.size >= MAX_TOOL_ADMISSION_OUTCOMES) {
+            throw new MCPError('Capability admission capacity exceeded', -32000);
         }
-        const result = ToolRegistry.fromToolsWithServer(admitted).listTools(options);
+        if (!withheld) {
+            this.withheldTools.set(key, { attempt, withheld: false });
+            return;
+        }
+        this.withheldTools.set(key, { attempt, withheld: true, registry, connection, adapter });
+    }
+    toolListingConfigSignature(serverNames) {
+        const configs = this.deps.getServerConfigs();
+        return createHash('sha256')
+            .update(JSON.stringify(serverNames.map((name) => [name, configs[name]])))
+            .digest('hex');
+    }
+    toolListingPage(walk, snapshot, options, visibility) {
+        const result = snapshot.registry.listTools(options);
         const tools = result.tools;
-        const servers = Array.from(new Set(tools.map((tool) => tool.server))).sort();
-        const routes = tools
-            .map((tool) => this.resolveRoute(tool, visibility))
-            .filter((route) => route !== undefined);
         return {
             ...result,
+            ...(result.nextCursor
+                ? { nextCursor: Buffer.from(JSON.stringify({ walk, cursor: result.nextCursor })).toString('base64url') }
+                : {}),
             tools,
-            servers,
-            routes,
-            refresh,
+            servers: Array.from(new Set(tools.map((tool) => tool.server))).sort(),
+            routes: tools
+                .map((tool) => this.resolveRoute(tool, visibility))
+                .filter((route) => route !== undefined),
+            refresh: snapshot.refresh,
         };
     }
+    decodeToolListingCursor(cursor) {
+        if (!cursor)
+            return undefined;
+        if (cursor.length > 4096)
+            throw new MCPError('Invalid capability pagination cursor', ErrorCode.InvalidParams);
+        try {
+            const decoded = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+            if (!decoded || typeof decoded !== 'object' || !('walk' in decoded)) {
+                throw new MCPError('Invalid capability pagination cursor', ErrorCode.InvalidParams);
+            }
+            if (typeof decoded.walk !== 'string' || !('cursor' in decoded) || typeof decoded.cursor !== 'string') {
+                throw new MCPError('Invalid capability pagination cursor', ErrorCode.InvalidParams);
+            }
+            return { walk: decoded.walk, cursor: decoded.cursor };
+        }
+        catch (error) {
+            if (error instanceof MCPError)
+                throw error;
+            throw new MCPError('Invalid capability pagination cursor', ErrorCode.InvalidParams);
+        }
+    }
+    toolListingVisibility(visibility) {
+        const effective = visibility ?? this.deps.defaultVisibility;
+        const owner = effective && visibilityCatalogCursorOwners.get(effective);
+        const staticCandidates = effective &&
+            Array.from(effective.serverCandidates.keys()).every((key) => parseTemplateConnectionKey(key).kind === 'static');
+        return JSON.stringify({
+            sessionId: owner && staticCandidates ? undefined : effective?.sessionId,
+            candidates: effective ? Array.from(effective.serverCandidates).sort(([a], [b]) => a.localeCompare(b)) : null,
+            filters: effective?.filterSelection,
+        });
+    }
+    async requiresToolListingRecovery(visibility) {
+        return (await this.visibleToolRegistry(visibility)).getListingMeta() !== undefined;
+    }
+    toolAdmissionMeta(inherited, timedOutSources, generation) {
+        if (timedOutSources.length === 0)
+            return inherited;
+        const facts = new Map(getCapabilityFailureFacts(inherited));
+        for (const source of timedOutSources) {
+            const previous = facts.get(source);
+            facts.set(source, {
+                ...previous,
+                upstream_tool_admission_timeout: (previous?.upstream_tool_admission_timeout ?? 0) + 1,
+            });
+        }
+        const failureCategories = { upstream_list_failed: 0, upstream_tool_admission_timeout: 0 };
+        for (const fact of facts.values()) {
+            failureCategories.upstream_list_failed += fact.upstream_list_failed ?? 0;
+            failureCategories.upstream_tool_admission_timeout += fact.upstream_tool_admission_timeout ?? 0;
+        }
+        const previous = inherited?.[CAPABILITY_PAGINATION_META_KEY];
+        return setCapabilityFailureFacts({
+            ...inherited,
+            [CAPABILITY_PAGINATION_META_KEY]: {
+                ...previous,
+                partial: true,
+                complete: false,
+                generation,
+                failedSourceCount: facts.size,
+                failureCategories: {
+                    ...(failureCategories.upstream_list_failed
+                        ? { upstream_list_failed: failureCategories.upstream_list_failed }
+                        : {}),
+                    upstream_tool_admission_timeout: failureCategories.upstream_tool_admission_timeout,
+                },
+                retryable: true,
+                recovery: 'restart-walk',
+            },
+        }, facts);
+    }
     async describeVisibleTool(args, visibility, queryOptions = {}) {
         const refresh = await this.resolveRefreshFacts(queryOptions.refreshIntent ?? 'never', 'describe');
         const access = await this.resolveVisibleToolAccess(args, visibility, queryOptions.toolRegistry);
@@ -208,9 +502,20 @@ export class CapabilityCatalog {
         }
     }
     async invokeVisibleTool(args, visibility, queryOptions = {}) {
+        const startedAt = performance.now();
+        const requested = { callId: randomUUID(), requestedServer: args.server, requestedTool: args.toolName };
+        writeLocalDiagnostic('info', 'tool.requested', requested);
+        writeLocalDiagnostic('debug', 'tool.arguments', () => ({ ...requested, arguments: args.args }));
         const refresh = await this.resolveRefreshFacts(queryOptions.refreshIntent ?? 'never', 'invoke');
         const access = await this.resolveVisibleToolAccess(args, visibility, queryOptions.toolRegistry);
         if (access.error) {
+            writeLocalDiagnostic('warn', 'tool.rejected', {
+                ...requested,
+                phase: 'routing',
+                outcome: queryOptions.signal?.aborted ? 'cancelled' : access.error.type,
+                error: access.error,
+                durationMs: performance.now() - startedAt,
+            });
             return {
                 result: {},
                 server: args.server ?? '',
@@ -221,9 +526,24 @@ export class CapabilityCatalog {
         }
         const { route } = access;
         const connection = access.connection ?? this.deps.outboundConnections.get(route.connectionKey);
+        const diagnosticRoute = {
+            ...requested,
+            server: route.server,
+            tool: route.toolName,
+            origin: route.origin,
+            routingScope: (visibility?.sessionId ?? this.deps.defaultVisibility?.sessionId) ? 'session' : 'default',
+            timeoutMs: connection?.requestTimeoutMs,
+        };
+        writeLocalDiagnostic('info', 'tool.routed', diagnosticRoute);
         if (!connection ||
             connection.status !== ClientStatus.Connected ||
             this.deps.outboundConnections.get(route.connectionKey) !== connection) {
+            writeLocalDiagnostic('warn', 'tool.rejected', {
+                ...diagnosticRoute,
+                phase: 'connection',
+                outcome: queryOptions.signal?.aborted ? 'cancelled' : 'unavailable',
+                durationMs: performance.now() - startedAt,
+            });
             return {
                 result: {},
                 server: route.server,
@@ -236,6 +556,7 @@ export class CapabilityCatalog {
                 refresh,
             };
         }
+        let phase = 'schema_admission';
         try {
             const adapter = connection.adapter;
             const definition = access.tool.definition ??
@@ -252,7 +573,9 @@ export class CapabilityCatalog {
                 signal: queryOptions.signal,
             };
             const contracts = await admitToolSchemas(definition, binding);
+            phase = 'input_validation';
             const validateOutput = await prepareToolValidation(contracts, args.args, binding);
+            phase = 'routing_revalidation';
             const current = await this.resolveVisibleToolAccess(args, visibility, queryOptions.toolRegistry);
             if (queryOptions.signal?.aborted ||
                 current.error ||
@@ -261,14 +584,45 @@ export class CapabilityCatalog {
                 JSON.stringify(current.route) !== JSON.stringify(route) ||
                 (current.tool.definition && JSON.stringify(current.tool.definition) !== JSON.stringify(definition)))
                 throw new SchemaBoundaryError('schema_invalid');
+            phase = 'upstream';
+            writeLocalDiagnostic('debug', 'tool.dispatch', () => ({ ...diagnosticRoute, phase }));
             const result = await requestLegacyAdapter(adapter, 'tools/call', {
                 name: route.toolName,
                 arguments: args.args,
             }, { signal: queryOptions.signal, timeoutMs: connection.requestTimeoutMs });
+            phase = 'output_validation';
             await validateOutput(result);
+            let outcome = 'success';
+            if (ownData(result, 'isError') === true)
+                outcome = 'upstream_error';
+            writeLocalDiagnostic('info', 'tool.completed', {
+                ...diagnosticRoute,
+                outcome,
+                durationMs: performance.now() - startedAt,
+            });
+            writeLocalDiagnostic('debug', 'tool.result', () => ({ ...diagnosticRoute, result }));
             return { result, server: route.server, tool: route.toolName, route, refresh };
         }
         catch (error) {
+            const errorCode = ownData(error, 'code');
+            const timedOut = errorCode === 'schema_evaluation_timeout' || errorCode === ErrorCode.RequestTimeout;
+            const failureKind = gatewayFailureFromUnknown(error, 'transport').kind;
+            let outcome = 'failed';
+            if (queryOptions.signal?.aborted || failureKind === 'cancelled')
+                outcome = 'cancelled';
+            else if (timedOut || failureKind === 'deadline-exceeded')
+                outcome = 'timeout';
+            else if (error instanceof SchemaBoundaryError)
+                outcome = 'validation_failed';
+            const failureFields = {
+                ...diagnosticRoute,
+                phase,
+                outcome,
+                error,
+                durationMs: performance.now() - startedAt,
+            };
+            writeLocalDiagnostic('warn', 'tool.failed', failureFields);
+            writeLocalDiagnostic('debug', 'tool.failure-details', () => failureFields);
             if (error instanceof SchemaBoundaryError && error.code === 'schema_input_invalid')
                 return { result: schemaInputErrorResult(), server: route.server, tool: route.toolName, route, refresh };
             if (error instanceof SchemaBoundaryError)
@@ -343,7 +697,7 @@ export class CapabilityCatalog {
             server: tool.server,
             connectionKey: tool.connectionKey,
             tags: tool.tags,
-        }))).withConnections(registry.getConnections(), () => registry.isCurrent());
+        })), registry.getListingMeta()).withConnections(registry.getConnections(), () => registry.isCurrent());
     }
     async resolveVisibleToolAccess(args, visibility, requestRegistry) {
         if (!args.server || !args.toolName) {
@@ -354,7 +708,9 @@ export class CapabilityCatalog {
                 },
             };
         }
-        const visibleRegistry = await this.visibleToolRegistry(visibility, requestRegistry);
+        const sourceRegistry = requestRegistry ?? (await this.deps.getToolRegistry());
+        await this.pruneToolAdmissionOutcomes(sourceRegistry);
+        const visibleRegistry = await this.visibleToolRegistry(visibility, sourceRegistry);
         if (typeof visibleRegistry.getTool !== 'function') {
             return {
                 error: {
@@ -364,7 +720,8 @@ export class CapabilityCatalog {
             };
         }
         const tool = visibleRegistry.getTool(args.server, args.toolName);
-        if (!tool) {
+        const withheld = tool && this.isToolWithheld(tool, sourceRegistry);
+        if (!tool || withheld) {
             const disabledError = this.isServerVisible(args.server, visibility)
                 ? getDisabledSourceToolError(this.deps.getServerConfigs(), args.server, args.toolName)
                 : undefined;
@@ -386,6 +743,20 @@ export class CapabilityCatalog {
         }
         return { route, tool, connection: visibleRegistry.getConnections()?.get(route.connectionKey) };
     }
+    isToolWithheld(tool, registry) {
+        const key = tool.connectionKey ?? tool.server;
+        const outcome = this.withheldTools.get(JSON.stringify([key, tool.name]));
+        if (!outcome?.withheld)
+            return false;
+        if (outcome.registry !== registry)
+            return false;
+        const connection = this.deps.outboundConnections.get(key);
+        if (outcome.connection !== connection)
+            return false;
+        if (outcome.adapter !== connection?.adapter)
+            return false;
+        return true;
+    }
     isServerVisible(server, visibility) {
         const effectiveVisibility = visibility ?? this.deps.defaultVisibility;
         return effectiveVisibility === undefined || getCapabilityVisibleServerNames(effectiveVisibility).has(server);
@@ -403,7 +774,7 @@ export class CapabilityCatalog {
                 kind: 'tools',
                 origin: 'external',
                 upstreamIdentity: tool.name,
-                publicIdentity: tool.route?.publicIdentity ?? `${tool.server}_1mcp_${tool.name}`,
+                publicIdentity: tool.route?.publicIdentity ?? buildPublicToolName(tool.server, tool.name),
                 server: tool.server,
                 toolName: tool.name,
                 connectionKey: registryConnectionKey,
@@ -419,7 +790,7 @@ export class CapabilityCatalog {
             kind: 'tools',
             origin: 'external',
             upstreamIdentity: tool.name,
-            publicIdentity: tool.route?.publicIdentity ?? `${tool.server}_1mcp_${tool.name}`,
+            publicIdentity: tool.route?.publicIdentity ?? buildPublicToolName(tool.server, tool.name),
             server: tool.server,
             toolName: tool.name,
             connectionKey: result.key,