toolhome 0.6.6 → 0.6.8

package/dist/server/data-plane/gateway-server.js

@@ -1,6 +1,9 @@
 import { CallToolRequestParamsSchema, CallToolResultSchema, ClientCapabilitiesSchema, CompleteResultSchema, EmptyResultSchema, GetPromptResultSchema, ListPromptsResultSchema, ListResourceTemplatesResultSchema, ListResourcesResultSchema, ListToolsResultSchema, ReadResourceResultSchema, ResultSchema, } from '@modelcontextprotocol/core';
-import { CLIENT_CAPABILITIES_META_KEY, ProtocolError, ProtocolErrorCode, SdkError, SdkErrorCode, Server, createRequestStateCodec, isInputRequiredResult, } from '@modelcontextprotocol/server';
+import { CLIENT_CAPABILITIES_META_KEY, ProtocolError, ProtocolErrorCode, SdkError, SdkErrorCode, Server, createRequestStateCodec, fromJsonSchema, isInputRequiredResult, } from '@modelcontextprotocol/server';
 import { createHash } from 'node:crypto';
+import { CompactState } from './compact-state.js';
+import { ToolCatalog } from './tool-catalog.js';
+import { CompactError, compactErrorResult, compactTools, parseExecArgs, executionBoundaryForTool, } from './compact-protocol.js';
 import { z } from 'zod';
 import { AppError } from '../domain/errors.js';
 import { fingerprint } from '../upstream/stable-json.js';
@@ -47,12 +50,15 @@ export class GatewayServerFactory {
     #cursors;
     #projections;
     #recorder;
-    constructor(registry, upstreams, cursors, masterKey, projections, recorder) {
+    #compactState = new CompactState();
+    #options;
+    constructor(registry, upstreams, cursors, masterKey, projections, recorder, options = {}) {
         this.#registry = registry;
         this.#upstreams = upstreams;
         this.#cursors = cursors;
         this.#projections = projections;
         this.#recorder = recorder;
+        this.#options = options;
         this.#stateCodec = createRequestStateCodec({
             key: createHash('sha256').update(masterKey).digest(),
             ttlSeconds: 86_400,
@@ -62,23 +68,32 @@ export class GatewayServerFactory {
     aggregate() {
         const aggregate = this.#registry.aggregate();
         const server = new Server({ name: 'toolhome', version: '0.1.0', title: 'ToolHome' }, {
-            capabilities: aggregate.capabilities,
+            capabilities: this.#options.toolMode === 'compact'
+                ? { ...aggregate.capabilities, tools: { listChanged: true } }
+                : aggregate.capabilities,
             instructions: 'ToolHome aggregates enabled servers. Tools use server_slug_encodedToolName; prompts use server_slug.name. Resources use toolhome:// virtual URIs. Use an individual /mcp/{server_slug} endpoint for exact upstream names and extension semantics.',
             requestState: { verify: this.#stateCodec.verify },
             inputRequired: { legacyShim: true },
         });
         this.#aggregateServers.add(server);
-        if (aggregate.capabilities.tools) {
+        if (this.#options.toolMode === 'compact') {
+            this.#installCompactTools(server);
+        }
+        else if (aggregate.capabilities.tools) {
             server.setRequestHandler('tools/list', async (request, context) => {
                 const entries = this.#registry.entries();
-                const tools = await this.#aggregateTools(server, entries, context, request.params);
-                const page = this.#page(tools, request.params?.cursor, fingerprint({ tools }));
+                const listed = await this.#aggregateTools(server, entries, context, request.params);
+                const tools = listed.items;
+                const page = this.#page(tools, request.params?.cursor, fingerprint({ tools, failedServers: listed.failedServers }));
                 return {
                     tools: page.items,
                     ...this.#nextCursor(page),
                     ttlMs: 0,
                     cacheScope: 'private',
-                    _meta: { 'toolhome/server-count': entries.length },
+                    _meta: {
+                        'toolhome/server-count': entries.length,
+                        ...this.#aggregateListMeta(listed),
+                    },
                 };
             });
             server.setRequestHandler('tools/call', { params: CallToolRequestParamsSchema, result: gatewayCallResultSchema }, async (request, context) => {
@@ -114,13 +129,15 @@ export class GatewayServerFactory {
         }
         if (aggregate.capabilities.prompts) {
             server.setRequestHandler('prompts/list', async (request, context) => {
-                const prompts = await this.#aggregatePrompts(server, this.#registry.entries(), context, request.params);
-                const page = this.#page(prompts, request.params?.cursor, fingerprint({ prompts }));
+                const listed = await this.#aggregatePrompts(server, this.#registry.entries(), context, request.params);
+                const prompts = listed.items;
+                const page = this.#page(prompts, request.params?.cursor, fingerprint({ prompts, failedServers: listed.failedServers }));
                 return {
                     prompts: page.items,
                     ...this.#nextCursor(page),
                     ttlMs: 0,
                     cacheScope: 'private',
+                    _meta: this.#aggregateListMeta(listed),
                 };
             });
             server.setRequestHandler('prompts/get', async (request, context) => {
@@ -135,23 +152,27 @@ export class GatewayServerFactory {
         }
         if (aggregate.capabilities.resources) {
             server.setRequestHandler('resources/list', async (request, context) => {
-                const resources = await this.#aggregateResources(server, this.#registry.entries(), context, request.params);
-                const page = this.#page(resources, request.params?.cursor, fingerprint({ resources }));
+                const listed = await this.#aggregateResources(server, this.#registry.entries(), context, request.params);
+                const resources = listed.items;
+                const page = this.#page(resources, request.params?.cursor, fingerprint({ resources, failedServers: listed.failedServers }));
                 return {
                     resources: page.items,
                     ...this.#nextCursor(page),
                     ttlMs: 0,
                     cacheScope: 'private',
+                    _meta: this.#aggregateListMeta(listed),
                 };
             });
             server.setRequestHandler('resources/templates/list', async (request, context) => {
-                const resourceTemplates = await this.#aggregateResourceTemplates(server, this.#registry.entries(), context, request.params);
-                const page = this.#page(resourceTemplates, request.params?.cursor, fingerprint({ resourceTemplates }));
+                const listed = await this.#aggregateResourceTemplates(server, this.#registry.entries(), context, request.params);
+                const resourceTemplates = listed.items;
+                const page = this.#page(resourceTemplates, request.params?.cursor, fingerprint({ resourceTemplates, failedServers: listed.failedServers }));
                 return {
                     resourceTemplates: page.items,
                     ...this.#nextCursor(page),
                     ttlMs: 0,
                     cacheScope: 'private',
+                    _meta: this.#aggregateListMeta(listed),
                 };
             });
             server.setRequestHandler('resources/read', async (request, context) => {
@@ -210,6 +231,24 @@ export class GatewayServerFactory {
             });
         }
         server.fallbackRequestHandler = async (request, context) => {
+            const listKeys = {
+                'tools/list': 'tools',
+                'prompts/list': 'prompts',
+                'resources/list': 'resources',
+                'resources/templates/list': 'resourceTemplates',
+            };
+            const emptyListKey = Object.hasOwn(listKeys, request.method)
+                ? listKeys[request.method]
+                : undefined;
+            if (emptyListKey) {
+                context.mcpReq.signal.throwIfAborted();
+                const cursor = request.params?.cursor;
+                if (cursor !== undefined && typeof cursor !== 'string') {
+                    throw new ProtocolError(ProtocolErrorCode.InvalidParams, 'Invalid cursor');
+                }
+                const page = this.#page([], cursor, fingerprint({ [emptyListKey]: [], failedServers: [] }));
+                return { [emptyListKey]: page.items, ttlMs: 0, cacheScope: 'private' };
+            }
             const taskMethod = canonicalTaskMethod(request.method);
             if (taskMethod) {
                 const params = taskParamsSchema.parse(request.params);
@@ -365,7 +404,323 @@ export class GatewayServerFactory {
         this.#installClientNotificationBridges(server, () => [entry]);
         return server;
     }
-    async #execute(server, entry, request, context) {
+    async catalogChanged() {
+        if (this.#options.toolMode !== 'compact')
+            return;
+        await this.#compactState.revoke((invocation) => {
+            try {
+                const target = this.#catalog().resolve(invocation.exposedTool);
+                return (target.entry.server.id === invocation.serverId &&
+                    this.#compactRevision(target.entry) === invocation.revision);
+            }
+            catch {
+                return false;
+            }
+        }, (invocation) => this.#terminateCompact(invocation));
+    }
+    async close() {
+        await this.#compactState.revoke(() => false, (invocation) => this.#terminateCompact(invocation));
+    }
+    #catalog() {
+        return new ToolCatalog(this.#registry.store(), this.#projections, {
+            scope: this.#options.scope ?? 'host',
+            nodeId: this.#options.nodeLabel,
+            hosts: (record) => this.#upstreams.hosts(record),
+        });
+    }
+    #compactProfile(server, context) {
+        return fingerprint({
+            principal: context.http?.authInfo?.clientId ?? 'local',
+            capabilities: this.#requestClientCapabilities(server, context),
+        });
+    }
+    #compactRevision(entry) {
+        return fingerprint({
+            server: entry.server,
+            snapshot: entry.snapshot.fingerprint,
+            projection: this.#registry.store().getProjectionIndex().get(entry.server.id)
+                ? {
+                    default: this.#registry.store().getServerProjection(entry.server.id),
+                    tools: this.#registry.store().listToolProjections(entry.server.id),
+                }
+                : null,
+        });
+    }
+    #compactKey(profile, tool) {
+        return `${profile}/${tool}`;
+    }
+    #installCompactTools(server) {
+        server.setRequestHandler('tools/list', async () => ({
+            tools: compactTools(),
+            ttlMs: 0,
+            cacheScope: 'private',
+        }));
+        server.setRequestHandler('tools/call', { params: CallToolRequestParamsSchema, result: gatewayCallResultSchema }, async (request, context) => {
+            if (request.name === 'search') {
+                const startedAt = Date.now();
+                const catalog = this.#catalog();
+                const profile = this.#compactProfile(server, context);
+                const result = catalog.search(request.arguments, (id) => {
+                    try {
+                        const resolved = catalog.resolve(id);
+                        const tool = this.#compactState.observed(this.#compactKey(profile, id), this.#compactRevision(resolved.entry));
+                        return tool ? { serverId: resolved.entry.server.id, tool } : undefined;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                });
+                this.#registry.store().appendEvent({
+                    level: 'debug',
+                    type: 'compact.search',
+                    serverId: null,
+                    message: 'Compact capability discovery',
+                    detail: {
+                        durationMs: Date.now() - startedAt,
+                        bytes: Buffer.byteLength(JSON.stringify(result)),
+                    },
+                });
+                return result;
+            }
+            if (request.name !== 'exec')
+                return compactErrorResult(new CompactError('unknown_tool', 'Use search or exec in compact mode.'));
+            return this.#compactExec(server, request, context);
+        });
+    }
+    async #compactExec(server, request, context) {
+        const startedAt = new Date();
+        let target;
+        let invocation;
+        let submitted = false;
+        let ownsInvocation = false;
+        const profile = this.#compactProfile(server, context);
+        const state = context.mcpReq.requestState();
+        try {
+            const args = parseExecArgs(request.arguments);
+            const catalog = this.#catalog();
+            const key = this.#compactKey(profile, args.tool);
+            if (!state && context.mcpReq.inputResponses !== undefined) {
+                throw new CompactError('continuation_rejected', 'Continuation state is required; the invocation will not be restarted.');
+            }
+            if (state) {
+                if (!state.compactInvocation)
+                    throw new CompactError('continuation_rejected', 'This request state belongs to a different invocation.');
+                invocation = this.#compactState.invocation(state.compactInvocation);
+                if (!invocation ||
+                    invocation.key !== key ||
+                    invocation.exposedTool !== args.tool ||
+                    state.serverId !== invocation.serverId ||
+                    !state.aggregate) {
+                    throw new CompactError('continuation_rejected', 'Continuation target or profile mismatch.');
+                }
+                if (invocation.busy)
+                    throw new CompactError('continuation_rejected', 'Continuation is already in progress.');
+                try {
+                    target = catalog.resolve(invocation.exposedTool);
+                    if (target.entry.server.id !== invocation.serverId ||
+                        this.#compactRevision(target.entry) !== invocation.revision) {
+                        throw new Error('Invocation configuration changed.');
+                    }
+                }
+                catch {
+                    await this.#terminateCompact(invocation);
+                    this.#compactState.release(invocation.id);
+                    throw new CompactError('continuation_rejected', 'Invocation is no longer enabled or visible.');
+                }
+                if (invocation.upstreamRequestState === undefined) {
+                    // No upstream round to resume: re-sending the bound arguments would be
+                    // a new business invocation, so fail closed instead of replaying.
+                    await this.#terminateCompact(invocation);
+                    this.#compactState.release(invocation.id);
+                    throw new CompactError('continuation_rejected', 'The original invocation cannot be resumed; it will not be restarted.', {
+                        nextStep: { action: 'use_individual', guidance: this.#compactEndpoint(target.entry) },
+                    });
+                }
+                if ((Object.keys(args.arguments).length > 0 &&
+                    fingerprint(args.arguments) !== fingerprint(invocation.arguments)) ||
+                    (args.definition !== undefined && args.definition !== invocation.definition)) {
+                    throw new CompactError('continuation_rejected', 'Continuation must retain its original arguments and definition.');
+                }
+                invocation.busy = true;
+                ownsInvocation = true;
+                target.tool = invocation.tool;
+                submitted = true;
+            }
+            else {
+                target = catalog.resolve(args.tool);
+                const live = (await this.#listTools(server, target.entry, context, {})).find((tool) => tool.name === target.tool.name);
+                if (!live)
+                    throw new CompactError('unknown_tool', 'The target is absent from its live directory.');
+                target.tool = live;
+                if (executionBoundaryForTool(live) !== 'exec' || this.#compactAppServer(target.entry)) {
+                    throw new CompactError('individual_endpoint_required', 'Use the original endpoint for this server’s App tools.', {
+                        nextStep: { action: 'use_individual', guidance: this.#compactEndpoint(target.entry) },
+                    });
+                }
+                const contractResult = catalog.search({ action: 'describe', tool: args.tool }, () => ({
+                    serverId: target.entry.server.id,
+                    tool: live,
+                }));
+                const contractText = contractResult.content.find((item) => item.type === 'text');
+                const contract = contractText?.type === 'text'
+                    ? JSON.parse(contractText.text)
+                    : {};
+                if (contractResult.isError)
+                    return gatewayCallResultSchema.parse(contractResult);
+                const definition = String(contract.definition);
+                const revision = this.#compactRevision(target.entry);
+                const saved = this.#compactState.observe(key, target.entry.server.id, revision, live);
+                if (args.definition !== undefined && args.definition !== definition) {
+                    throw new CompactError(saved ? 'definition_changed' : 'definition_too_large', 'The target contract changed before invocation. Obtain its current definition.', {
+                        nextStep: saved
+                            ? { action: 'describe', arguments: { action: 'describe', tool: args.tool } }
+                            : { action: 'use_individual', guidance: this.#compactEndpoint(target.entry) },
+                    });
+                }
+                const validation = await fromJsonSchema(live.inputSchema)['~standard'].validate(args.arguments);
+                if (validation.issues)
+                    throw new CompactError('invalid_arguments', validation.issues
+                        .map((issue) => issue.message)
+                        .join('; ')
+                        .slice(0, 1200));
+                const taskSupport = live.execution?.taskSupport;
+                // Task semantics are carried on the request params (`CallToolRequestParams`
+                // extends `TaskAugmentedRequestParams`), not the `_meta` envelope.
+                const taskRequested = request.task !== undefined;
+                if (taskSupport === 'required' || (taskRequested && taskSupport !== 'optional')) {
+                    throw new CompactError('individual_endpoint_required', 'Use the original endpoint for this Task/client combination.', {
+                        nextStep: { action: 'use_individual', guidance: this.#compactEndpoint(target.entry) },
+                    });
+                }
+                invocation =
+                    this.#compactState.retain({
+                        key,
+                        serverId: target.entry.server.id,
+                        exposedTool: args.tool,
+                        tool: live,
+                        arguments: args.arguments,
+                        definition,
+                        revision,
+                    }, target.entry.server.settings.maxTotalTimeoutMs, (value) => this.#terminateCompact(value)) ?? undefined;
+                if (!invocation)
+                    throw new CompactError('continuation_rejected', 'Pending invocation capacity exceeded.', {
+                        callEffect: 'not_started',
+                        nextStep: { action: 'use_individual', guidance: this.#compactEndpoint(target.entry) },
+                    });
+                invocation.busy = true;
+                ownsInvocation = true;
+            }
+            const params = this.#restoreParams({
+                ...request,
+                name: invocation.tool.name,
+                arguments: invocation.arguments,
+                ...(invocation.upstreamRequestState === undefined
+                    ? {}
+                    : { requestState: invocation.upstreamRequestState }),
+                ...(context.mcpReq.inputResponses === undefined
+                    ? {}
+                    : { inputResponses: context.mcpReq.inputResponses }),
+            }, target.entry.server.slug);
+            const raw = await this.#execute(server, target.entry, { method: 'tools/call', params }, context, {
+                toolDefinition: invocation.tool,
+                onDispatch: () => {
+                    submitted = true;
+                },
+            });
+            this.#recordCall(context, {
+                endpointType: 'aggregate',
+                serverId: target.entry.server.id,
+                exposedToolName: 'exec',
+                upstreamToolName: invocation.tool.name,
+                status: 'success',
+                startedAt,
+                raw,
+            });
+            if (isInputRequiredResult(raw)) {
+                invocation.upstreamRequestState = raw.requestState;
+                invocation.busy = false;
+                const rewritten = rewriteAggregateContent(raw, target.entry.server.slug);
+                return gatewayCallResultSchema.parse({
+                    ...rewritten,
+                    requestState: await this.#stateCodec.mint({ aggregate: true, serverId: target.entry.server.id, compactInvocation: invocation.id }, context),
+                });
+            }
+            this.#compactState.release(invocation.id);
+            return this.#parseToolResult(raw, context, target.entry.server.id, target.entry.server.slug);
+        }
+        catch (error) {
+            if (invocation && ownsInvocation) {
+                invocation.busy = false;
+                await this.#terminateCompact(invocation);
+                this.#compactState.release(invocation.id);
+            }
+            if (target)
+                this.#recordCallError(context, {
+                    endpointType: 'aggregate',
+                    serverId: target.entry.server.id,
+                    exposedToolName: 'exec',
+                    upstreamToolName: target.tool.name,
+                    startedAt,
+                    error,
+                });
+            if (CompactError.isInstance(error))
+                return compactErrorResult(state && error.callEffect === 'not_started'
+                    ? new CompactError('continuation_rejected', error.message, {
+                        callEffect: 'may_have_run',
+                        nextStep: error.nextStep,
+                    })
+                    : error);
+            if (ProtocolError.isInstance(error) && error.code === -32020 && target) {
+                let recovered = false;
+                try {
+                    const live = (await this.#listTools(server, target.entry, context, {})).find((tool) => tool.name === target.tool.name);
+                    if (live)
+                        recovered = this.#compactState.observe(this.#compactKey(profile, aggregateToolName(target.entry.server.slug, live.name)), target.entry.server.id, this.#compactRevision(target.entry), live);
+                }
+                catch {
+                    /* Recovery cannot resubmit the business invocation. */
+                }
+                return compactErrorResult(new CompactError('definition_changed', error.message, {
+                    source: 'upstream',
+                    callEffect: 'may_have_run',
+                    nextStep: {
+                        action: 'check_status',
+                        guidance: recovered
+                            ? 'Check the original invocation, then describe the target before explicitly retrying.'
+                            : this.#compactEndpoint(target.entry),
+                    },
+                    details: { upstreamCode: error.code },
+                }));
+            }
+            return compactErrorResult(new CompactError(state ? 'continuation_rejected' : 'upstream_failure', error instanceof Error ? error.message.slice(0, 1200) : 'Upstream invocation failed.', {
+                source: submitted ? 'upstream' : 'gateway',
+                callEffect: submitted || state ? 'may_have_run' : 'not_started',
+            }));
+        }
+    }
+    #compactAppServer(entry) {
+        return entry.snapshot.tools.some((tool) => executionBoundaryForTool(tool) !== 'exec');
+    }
+    #compactEndpoint(entry) {
+        return this.#options.scope === 'local'
+            ? `Use toolhome mcp launch ${entry.server.slug} on this machine.`
+            : `Use /mcp/${entry.server.slug}.`;
+    }
+    async #terminateCompact(invocation) {
+        if (invocation.upstreamRequestState !== undefined) {
+            const result = this.#upstreams.terminateContinuation(invocation.serverId, invocation.upstreamRequestState);
+            if (result.limitation) {
+                this.#registry.store().appendEvent({
+                    level: 'warn',
+                    type: 'compact.continuation.termination_limited',
+                    serverId: invocation.serverId,
+                    message: 'Upstream suspended state cannot be terminated by this gateway',
+                    detail: { kind: result.kind },
+                });
+            }
+        }
+    }
+    async #execute(server, entry, request, context, executionOptions) {
         try {
             return await this.#upstreams.execute(entry.server.id, request, context, this.#requestClientCapabilities(server, context), this.#aggregateServers.has(server)
                 ? {
@@ -373,7 +728,7 @@ export class GatewayServerFactory {
                     transformNotification: (notification) => this.#aggregateNotification(notification, entry.server.slug),
                     transformRequest: (upstreamRequest) => this.#aggregateRequest(upstreamRequest, entry.server.slug),
                 }
-                : {});
+                : {}, executionOptions);
         }
         catch (error) {
             if (ProtocolError.isInstance(error))
@@ -510,47 +865,67 @@ export class GatewayServerFactory {
             requestState: await this.#stateCodec.mint(state, context),
         };
     }
+    #aggregateListMeta(listed) {
+        return listed.failedServers.length === 0
+            ? {}
+            : { 'toolhome/failed-servers': listed.failedServers };
+    }
+    async #aggregateList(entries, context, list) {
+        context.mcpReq.signal.throwIfAborted();
+        const results = await Promise.allSettled(entries.map(list));
+        context.mcpReq.signal.throwIfAborted();
+        const items = [];
+        const failedServers = [];
+        for (const [index, result] of results.entries()) {
+            if (result.status === 'fulfilled')
+                items.push(...result.value);
+            else
+                failedServers.push(entries[index].server.slug);
+        }
+        failedServers.sort();
+        if (results.length > 0 && failedServers.length === results.length) {
+            throw new ProtocolError(ProtocolErrorCode.InternalError, 'Every upstream failed to list capabilities', {
+                'toolhome/failed-servers': failedServers,
+            });
+        }
+        return { items, failedServers };
+    }
     async #aggregateTools(server, entries, context, params) {
-        const groups = await Promise.all(entries
-            .filter(({ snapshot }) => snapshot.capabilities.tools)
-            .map(async (entry) => {
+        const listed = await this.#aggregateList(entries.filter(({ snapshot }) => snapshot.capabilities.tools), context, async (entry) => {
             const tools = await this.#listTools(server, entry, context, params);
-            // Tool visibility is an aggregate-endpoint projection: hidden tools
-            // are excluded here (and enforced again in #liveToolRoute).
+            // Tool visibility applies only to the aggregate endpoint.
             const visible = this.#projections.apply(entry.server.id, tools);
             return visible.map((tool) => ({
                 ...rewriteAggregateTool(tool, entry.server.slug),
                 name: aggregateToolName(entry.server.slug, tool.name),
             }));
-        }));
-        return groups.flat().sort((left, right) => left.name.localeCompare(right.name));
+        });
+        listed.items.sort((left, right) => left.name.localeCompare(right.name));
+        return listed;
     }
     async #aggregatePrompts(server, entries, context, params) {
-        const groups = await Promise.all(entries
-            .filter(({ snapshot }) => snapshot.capabilities.prompts)
-            .map(async (entry) => (await this.#listPrompts(server, entry, context, params)).map((prompt) => ({
+        const listed = await this.#aggregateList(entries.filter(({ snapshot }) => snapshot.capabilities.prompts), context, async (entry) => (await this.#listPrompts(server, entry, context, params)).map((prompt) => ({
             ...prompt,
             name: aggregateName(entry.server.slug, prompt.name),
-        }))));
-        return groups.flat().sort((left, right) => left.name.localeCompare(right.name));
+        })));
+        listed.items.sort((left, right) => left.name.localeCompare(right.name));
+        return listed;
     }
     async #aggregateResources(server, entries, context, params) {
-        const groups = await Promise.all(entries
-            .filter(({ snapshot }) => snapshot.capabilities.resources)
-            .map(async (entry) => (await this.#listResources(server, entry, context, params)).map((resource) => ({
+        const listed = await this.#aggregateList(entries.filter(({ snapshot }) => snapshot.capabilities.resources), context, async (entry) => (await this.#listResources(server, entry, context, params)).map((resource) => ({
             ...resource,
             uri: virtualResourceUri(entry.server.slug, resource.uri),
-        }))));
-        return groups.flat().sort((left, right) => left.uri.localeCompare(right.uri));
+        })));
+        listed.items.sort((left, right) => left.uri.localeCompare(right.uri));
+        return listed;
     }
     async #aggregateResourceTemplates(server, entries, context, params) {
-        const groups = await Promise.all(entries
-            .filter(({ snapshot }) => snapshot.capabilities.resources)
-            .map(async (entry) => (await this.#listResourceTemplates(server, entry, context, params)).map((template) => ({
+        const listed = await this.#aggregateList(entries.filter(({ snapshot }) => snapshot.capabilities.resources), context, async (entry) => (await this.#listResourceTemplates(server, entry, context, params)).map((template) => ({
             ...template,
             uriTemplate: virtualResourceTemplate(entry.server.slug, template.uriTemplate),
-        }))));
-        return groups.flat().sort((left, right) => left.uriTemplate.localeCompare(right.uriTemplate));
+        })));
+        listed.items.sort((left, right) => left.uriTemplate.localeCompare(right.uriTemplate));
+        return listed;
     }
     async #listTools(server, entry, context, params) {
         const tools = [];
@@ -759,7 +1134,18 @@ export class GatewayServerFactory {
         return { entry: route.entry, original: route.upstreamUri };
     }
     #page(items, cursor, key) {
-        const offset = cursor === undefined ? 0 : this.#cursors.decode(cursor, key).offset;
+        let offset = 0;
+        if (cursor !== undefined) {
+            try {
+                offset = this.#cursors.decode(cursor, key).offset;
+            }
+            catch (error) {
+                if (error instanceof AppError) {
+                    throw new ProtocolError(ProtocolErrorCode.InvalidParams, error.message);
+                }
+                throw error;
+            }
+        }
         const pageItems = items.slice(offset, offset + pageSize);
         const nextOffset = offset + pageItems.length;
         return {