@nitrostack/core 1.0.17 → 1.1.0-beta.1

package/dist/core/protocol/modern-v2.adapter.js

@@ -30,6 +30,12 @@ import { mapToJsonRpcError } from './features/errors.js';
 import { isInputRequired } from './features/mrtr.js';
 import { isMcpAppMode, isOpenAiMode } from '../app-mode.js';
 import { TaskContext, TaskAugmentationRequiredError } from '../task.js';
+function sessionRequiredError() {
+    const error = new Error('Session required');
+    error.name = 'SessionRequiredError';
+    error.code = -32600;
+    return error;
+}
 /** Meta-key constants (SEP-2575 / SEP-414) used to read the request envelope. */
 const META = {
     PROTOCOL_VERSION: 'io.modelcontextprotocol/protocolVersion',
@@ -42,8 +48,23 @@ export class ModernProtocolAdapter {
     era = 'modern';
     handler;
     stdioHandle;
+    /** Process-local session for the single stdio peer. Not taken from a client header. */
+    stdioSessionId;
+    /** Tool registrations on the pinned stdio server, kept to resync after visibility changes. */
+    stdioCatalog;
+    stdioResync = Promise.resolve();
     serverSdkPromise;
     taskManager;
+    /**
+     * HTTP session ids minted by this process. Client-supplied ids are not members.
+     * The first verified subject to use an id owns it.
+     */
+    issuedSessions = new Map();
+    /** Method the HTTP gate already classified for this request. The SDK consumes the body before the factory runs. */
+    gatedMethods = new WeakMap();
+    static ISSUED_SESSION_TTL_MS = 30 * 60 * 1000;
+    static MAX_ISSUED_SESSIONS = 1000;
+    lastSessionCapWarning = 0;
     constructor(registry, options = { legacyMode: 'reject' }) {
         this.registry = registry;
         this.options = options;
@@ -58,91 +79,338 @@ export class ModernProtocolAdapter {
     // ==========================================================================
     // Server construction (called per request by the SDK factory)
     // ==========================================================================
-    async buildServer() {
+    async buildServer(factoryCtx, source = 'http') {
         const sdk = await this.loadServerSdk();
         const config = this.registry.config;
         const extensions = this.advertisedExtensions();
         const serverOptions = {
             cacheHints: this.buildServerCacheHints(),
         };
+        // The SDK installs tools/list only after a tool is registered or when the
+        // tools capability is set. A session that has hidden every tool must still
+        // answer tools/list with an empty catalog.
+        const capabilities = {};
         if (Object.keys(extensions).length > 0) {
-            // Advertise the SEP-2133 extensions map on server/discover capabilities.
-            serverOptions.capabilities = { extensions };
+            capabilities.extensions = extensions;
+        }
+        if (this.registry.getTools().size > 0) {
+            capabilities.tools = {};
+        }
+        if (Object.keys(capabilities).length > 0) {
+            serverOptions.capabilities = capabilities;
         }
         const server = new sdk.McpServer({ name: config.name, version: config.version }, serverOptions);
-        await this.registerTools(server, sdk);
-        await this.registerResources(server, sdk);
+        // The SDK calls this factory once per HTTP request, with the request on
+        // `requestInfo`. Catalog shaping (session visibility) and spillover reads
+        // both need that session; a context-free list is the stateless catalog.
+        // `source` selects the stdio peer id. Hardcoding `http` made stdio list
+        // with no session and threw Session required when visibility was on.
+        const requestContext = await this.contextFromFactory(factoryCtx, source);
+        const handles = await this.registerTools(server, sdk, requestContext);
+        if (source === 'stdio') {
+            this.stdioCatalog = { server, sdk, handles };
+        }
+        await this.registerResources(server, sdk, requestContext);
         await this.registerPrompts(server, sdk);
         return server;
     }
+    /**
+     * Session and auth from the per-request factory context.
+     * `createMcpHandler` supplies `requestInfo` (the HTTP request) and optional `authInfo`.
+     */
+    async contextFromFactory(factoryCtx, source = 'http') {
+        const request = factoryCtx?.requestInfo;
+        const headerSession = request?.headers?.get?.('mcp-session-id') ||
+            request?.headers?.get?.('Mcp-Session-Id') ||
+            undefined;
+        const headerMethod = request?.headers?.get?.('mcp-method') || request?.headers?.get?.('Mcp-Method') || undefined;
+        // The legacy fallback builds the server from a cloned request, so the
+        // gate's WeakMap entry (on the original) is missing. The clone's body is
+        // still readable here; the transport reads it afterwards.
+        let method = (request ? this.gatedMethods.get(request) : undefined) ?? headerMethod;
+        if (!method && source === 'http' && request?.clone) {
+            try {
+                const body = (await request.clone().json());
+                method = typeof body?.method === 'string' ? body.method : undefined;
+            }
+            catch {
+                method = undefined;
+            }
+        }
+        // initialize, ping, and server/discover run before a session exists.
+        // A client-supplied id on those methods is not an isolation key.
+        // Stdio ignores a caller-supplied Mcp-Session-Id. That header is the HTTP
+        // isolation key, and accepting it here would let the local peer read it.
+        const sessionId = source === 'stdio'
+            ? this.stdioSessionId
+            : this.isSessionFreeMethod(method)
+                ? undefined
+                : this.httpSessionOrThrow(headerSession);
+        if (source !== 'stdio') {
+            this.bindIssuedSubject(sessionId, factoryCtx?.authInfo);
+        }
+        if (!factoryCtx && !sessionId)
+            return undefined;
+        return this.executionContextFromRequest({
+            sessionId,
+            authInfo: factoryCtx?.authInfo,
+            protocolVersion: MODERN_PROTOCOL_VERSION,
+        });
+    }
+    visibilityRequiresSession() {
+        return this.registry.hasSessionVisibility();
+    }
+    /** Methods that proceed without a server-issued session. */
+    isSessionFreeMethod(method) {
+        return method === 'initialize' || method === 'ping' || method === 'server/discover';
+    }
+    /**
+     * Remember a session id this process minted.
+     * Tests use this to present the same id a successful `initialize` would return.
+     * An id the client invented is not accepted by {@link httpSessionOrThrow}.
+     */
+    issueSession(id = crypto.randomUUID()) {
+        this.sweepIssuedSessions();
+        if (!this.issuedSessions.has(id) && this.issuedSessions.size >= ModernProtocolAdapter.MAX_ISSUED_SESSIONS) {
+            // Refusing here would let anonymous `initialize` calls lock out every new client.
+            this.evictIssuedSession();
+        }
+        const now = Date.now();
+        const existing = this.issuedSessions.get(id);
+        this.issuedSessions.set(id, {
+            createdAt: existing?.createdAt ?? now,
+            lastActive: now,
+        });
+        return id;
+    }
+    /** True when `id` is unexpired and was minted here. Refreshes its idle timer. */
+    touchIssuedSession(id) {
+        const entry = this.issuedSessions.get(id);
+        if (!entry)
+            return false;
+        if (Date.now() - entry.lastActive > ModernProtocolAdapter.ISSUED_SESSION_TTL_MS) {
+            this.issuedSessions.delete(id);
+            return false;
+        }
+        entry.lastActive = Date.now();
+        return true;
+    }
+    /** Drops the least recently active unclaimed session, or the least recently active one if all are claimed. */
+    evictIssuedSession() {
+        let oldestUnclaimed;
+        let oldest;
+        for (const [id, entry] of this.issuedSessions) {
+            if (!oldest || entry.lastActive < oldest[1])
+                oldest = [id, entry.lastActive];
+            if (!entry.subject && (!oldestUnclaimed || entry.lastActive < oldestUnclaimed[1])) {
+                oldestUnclaimed = [id, entry.lastActive];
+            }
+        }
+        const victim = (oldestUnclaimed ?? oldest)?.[0];
+        if (victim === undefined)
+            return;
+        this.issuedSessions.delete(victim);
+        const now = Date.now();
+        if (now - this.lastSessionCapWarning > 60_000) {
+            this.lastSessionCapWarning = now;
+            this.registry.logger.warn('Issued session cap reached; evicting idle sessions', {
+                cap: ModernProtocolAdapter.MAX_ISSUED_SESSIONS,
+            });
+        }
+    }
+    sweepIssuedSessions() {
+        const now = Date.now();
+        for (const [id, entry] of this.issuedSessions) {
+            if (now - entry.lastActive > ModernProtocolAdapter.ISSUED_SESSION_TTL_MS) {
+                this.issuedSessions.delete(id);
+            }
+        }
+    }
+    /**
+     * When visibility is installed, an HTTP session id must be one `issueSession` recorded.
+     * A missing or unknown id throws. Stdio does not call this.
+     */
+    httpSessionOrThrow(sessionId) {
+        if (!this.visibilityRequiresSession())
+            return sessionId;
+        if (!sessionId || !this.touchIssuedSession(sessionId)) {
+            throw sessionRequiredError();
+        }
+        return sessionId;
+    }
+    /**
+     * The first verified subject to present a minted id owns it.
+     * A later call with a different subject, or with no subject, is rejected.
+     * An id that has only been used anonymously stays anonymous until a subject claims it.
+     */
+    bindIssuedSubject(sessionId, authInfo) {
+        if (!this.visibilityRequiresSession() || !sessionId)
+            return;
+        const entry = this.issuedSessions.get(sessionId);
+        if (!entry)
+            return;
+        const subject = this.verifiedSubject(authInfo);
+        if (entry.subject && entry.subject !== subject) {
+            throw sessionRequiredError();
+        }
+        if (!entry.subject && subject) {
+            entry.subject = subject;
+        }
+    }
+    verifiedSubject(authInfo) {
+        if (!authInfo)
+            return undefined;
+        const subject = this.mapAuthInfo(authInfo)?.subject;
+        return typeof subject === 'string' && subject.length > 0 ? subject : undefined;
+    }
+    /**
+     * One context for tools/list, tools/call, and resources/read.
+     * `authInfo` is the verified SDK principal. Metadata may still carry a raw
+     * bearer token; `createExecutionContext` does not use that token as the
+     * isolation subject.
+     */
+    executionContextFromRequest(input) {
+        return this.registry.createExecutionContext({
+            toolName: input.toolName,
+            metadata: input.metadata,
+            extra: {
+                sessionId: input.sessionId,
+                protocolVersion: input.protocolVersion ?? MODERN_PROTOCOL_VERSION,
+                clientInfo: input.clientInfo,
+                clientCapabilities: input.clientCapabilities,
+                requestState: input.requestState,
+                inputResponses: input.inputResponses,
+                trace: input.trace,
+                auth: input.authInfo ? this.mapAuthInfo(input.authInfo) : undefined,
+            },
+        });
+    }
     /** Server-level per-operation cache hints for list/discover results. */
     buildServerCacheHints() {
         // Conservative shared default for list surfaces; per-resource hints still win.
         return undefined;
     }
-    async registerTools(server, sdk) {
-        for (const tool of this.registry.getTools().values()) {
-            const inputSchema = await this.toModernSchema(tool.inputSchema, 'input', sdk);
-            const outputSchema = tool.outputSchema
-                ? await this.toModernSchema(tool.outputSchema, 'output', sdk)
-                : undefined;
-            const config = {
-                description: tool.description,
-                inputSchema,
-            };
-            if (tool.title)
-                config.title = tool.title;
-            if (outputSchema)
-                config.outputSchema = outputSchema;
-            if (tool.annotations)
-                config.annotations = tool.annotations;
-            const meta = {};
-            const cacheHint = resolveToolCacheHint(tool);
-            if (cacheHint)
-                meta['io.modelcontextprotocol/cacheHint'] = cacheHint;
-            if (tool.hasComponent && tool.hasComponent()) {
-                const component = tool.getComponent();
-                const resourceUri = component.getResourceUri();
-                const componentMeta = component.getResourceMetadata();
-                meta['ui/template'] = resourceUri;
-                meta['openai/outputTemplate'] = resourceUri;
-                meta['ui'] = { resourceUri };
-                if (componentMeta) {
-                    if (componentMeta['openai/widgetCSP'] !== undefined) {
-                        meta['openai/widgetCSP'] = componentMeta['openai/widgetCSP'];
-                    }
-                    if (componentMeta['openai/widgetDescription'] !== undefined) {
-                        meta['openai/widgetDescription'] = componentMeta['openai/widgetDescription'];
-                    }
-                    if (componentMeta['openai/widgetPrefersBorder'] !== undefined) {
-                        meta['openai/widgetPrefersBorder'] = componentMeta['openai/widgetPrefersBorder'];
-                    }
-                    if (componentMeta['openai/widgetDomain'] !== undefined) {
-                        meta['openai/widgetDomain'] = componentMeta['openai/widgetDomain'];
-                    }
-                }
-            }
-            else if (tool.widget?.route || tool.outputTemplate) {
-                const route = tool.widget?.route || tool.outputTemplate;
-                const normalized = route?.startsWith('/') ? route : `/${route}`;
-                const resourceUri = `/widgets${normalized}`;
-                meta['ui/template'] = resourceUri;
-                meta['openai/outputTemplate'] = resourceUri;
-                meta['ui'] = { resourceUri };
-            }
-            if (tool.examples) {
-                meta['tool/examples'] = tool.examples;
+    async registerTools(server, sdk, requestContext) {
+        const tools = await this.registry.getTransformedTools(requestContext);
+        const handles = new Map();
+        for (const tool of tools.values()) {
+            handles.set(tool.name, await this.registerOneTool(server, sdk, tool));
+        }
+        return handles;
+    }
+    /**
+     * The stdio SDK pins one server per connection, so its catalog is built once.
+     * Re-run the pipeline for the peer session and add or remove registrations to
+     * match. Each change makes the SDK send `notifications/tools/list_changed`.
+     */
+    resyncStdioTools() {
+        const catalog = this.stdioCatalog;
+        if (!catalog)
+            return;
+        this.stdioResync = this.stdioResync
+            .then(async () => {
+            if (this.stdioCatalog !== catalog)
+                return;
+            const context = this.executionContextFromRequest({ sessionId: this.stdioSessionId });
+            const next = await this.registry.getTransformedTools(context);
+            for (const [name, handle] of [...catalog.handles]) {
+                if (next.has(name))
+                    continue;
+                handle.remove();
+                catalog.handles.delete(name);
             }
-            if (tool.isInitial) {
-                meta['tool/initial'] = true;
+            for (const tool of next.values()) {
+                if (catalog.handles.has(tool.name))
+                    continue;
+                catalog.handles.set(tool.name, await this.registerOneTool(catalog.server, catalog.sdk, tool));
             }
-            if (Object.keys(meta).length > 0) {
-                config._meta = meta;
+        })
+            .catch((error) => {
+            this.registry.logger.warn('Failed to refresh the stdio tool catalog', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        });
+    }
+    async registerOneTool(server, sdk, tool) {
+        const inputSchema = await this.toModernSchema(tool.inputSchema, 'input', sdk);
+        const outputSchema = tool.outputSchema
+            ? await this.toModernSchema(tool.outputSchema, 'output', sdk)
+            : undefined;
+        const config = {
+            description: tool.description,
+            inputSchema,
+        };
+        if (tool.title)
+            config.title = tool.title;
+        if (outputSchema)
+            config.outputSchema = outputSchema;
+        if (tool.annotations)
+            config.annotations = tool.annotations;
+        const meta = {};
+        const cacheHint = resolveToolCacheHint(tool);
+        if (cacheHint)
+            meta['io.modelcontextprotocol/cacheHint'] = cacheHint;
+        if (tool.hasComponent && tool.hasComponent()) {
+            const component = tool.getComponent();
+            const resourceUri = component.getResourceUri();
+            const componentMeta = component.getResourceMetadata();
+            meta['ui/template'] = resourceUri;
+            meta['openai/outputTemplate'] = resourceUri;
+            meta['ui'] = { resourceUri };
+            if (componentMeta) {
+                if (componentMeta['openai/widgetCSP'] !== undefined) {
+                    meta['openai/widgetCSP'] = componentMeta['openai/widgetCSP'];
+                }
+                if (componentMeta['openai/widgetDescription'] !== undefined) {
+                    meta['openai/widgetDescription'] = componentMeta['openai/widgetDescription'];
+                }
+                if (componentMeta['openai/widgetPrefersBorder'] !== undefined) {
+                    meta['openai/widgetPrefersBorder'] = componentMeta['openai/widgetPrefersBorder'];
+                }
+                if (componentMeta['openai/widgetDomain'] !== undefined) {
+                    meta['openai/widgetDomain'] = componentMeta['openai/widgetDomain'];
+                }
             }
-            server.registerTool(tool.name, config, async (args, ctx) => this.runTool(tool, args, ctx, sdk));
         }
+        else if (tool.widget?.route || tool.outputTemplate) {
+            const route = tool.widget?.route || tool.outputTemplate;
+            const normalized = route?.startsWith('/') ? route : `/${route}`;
+            const resourceUri = `/widgets${normalized}`;
+            meta['ui/template'] = resourceUri;
+            meta['openai/outputTemplate'] = resourceUri;
+            meta['ui'] = { resourceUri };
+        }
+        if (tool.examples) {
+            meta['tool/examples'] = tool.examples;
+        }
+        if (tool.isInitial) {
+            meta['tool/initial'] = true;
+        }
+        if (Object.keys(meta).length > 0) {
+            config._meta = meta;
+        }
+        return server.registerTool(tool.name, config, async (args, ctx) => {
+            // Build the context first so resolution is session-aware: authorization
+            // transforms (session visibility) need the sessionId to decide.
+            const context = this.buildContext(ctx, { toolName: tool.name });
+            const resolved = await this.registry.resolveTool(tool.name, context);
+            if (!resolved) {
+                const Missing = sdk.MethodNotFoundError;
+                if (Missing) {
+                    throw new Missing(`Tool '${tool.name}' not found`);
+                }
+                const missing = new Error(`Tool '${tool.name}' not found`);
+                missing.code = -32601;
+                throw missing;
+            }
+            const result = await this.runTool(resolved, args, ctx, sdk, context);
+            // A visibility change made by this call must be listed before its result arrives.
+            if (this.stdioCatalog?.server === server)
+                await this.stdioResync;
+            return result;
+        });
     }
-    async registerResources(server, sdk) {
+    async registerResources(server, sdk, requestContext) {
         // Static resources and template resources both flow through registerResource.
         const templateResources = this.registry.getTemplateResources();
         for (const resource of this.registry.getResources().values()) {
@@ -159,7 +427,7 @@ export class ModernProtocolAdapter {
                 config.title = resource.title;
             if (cacheHint)
                 config.cacheHint = cacheHint;
-            server.registerResource(resource.name, resource.uri, config, async (uri) => this.readResource(String(uri?.href ?? uri), resource, sdk));
+            server.registerResource(resource.name, resource.uri, config, async (uri) => this.readResource(String(uri?.href ?? uri), resource, sdk, requestContext));
         }
         // Template resources keyed by uri template.
         for (const [uriTemplate, resource] of templateResources.entries()) {
@@ -177,7 +445,7 @@ export class ModernProtocolAdapter {
                 const template = ResourceTemplateCtor
                     ? new ResourceTemplateCtor(uriTemplate, { list: undefined })
                     : uriTemplate;
-                server.registerResource(resource.name, template, config, async (uri) => this.readResource(String(uri?.href ?? uri), resource, sdk));
+                server.registerResource(resource.name, template, config, async (uri) => this.readResource(String(uri?.href ?? uri), resource, sdk, requestContext));
             }
             catch (err) {
                 this.registry.logger.warn('Failed to register modern resource template', {
@@ -194,10 +462,12 @@ export class ModernProtocolAdapter {
         if ((rawResources.size > 0 || templateResources.size > 0) && server.server && typeof server.server.setRequestHandler === 'function') {
             server.server.setRequestHandler('resources/read', async (request, ctx) => {
                 const reqUri = String(request?.params?.uri ?? '');
+                const fromCall = ctx ? this.buildContext(ctx, {}) : undefined;
+                const readContext = fromCall?.sessionId ? fromCall : requestContext;
                 // 1. Check exact match in registered resources (including path-based URIs like /widgets/...)
                 const matchingResource = rawResources.get(reqUri);
                 if (matchingResource) {
-                    const resResult = await this.readResource(reqUri, matchingResource, sdk);
+                    const resResult = await this.readResource(reqUri, matchingResource, sdk, readContext);
                     const cacheHint = resolveResourceCacheHint(matchingResource);
                     if (cacheHint) {
                         return { ...resResult, cacheHint };
@@ -211,10 +481,9 @@ export class ModernProtocolAdapter {
                 }
                 catch {
                     // If not parseable as standard URL, check if any resource matches
-                    for (const [uri, res] of rawResources.entries()) {
-                        if (uri === reqUri || uri.endsWith(reqUri) || reqUri.endsWith(uri)) {
-                            return this.readResource(reqUri, res, sdk);
-                        }
+                    const exact = rawResources.get(reqUri);
+                    if (exact) {
+                        return this.readResource(reqUri, exact, sdk, readContext);
                     }
                 }
                 if (parsedUrl) {
@@ -224,7 +493,7 @@ export class ModernProtocolAdapter {
                         if (typeof registered.readCallback === 'function') {
                             return registered.readCallback(parsedUrl, ctx);
                         }
-                        return this.readResource(reqUri, registered, sdk);
+                        return this.readResource(reqUri, registered, sdk, readContext);
                     }
                 }
                 // 3. Check template resources
@@ -296,8 +565,8 @@ export class ModernProtocolAdapter {
     // ==========================================================================
     // Handlers
     // ==========================================================================
-    async runTool(tool, args, ctx, sdk) {
-        const context = this.buildContext(ctx, { toolName: tool.name });
+    async runTool(tool, args, ctx, sdk, prebuiltContext) {
+        const context = prebuiltContext ?? this.buildContext(ctx, { toolName: tool.name });
         const isTaskAugmented = ctx?.task !== undefined || ctx?.mcpReq?.params?.task !== undefined;
         // Enforce tool-level task support negotiation
         if (tool.taskSupport === 'required' && !isTaskAugmented) {
@@ -335,14 +604,21 @@ export class ModernProtocolAdapter {
                     message: result.message,
                 });
             }
-            const response = {
-                content: [
-                    {
-                        type: 'text',
-                        text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
-                    },
-                ],
-            };
+            const isCallToolResult = result !== null &&
+                typeof result === 'object' &&
+                Array.isArray(result.content) &&
+                result.content.length > 0 &&
+                typeof result.content[0]?.type === 'string';
+            const response = isCallToolResult
+                ? { ...result }
+                : {
+                    content: [
+                        {
+                            type: 'text',
+                            text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
             if (tool.hasComponent()) {
                 const component = tool.getComponent();
                 response.structuredContent = (await component.transformData(result, context));
@@ -401,10 +677,14 @@ export class ModernProtocolAdapter {
             err.data = mapped.data;
         return err;
     }
-    async readResource(uri, resource, sdk) {
-        const context = this.registry.createExecutionContext({
-            extra: { protocolVersion: MODERN_PROTOCOL_VERSION },
-        });
+    async readResource(uri, resource, sdk, requestContext) {
+        // requestContext already passed through createExecutionContext once.
+        // Feeding its sessionId back in as extra.sessionId runs sessionIsolationKey
+        // a second time and the spillover read no longer matches the write.
+        const context = requestContext ??
+            this.registry.createExecutionContext({
+                extra: { protocolVersion: MODERN_PROTOCOL_VERSION },
+            });
         let content;
         try {
             content = await resource.fetch(context, uri);
@@ -455,11 +735,9 @@ export class ModernProtocolAdapter {
         }
         const trace = extractTraceContext({ ...meta, ...envelope });
         const inputResponses = mcpReq.inputResponses;
-        const authInfo = readEnvelope('auth', 'io.modelcontextprotocol/auth') ??
-            ctx?.http?.authInfo ??
-            mcpReq?.http?.authInfo ??
-            ctx?.authInfo ??
-            ctx?.auth;
+        // Envelope and `_meta` are the client request. A subject there must not
+        // become the isolation principal. Only auth the host or SDK attached.
+        const authInfo = this.trustedAuthInfo(ctx);
         const rawHeaders = {};
         const reqHeaders = ctx?.http?.req?.headers ||
             ctx?.http?.headers ||
@@ -520,18 +798,33 @@ export class ModernProtocolAdapter {
             metadata._oauth = rawToken;
             metadata.jwtToken = rawToken;
         }
-        return this.registry.createExecutionContext({
+        // Header only. requestState is client-echoed MRTR state and must not select a session.
+        let sessionId = rawHeaders['mcp-session-id'] ||
+            rawHeaders['Mcp-Session-Id'] ||
+            ctx?.request?.headers?.get?.('mcp-session-id') ||
+            ctx?.req?.headers?.get?.('mcp-session-id') ||
+            undefined;
+        const hasHttpRequest = Boolean(reqHeaders || ctx?.http || ctx?.request || ctx?.req);
+        const usingStdioPeer = !hasHttpRequest && Boolean(this.stdioSessionId);
+        if (usingStdioPeer) {
+            // The stdio peer has one minted id. A header here is not a second session.
+            sessionId = this.stdioSessionId;
+        }
+        else {
+            sessionId = this.httpSessionOrThrow(sessionId);
+            this.bindIssuedSubject(sessionId, authInfo);
+        }
+        return this.executionContextFromRequest({
             toolName: opts.toolName,
             metadata,
-            extra: {
-                protocolVersion,
-                clientInfo,
-                clientCapabilities,
-                requestState,
-                inputResponses,
-                trace,
-                auth: authInfo ? this.mapAuthInfo(authInfo) : undefined,
-            },
+            sessionId,
+            authInfo,
+            protocolVersion,
+            clientInfo,
+            clientCapabilities,
+            requestState,
+            inputResponses,
+            trace,
         });
     }
     mapAuthInfo(authInfo) {
@@ -581,7 +874,7 @@ export class ModernProtocolAdapter {
     async getHttpHandler() {
         if (!this.handler) {
             const sdk = await this.loadServerSdk();
-            const rawHandler = sdk.createMcpHandler(() => this.buildServer(), {
+            const rawHandler = sdk.createMcpHandler((ctx) => this.buildServer(ctx, 'http'), {
                 legacy: this.options.legacyMode,
                 onerror: (error) => {
                     this.registry.logger.error('Modern MCP handler error', { error: error.message });
@@ -591,6 +884,11 @@ export class ModernProtocolAdapter {
             this.handler = {
                 ...rawHandler,
                 fetch: async (request, requestOptions) => {
+                    if (this.visibilityRequiresSession()) {
+                        const blocked = await this.visibilityHttpGate(request);
+                        if (blocked)
+                            return blocked;
+                    }
                     if (request.headers.get('mcp-method') === 'ping') {
                         try {
                             const clone = request.clone();
@@ -624,23 +922,209 @@ export class ModernProtocolAdapter {
                             // Not JSON or cannot intercept; let rawFetch handle
                         }
                     }
-                    return rawFetch(request, requestOptions);
+                    const response = await rawFetch(request, requestOptions);
+                    if (this.visibilityRequiresSession()) {
+                        return this.attachIssuedSession(request, response);
+                    }
+                    return response;
                 },
             };
         }
         return this.handler;
     }
-    extractAccessContext(req, parsedBody) {
+    sessionRequiredResponse(id) {
+        return new Response(JSON.stringify({
+            jsonrpc: '2.0',
+            id,
+            error: { code: -32600, message: 'Session required' },
+        }), { status: 200, headers: { 'Content-Type': 'application/json' } });
+    }
+    /**
+     * Session gate for the modern HTTP fetch path.
+     * `initialize`, `ping`, and `server/discover` proceed without a session.
+     * `tools/list`, `tools/call`, and `resources/read` need an id this process minted.
+     * A POST whose method cannot be read fails closed.
+     */
+    async visibilityHttpGate(request) {
+        const headerMethod = request.headers.get('mcp-method') || request.headers.get('Mcp-Method');
+        let bodyMethod;
+        let bodyId = null;
+        let bodyReadable = true;
+        if (request.method === 'POST') {
+            try {
+                const body = (await request.clone().json());
+                bodyMethod = typeof body?.method === 'string' ? body.method : undefined;
+                bodyId = body?.id ?? null;
+            }
+            catch {
+                bodyReadable = false;
+            }
+        }
+        if (request.method === 'POST' && !bodyReadable && !headerMethod) {
+            return this.sessionRequiredResponse(null);
+        }
+        // The body is the method that will run. A session-free header must not
+        // hide tasks/get or tools/call.
+        if (headerMethod && bodyMethod && headerMethod !== bodyMethod) {
+            return this.sessionRequiredResponse(bodyId);
+        }
+        const method = bodyMethod ?? headerMethod;
+        this.gatedMethods.set(request, typeof method === 'string' ? method : undefined);
+        if (this.isSessionFreeMethod(method)) {
+            return null;
+        }
+        const session = request.headers.get('mcp-session-id') || request.headers.get('Mcp-Session-Id') || undefined;
+        const needsSession = method === 'tools/list' ||
+            method === 'tools/call' ||
+            method === 'resources/read' ||
+            method === 'tasks/get' ||
+            method === 'tasks/cancel' ||
+            method === 'tasks/update' ||
+            (!method && request.method === 'POST');
+        if ((needsSession && !session) || (session && !this.touchIssuedSession(session))) {
+            return this.sessionRequiredResponse(bodyId);
+        }
+        return null;
+    }
+    /** Stamp a freshly minted session id onto a successful initialize response. */
+    async attachIssuedSession(request, response) {
+        const headerMethod = request.headers.get('mcp-method') || request.headers.get('Mcp-Method');
+        const method = this.gatedMethods.get(request) ?? headerMethod;
+        if (method !== 'initialize' || !response.ok)
+            return response;
+        const contentType = response.headers.get('content-type');
+        const text = await this.readResponseText(response, contentType);
+        const parsed = this.extractRpcMessage(text, contentType);
+        const headers = new Headers(response.headers);
+        if (parsed && parsed.error == null && parsed.result) {
+            headers.set('mcp-session-id', this.issueSession());
+        }
+        return new Response(text, { status: response.status, statusText: response.statusText, headers });
+    }
+    /**
+     * Read a finite JSON body, or the first SSE frame.
+     * A legacy initialize answer is a stream that stays open after the handshake.
+     */
+    async readResponseText(response, contentType) {
+        if (!contentType?.includes('text/event-stream') || !response.body) {
+            return response.text();
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        const deadline = Date.now() + 5000;
+        try {
+            while (Date.now() < deadline) {
+                const { value, done } = await reader.read();
+                if (value)
+                    buffer += decoder.decode(value, { stream: true });
+                if (this.extractRpcMessage(buffer, contentType))
+                    break;
+                if (done)
+                    break;
+            }
+        }
+        finally {
+            await reader.cancel().catch(() => undefined);
+        }
+        return buffer;
+    }
+    /** First JSON-RPC message from a JSON body or an SSE `data:` frame. */
+    extractRpcMessage(text, contentType) {
+        if (contentType?.includes('text/event-stream')) {
+            for (const line of text.split('\n')) {
+                const trimmed = line.trim();
+                if (!trimmed.startsWith('data:'))
+                    continue;
+                try {
+                    const parsed = JSON.parse(trimmed.slice(5).trim());
+                    if (parsed && (parsed.result !== undefined || parsed.error !== undefined))
+                        return parsed;
+                }
+                catch {
+                    /* keep scanning */
+                }
+            }
+            return undefined;
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Raw mcp-session-id from a Web Request or an Express request. Not an isolation key. */
+    requestSessionId(req) {
         const reqAny = req;
-        const auth = reqAny?.auth || reqAny?.user;
+        const headers = reqAny?.headers;
+        const fromObject = headers?.['mcp-session-id'] || headers?.['Mcp-Session-Id'];
+        const fromGetter = typeof headers?.get === 'function'
+            ? headers.get('mcp-session-id') || headers.get('Mcp-Session-Id')
+            : undefined;
+        const fromExpress = typeof reqAny?.get === 'function'
+            ? reqAny.get('mcp-session-id') || reqAny.get('Mcp-Session-Id')
+            : undefined;
+        const value = fromObject || fromGetter || fromExpress;
+        return typeof value === 'string' && value.length > 0 ? value : undefined;
+    }
+    /**
+     * Principal attached by the host or the SDK.
+     * `auth` on the request body and `_meta` are not verified and are ignored.
+     */
+    trustedAuthInfo(source) {
+        if (!source || typeof source !== 'object')
+            return undefined;
+        const mcpReq = (source.mcpReq ?? {});
+        const candidates = [source.http?.authInfo, mcpReq.http?.authInfo, source.authInfo];
+        for (const candidate of candidates) {
+            if (candidate && typeof candidate === 'object')
+                return candidate;
+        }
+        return undefined;
+    }
+    /** SDK authInfo when the host attached it. A bearer header is not verified here. */
+    requestAuthInfo(req) {
+        return this.trustedAuthInfo(req);
+    }
+    extractAccessContext(req, _parsedBody) {
+        const reqAny = req;
+        const auth = (reqAny?.authInfo || reqAny?.auth || reqAny?.user);
         const userId = auth?.sub || auth?.userId || auth?.id;
         const tenantId = auth?.tenantId || auth?.orgId;
-        const sessionId = reqAny?.headers?.['mcp-session-id'] || reqAny?.get?.('mcp-session-id');
+        const sessionId = this.requestSessionId(req);
         if (!userId && !tenantId && !sessionId) {
             return undefined;
         }
         return { userId, tenantId, sessionId };
     }
+    /**
+     * tasks/get, tasks/cancel, and tasks/update carry tool results. When visibility
+     * is on they need the same minted session as tools/call. params.sessionId is
+     * not a credential.
+     */
+    taskAccessForRequest(req, id, accessContext) {
+        if (!this.visibilityRequiresSession()) {
+            return { access: accessContext };
+        }
+        try {
+            const issued = this.httpSessionOrThrow(this.requestSessionId(req));
+            this.bindIssuedSubject(issued, this.requestAuthInfo(req));
+            return { access: { ...(accessContext ?? {}), sessionId: issued } };
+        }
+        catch (err) {
+            return {
+                error: {
+                    jsonrpc: '2.0',
+                    id: id ?? null,
+                    error: {
+                        code: -32600,
+                        message: err instanceof Error ? err.message : 'Session required',
+                    },
+                },
+            };
+        }
+    }
     async handleTaskPreDispatch(body, req) {
         if (!this.taskManager || !body || typeof body !== 'object')
             return null;
@@ -652,8 +1136,11 @@ export class ModernProtocolAdapter {
             if (!taskId) {
                 return { jsonrpc: '2.0', id: id ?? null, error: { code: -32602, message: 'Invalid params: taskId is required' } };
             }
+            const gated = this.taskAccessForRequest(req, id, accessContext);
+            if (gated.error)
+                return gated.error;
             try {
-                const entry = this.taskManager.getEntry(taskId, accessContext);
+                const entry = this.taskManager.getEntry(taskId, gated.access);
                 const resultPayload = { ...entry.data };
                 if (entry.data.status === 'completed' && entry.result !== undefined) {
                     resultPayload.result = entry.result;
@@ -673,8 +1160,11 @@ export class ModernProtocolAdapter {
             if (!taskId) {
                 return { jsonrpc: '2.0', id: id ?? null, error: { code: -32602, message: 'Invalid params: taskId is required' } };
             }
+            const gated = this.taskAccessForRequest(req, id, accessContext);
+            if (gated.error)
+                return gated.error;
             try {
-                const taskData = this.taskManager.cancelTask(taskId, accessContext);
+                const taskData = this.taskManager.cancelTask(taskId, gated.access);
                 return { jsonrpc: '2.0', id: id ?? null, result: taskData };
             }
             catch (err) {
@@ -687,8 +1177,11 @@ export class ModernProtocolAdapter {
             if (!taskId) {
                 return { jsonrpc: '2.0', id: id ?? null, error: { code: -32602, message: 'Invalid params: taskId is required' } };
             }
+            const gated = this.taskAccessForRequest(req, id, accessContext);
+            if (gated.error)
+                return gated.error;
             try {
-                const taskData = this.taskManager.updateStatus(taskId, params.status || 'working', params.statusMessage, accessContext);
+                const taskData = this.taskManager.updateStatus(taskId, params.status || 'working', params.statusMessage, gated.access);
                 return { jsonrpc: '2.0', id: id ?? null, result: taskData };
             }
             catch (err) {
@@ -717,14 +1210,55 @@ export class ModernProtocolAdapter {
                 },
             };
         }
-        // 6. tools/call with task augmentation OR mandatory task support check
-        if (method === 'tools/call' && params) {
+        // 6. tools/call with task augmentation OR mandatory task support check.
+        // Resolution goes through the transform chain so session visibility still applies.
+        // The raw catalog lookup used to execute hidden and disabled tools.
+        if (method === 'tools/call' && params && typeof params.name === 'string') {
             const toolName = params.name;
-            const tool = this.registry.getTools().get(toolName);
-            if (!tool)
-                return null; // Let standard flow handle tool not found
+            let issuedSession;
+            const taskAuth = this.requestAuthInfo(req);
+            try {
+                issuedSession = this.httpSessionOrThrow(this.requestSessionId(req));
+                this.bindIssuedSubject(issuedSession, taskAuth);
+            }
+            catch (err) {
+                return {
+                    jsonrpc: '2.0',
+                    id: id ?? null,
+                    error: {
+                        code: -32600,
+                        message: err instanceof Error ? err.message : 'Session required',
+                    },
+                };
+            }
+            const executionContext = this.executionContextFromRequest({
+                toolName,
+                sessionId: issuedSession,
+                authInfo: taskAuth,
+            });
+            let tool;
+            try {
+                tool = await this.registry.resolveTool(toolName, executionContext);
+            }
+            catch (err) {
+                const coded = err;
+                return {
+                    jsonrpc: '2.0',
+                    id: id ?? null,
+                    error: {
+                        code: typeof coded.code === 'number' ? coded.code : -32603,
+                        message: err instanceof Error ? err.message : String(err),
+                    },
+                };
+            }
+            if (!tool) {
+                return {
+                    jsonrpc: '2.0',
+                    id: id ?? null,
+                    error: { code: -32601, message: `Tool '${toolName}' not found` },
+                };
+            }
             const isTaskAugmented = params.task !== undefined;
-            // Enforcement: if taskSupport === 'required' and not task-augmented
             if (!isTaskAugmented && tool.taskSupport === 'required') {
                 return {
                     jsonrpc: '2.0',
@@ -732,58 +1266,54 @@ export class ModernProtocolAdapter {
                     error: { code: -32600, message: `Task augmentation required for tools/call requests on tool '${toolName}'` },
                 };
             }
-            // If task-augmented:
-            if (isTaskAugmented) {
-                if (tool.taskSupport === 'forbidden') {
-                    return {
-                        jsonrpc: '2.0',
-                        id: id ?? null,
-                        error: { code: -32601, message: `Tool '${toolName}' does not support task augmentation` },
-                    };
-                }
-                const taskData = this.taskManager.createTask(params.task, toolName, accessContext);
-                const taskId = taskData.taskId;
-                const taskContext = new TaskContext(this.taskManager, taskId);
-                const executionContext = this.registry.createExecutionContext({
-                    toolName,
-                    extra: {
-                        task: taskContext,
-                    },
-                });
-                executionContext.task = taskContext;
-                const tm = this.taskManager;
-                // Run tool asynchronously in the background
-                Promise.resolve().then(async () => {
-                    try {
-                        const argsRecord = (params.arguments || {});
-                        const { _meta: _, ...toolArgs } = argsRecord;
-                        const toolResult = await tool.execute(toolArgs, executionContext);
-                        if (tm.hasTask(taskId)) {
-                            const current = tm.getTask(taskId);
-                            if (current.status !== 'cancelled') {
-                                tm.completeTask(taskId, toolResult, undefined, accessContext);
-                            }
-                        }
-                    }
-                    catch (err) {
-                        if (tm.hasTask(taskId)) {
-                            const current = tm.getTask(taskId);
-                            if (current.status !== 'cancelled') {
-                                tm.failTask(taskId, { code: err.code || -32603, message: err.message || String(err) }, undefined, accessContext);
-                            }
-                        }
-                    }
-                });
-                // Return CreateTaskResult immediately
+            // Synchronous tools/call stays on the registered handler, which resolves again.
+            if (!isTaskAugmented)
+                return null;
+            if (tool.taskSupport === 'forbidden') {
                 return {
                     jsonrpc: '2.0',
                     id: id ?? null,
-                    result: {
-                        task: taskData,
-                        resultType: 'task',
-                    },
+                    error: { code: -32601, message: `Tool '${toolName}' does not support task augmentation` },
                 };
             }
+            const taskData = this.taskManager.createTask(params.task, toolName, accessContext);
+            const taskId = taskData.taskId;
+            const taskContext = new TaskContext(this.taskManager, taskId);
+            executionContext.task = taskContext;
+            const tm = this.taskManager;
+            Promise.resolve().then(async () => {
+                try {
+                    const argsRecord = (params.arguments || {});
+                    const { _meta: _, ...toolArgs } = argsRecord;
+                    const toolResult = await tool.execute(toolArgs, executionContext);
+                    if (tm.hasTask(taskId)) {
+                        const current = tm.getTask(taskId);
+                        if (current.status !== 'cancelled') {
+                            tm.completeTask(taskId, toolResult, undefined, accessContext);
+                        }
+                    }
+                }
+                catch (err) {
+                    if (tm.hasTask(taskId)) {
+                        const current = tm.getTask(taskId);
+                        if (current.status !== 'cancelled') {
+                            const coded = err;
+                            tm.failTask(taskId, {
+                                code: typeof coded.code === 'number' ? coded.code : -32603,
+                                message: err instanceof Error ? err.message : String(err),
+                            }, undefined, accessContext);
+                        }
+                    }
+                }
+            });
+            return {
+                jsonrpc: '2.0',
+                id: id ?? null,
+                result: {
+                    task: taskData,
+                    resultType: 'task',
+                },
+            };
         }
         return null;
     }
@@ -865,7 +1395,8 @@ export class ModernProtocolAdapter {
     }
     /**
      * SEP-2243/SEP-2575 CORS: expose and allow the new required request headers
-     * (`MCP-Protocol-Version`, `Mcp-Method`, `Mcp-Name`, and `Mcp-Param-*`).
+     * (`MCP-Protocol-Version`, `Mcp-Method`, `Mcp-Name`, `Mcp-Param-*`, and
+     * `Mcp-Session-Id`). Session visibility and spillover both read that header.
      */
     applyCorsHeaders(req, res) {
         const origin = req.headers.origin;
@@ -879,20 +1410,26 @@ export class ModernProtocolAdapter {
             'Mcp-Method',
             'Mcp-Name',
             'Mcp-Param-*',
+            'Mcp-Session-Id',
             'Last-Event-ID',
         ].join(', '));
         res.setHeader('Access-Control-Expose-Headers', ['MCP-Protocol-Version', 'Mcp-Method', 'Mcp-Name'].join(', '));
     }
     async serveStdio() {
+        this.stdioSessionId ??= crypto.randomUUID();
         const stdio = (await import('@modelcontextprotocol/server/stdio'));
-        this.stdioHandle = stdio.serveStdio(() => this.buildServer());
+        this.stdioHandle = stdio.serveStdio((ctx) => this.buildServer(ctx, 'stdio'));
         this.registry.logger.info(`Modern MCP (${MODERN_PROTOCOL_VERSION}) serving over stdio`);
     }
     // ==========================================================================
     // Notifications (subscriptions/listen bus)
     // ==========================================================================
-    notifyToolsListChanged() {
-        this.handler?.notify?.toolsChanged?.();
+    notifyToolsListChanged(sessionId) {
+        if (!sessionId || sessionId === this.stdioSessionId) {
+            this.resyncStdioTools();
+        }
+        this.handler?.notify?.toolsChanged?.(sessionId);
+        this.handler?.bus?.emit?.('tools_changed', sessionId ? { sessionId } : {});
     }
     notifyResourcesListChanged() {
         this.handler?.notify?.resourcesChanged?.();
@@ -927,6 +1464,7 @@ export class ModernProtocolAdapter {
         }
         this.handler = undefined;
         this.stdioHandle = undefined;
+        this.stdioCatalog = undefined;
     }
     /** The extensions map this adapter would advertise (for diagnostics/notes). */
     advertisedExtensions() {