@frontmcp/sdk 0.5.0 → 0.6.0

package/src/prompt/flows/prompts-list.flow.d.ts

@@ -4,8 +4,15 @@ import { z } from 'zod';
 declare const inputSchema: z.ZodObject<{
     request: z.ZodObject<{
         params: z.ZodOptional<z.ZodObject<{
+            task: z.ZodOptional<z.ZodObject<{
+                ttl: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodNull]>>;
+                pollInterval: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$loose>>;
             _meta: z.ZodOptional<z.ZodObject<{
                 progressToken: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+                "io.modelcontextprotocol/related-task": z.ZodOptional<z.ZodObject<{
+                    taskId: z.ZodString;
+                }, z.core.$loose>>;
             }, z.core.$loose>>;
             cursor: z.ZodOptional<z.ZodString>;
         }, z.core.$loose>>;
@@ -14,7 +21,11 @@ declare const inputSchema: z.ZodObject<{
     ctx: z.ZodUnknown;
 }, z.core.$strip>;
 declare const outputSchema: z.ZodObject<{
-    _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    _meta: z.ZodOptional<z.ZodObject<{
+        "io.modelcontextprotocol/related-task": z.ZodOptional<z.ZodObject<{
+            taskId: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
     nextCursor: z.ZodOptional<z.ZodString>;
     prompts: z.ZodArray<z.ZodObject<{
         description: z.ZodOptional<z.ZodString>;

package/src/provider/provider.registry.d.ts

@@ -11,6 +11,18 @@ export default class ProviderRegistry extends RegistryAbstract<ProviderEntry, Pr
     /** topo order (deps first) */
     private order;
     private registries;
+    /** Session-scoped provider instance cache by sessionKey */
+    private sessionStores;
+    /** Locks to prevent concurrent session builds (race condition prevention) */
+    private sessionBuildLocks;
+    /** Maximum number of sessions to cache (LRU eviction) */
+    private static readonly MAX_SESSION_CACHE_SIZE;
+    /** Session cache TTL in milliseconds (1 hour) */
+    private static readonly SESSION_CACHE_TTL_MS;
+    /** Cleanup interval in milliseconds (1 minute) */
+    private static readonly SESSION_CLEANUP_INTERVAL_MS;
+    /** Handle for the session cleanup interval */
+    private sessionCleanupInterval;
     constructor(list: ProviderType[], parentProviders?: ProviderRegistry | undefined);
     getProviders(): ProviderEntry[];
     /** Walk up the registry chain to find a def for a token. */
@@ -32,6 +44,15 @@ export default class ProviderRegistry extends RegistryAbstract<ProviderEntry, Pr
     getAllSingletons(): ReadonlyMap<Token, unknown>;
     discoveryDeps(rec: ProviderRecord): Token[];
     invocationTokens(_token: Token, rec: ProviderRecord): Token[];
+    /**
+     * Normalize deprecated scopes to their modern equivalents.
+     *
+     * - SESSION → CONTEXT (deprecated)
+     * - REQUEST → CONTEXT (deprecated)
+     *
+     * This enables backwards compatibility while unifying the scope model.
+     */
+    private normalizeScope;
     getProviderScope(rec: ProviderRecord): ProviderScope;
     getScope(): ScopeEntry;
     private withTimeout;
@@ -73,10 +94,81 @@ export default class ProviderRegistry extends RegistryAbstract<ProviderEntry, Pr
     getActiveScope(): Scope;
     getActiveServer(): FrontMcpServer;
     /**
-     * Build provider instance views for different scopes
-     * NOTE: This is currently a stub implementation returning empty maps.
-     * Actual view building logic is planned as part of the session management refactoring.
-     * See the ProviderRegistryInterface TODO for fixing the session type.
+     * Clean up a specific session's provider cache.
+     * Call this when a session is terminated or expired.
+     *
+     * @param sessionKey - The session identifier to clean up
+     */
+    cleanupSession(sessionKey: string): void;
+    /**
+     * Clean up expired sessions from the cache.
+     * Sessions older than SESSION_CACHE_TTL_MS are removed.
+     *
+     * @returns Number of sessions cleaned up
+     */
+    cleanupExpiredSessions(): number;
+    /**
+     * Start the background session cleanup timer.
+     * This periodically removes expired sessions from the cache.
+     */
+    startSessionCleanup(): void;
+    /**
+     * Stop the background session cleanup timer.
+     * Call this when shutting down the server gracefully.
+     */
+    stopSessionCleanup(): void;
+    /**
+     * Dispose of the registry, cleaning up all resources.
+     * Call this when the registry/scope is being destroyed to prevent:
+     * - Memory leaks from retained interval handles
+     * - Orphaned session cleanup timers
+     *
+     * @example
+     * ```typescript
+     * // In scope teardown
+     * scope.providers.dispose();
+     * ```
+     */
+    dispose(): void;
+    /**
+     * Get session cache statistics for monitoring.
+     */
+    getSessionCacheStats(): {
+        size: number;
+        maxSize: number;
+        ttlMs: number;
+    };
+    /**
+     * Build provider instance views for different scopes.
+     *
+     * This method creates a complete view of providers across all scopes:
+     * - GLOBAL: Returns existing singleton instances (read-only)
+     * - CONTEXT: Builds per-context providers (unified session + request)
+     *
+     * Note: For backwards compatibility, SESSION and REQUEST scopes are normalized
+     * to CONTEXT. The returned views include `session` and `request` aliases that
+     * both point to the `context` store.
+     *
+     * @param sessionKey - Unique context/session identifier for CONTEXT-scoped providers
+     * @param contextProviders - Optional pre-built CONTEXT-scoped providers (e.g., FrontMcpContext)
+     * @returns ProviderViews with global and context provider maps (session/request as aliases)
+     */
+    buildViews(sessionKey: string, contextProviders?: Map<Token, unknown>): Promise<ProviderViews>;
+    /**
+     * Build a provider into a store, with access to context and global views for dependencies.
+     */
+    private buildIntoStoreWithViews;
+    /**
+     * Resolve a dependency from the available views (context → global).
+     */
+    private resolveFromViews;
+    /**
+     * Get a provider from the given views, checking context → global.
+     *
+     * @param token - The provider token to look up
+     * @param views - The provider views to search
+     * @returns The provider instance
+     * @throws Error if provider not found in any view
      */
-    buildViews(session: string): Promise<ProviderViews>;
+    getScoped<T>(token: Token<T>, views: ProviderViews): T;
 }

package/src/provider/provider.registry.js

@@ -7,6 +7,7 @@ const token_utils_1 = require("../utils/token.utils");
 const metadata_utils_1 = require("../utils/metadata.utils");
 const regsitry_1 = require("../regsitry");
 const scope_1 = require("../scope");
+const session_key_provider_1 = require("../context/session-key.provider");
 class ProviderRegistry extends regsitry_1.RegistryAbstract {
     parentProviders;
     /** used to track which registry provided which token */
@@ -16,6 +17,18 @@ class ProviderRegistry extends regsitry_1.RegistryAbstract {
     // /** scoped instance stores by key */
     // private scoped = new Map<string, Map<Token, any>>();
     registries = new Map();
+    /** Session-scoped provider instance cache by sessionKey */
+    sessionStores = new Map();
+    /** Locks to prevent concurrent session builds (race condition prevention) */
+    sessionBuildLocks = new Map();
+    /** Maximum number of sessions to cache (LRU eviction) */
+    static MAX_SESSION_CACHE_SIZE = 10000;
+    /** Session cache TTL in milliseconds (1 hour) */
+    static SESSION_CACHE_TTL_MS = 3600000;
+    /** Cleanup interval in milliseconds (1 minute) */
+    static SESSION_CLEANUP_INTERVAL_MS = 60000;
+    /** Handle for the session cleanup interval */
+    sessionCleanupInterval = null;
     constructor(list, parentProviders) {
         super('ProviderRegistry', parentProviders, list, false);
         this.parentProviders = parentProviders;
@@ -141,6 +154,13 @@ class ProviderRegistry extends regsitry_1.RegistryAbstract {
                 throw new Error(`Failed constructing ${(0, token_utils_1.tokenName)(token)}: ${msg}`);
             }
         }
+        // Start background session cleanup after initialization
+        // This ensures expired sessions are periodically cleaned up (TTL enforcement)
+        // Only start for scope-level registries (those with parentProviders) since
+        // SESSION providers are stored in scope registries, not the global registry
+        if (this.parentProviders) {
+            this.startSessionCleanup();
+        }
     }
     /* -------------------- Views & session stores -------------------- */
     /** Return the live singleton map as a read-only view. No copying. */
@@ -153,8 +173,26 @@ class ProviderRegistry extends regsitry_1.RegistryAbstract {
     invocationTokens(_token, rec) {
         return (0, provider_utils_1.providerInvocationTokens)(rec, (k, phase) => (0, token_utils_1.depsOfClass)(k, phase));
     }
+    /**
+     * Normalize deprecated scopes to their modern equivalents.
+     *
+     * - SESSION → CONTEXT (deprecated)
+     * - REQUEST → CONTEXT (deprecated)
+     *
+     * This enables backwards compatibility while unifying the scope model.
+     */
+    normalizeScope(scope) {
+        switch (scope) {
+            case common_1.ProviderScope.SESSION:
+            case common_1.ProviderScope.REQUEST:
+                return common_1.ProviderScope.CONTEXT;
+            default:
+                return scope;
+        }
+    }
     getProviderScope(rec) {
-        return rec.metadata?.scope ?? common_1.ProviderScope.GLOBAL;
+        const rawScope = rec.metadata?.scope ?? common_1.ProviderScope.GLOBAL;
+        return this.normalizeScope(rawScope);
     }
     getScope() {
         return this.getActiveScope();
@@ -553,19 +591,278 @@ class ProviderRegistry extends regsitry_1.RegistryAbstract {
     getActiveServer() {
         return this.getWithParents(common_1.FrontMcpServer);
     }
+    /* -------------------- Session Cache Management -------------------- */
+    /**
+     * Clean up a specific session's provider cache.
+     * Call this when a session is terminated or expired.
+     *
+     * @param sessionKey - The session identifier to clean up
+     */
+    cleanupSession(sessionKey) {
+        this.sessionStores.delete(sessionKey);
+        // Resolve any waiters before deleting the lock to prevent hung promises
+        const lock = this.sessionBuildLocks.get(sessionKey);
+        if (lock) {
+            lock.resolve();
+            this.sessionBuildLocks.delete(sessionKey);
+        }
+    }
+    /**
+     * Clean up expired sessions from the cache.
+     * Sessions older than SESSION_CACHE_TTL_MS are removed.
+     *
+     * @returns Number of sessions cleaned up
+     */
+    cleanupExpiredSessions() {
+        const now = Date.now();
+        const cutoff = now - ProviderRegistry.SESSION_CACHE_TTL_MS;
+        let cleaned = 0;
+        for (const [key, entry] of this.sessionStores) {
+            if (entry.lastAccess < cutoff) {
+                this.sessionStores.delete(key);
+                // Resolve any waiters before deleting the lock to prevent hung promises
+                const lock = this.sessionBuildLocks.get(key);
+                if (lock) {
+                    lock.resolve();
+                    this.sessionBuildLocks.delete(key);
+                }
+                cleaned++;
+            }
+        }
+        return cleaned;
+    }
     /**
-     * Build provider instance views for different scopes
-     * NOTE: This is currently a stub implementation returning empty maps.
-     * Actual view building logic is planned as part of the session management refactoring.
-     * See the ProviderRegistryInterface TODO for fixing the session type.
+     * Start the background session cleanup timer.
+     * This periodically removes expired sessions from the cache.
      */
-    async buildViews(session) {
+    startSessionCleanup() {
+        // Only start if not already running
+        if (this.sessionCleanupInterval) {
+            return;
+        }
+        this.sessionCleanupInterval = setInterval(() => {
+            const cleaned = this.cleanupExpiredSessions();
+            if (cleaned > 0) {
+                console.debug(`[ProviderRegistry] Cleaned up ${cleaned} expired sessions`);
+            }
+        }, ProviderRegistry.SESSION_CLEANUP_INTERVAL_MS);
+        // Allow the process to exit even if the interval is running
+        // This is important for graceful shutdown in serverless environments
+        if (this.sessionCleanupInterval.unref) {
+            this.sessionCleanupInterval.unref();
+        }
+    }
+    /**
+     * Stop the background session cleanup timer.
+     * Call this when shutting down the server gracefully.
+     */
+    stopSessionCleanup() {
+        if (this.sessionCleanupInterval) {
+            clearInterval(this.sessionCleanupInterval);
+            this.sessionCleanupInterval = null;
+        }
+    }
+    /**
+     * Dispose of the registry, cleaning up all resources.
+     * Call this when the registry/scope is being destroyed to prevent:
+     * - Memory leaks from retained interval handles
+     * - Orphaned session cleanup timers
+     *
+     * @example
+     * ```typescript
+     * // In scope teardown
+     * scope.providers.dispose();
+     * ```
+     */
+    dispose() {
+        this.stopSessionCleanup();
+        // Clear all session stores to help garbage collection
+        this.sessionStores.clear();
+        // Resolve any pending locks to prevent hung promises
+        for (const lock of this.sessionBuildLocks.values()) {
+            lock.resolve();
+        }
+        this.sessionBuildLocks.clear();
+    }
+    /**
+     * Get session cache statistics for monitoring.
+     */
+    getSessionCacheStats() {
+        return {
+            size: this.sessionStores.size,
+            maxSize: ProviderRegistry.MAX_SESSION_CACHE_SIZE,
+            ttlMs: ProviderRegistry.SESSION_CACHE_TTL_MS,
+        };
+    }
+    /* -------------------- Scoped Provider Views -------------------- */
+    /**
+     * Build provider instance views for different scopes.
+     *
+     * This method creates a complete view of providers across all scopes:
+     * - GLOBAL: Returns existing singleton instances (read-only)
+     * - CONTEXT: Builds per-context providers (unified session + request)
+     *
+     * Note: For backwards compatibility, SESSION and REQUEST scopes are normalized
+     * to CONTEXT. The returned views include `session` and `request` aliases that
+     * both point to the `context` store.
+     *
+     * @param sessionKey - Unique context/session identifier for CONTEXT-scoped providers
+     * @param contextProviders - Optional pre-built CONTEXT-scoped providers (e.g., FrontMcpContext)
+     * @returns ProviderViews with global and context provider maps (session/request as aliases)
+     */
+    async buildViews(sessionKey, contextProviders) {
+        // Early validation BEFORE any cache operations or lock acquisition
+        // This prevents cache pollution with invalid session keys
+        session_key_provider_1.SessionKey.validate(sessionKey);
+        // 1. Global providers - return existing singletons
+        const global = this.getAllSingletons();
+        // 2. Context providers - build per-context (unified session+request)
+        // Note: We don't cache context providers because they're per-request.
+        // The unified context model means all non-global providers are fresh per-request.
+        const contextStore = new Map(contextProviders);
+        // Inject SessionKey for backwards compatibility with providers that depend on it
+        // @deprecated - Providers should migrate to using FRONTMCP_CONTEXT instead
+        if (!contextStore.has(session_key_provider_1.SessionKey)) {
+            contextStore.set(session_key_provider_1.SessionKey, new session_key_provider_1.SessionKey(sessionKey));
+        }
+        // Build all CONTEXT-scoped providers (including normalized SESSION/REQUEST)
+        for (const token of this.order) {
+            const rec = this.defs.get(token);
+            if (!rec)
+                continue;
+            // getProviderScope() already normalizes SESSION/REQUEST → CONTEXT
+            if (this.getProviderScope(rec) !== common_1.ProviderScope.CONTEXT)
+                continue;
+            if (contextStore.has(token))
+                continue;
+            await this.buildIntoStoreWithViews(token, rec, contextStore, sessionKey, contextStore, global);
+        }
+        // Return views with backwards-compatible aliases
+        // All three (context, session, request) point to the same map
         return {
-            global: new Map(),
-            session: new Map(),
-            request: new Map(),
+            global,
+            context: contextStore,
+            // Backwards compatibility aliases
+            session: contextStore,
+            request: contextStore,
         };
     }
+    /**
+     * Build a provider into a store, with access to context and global views for dependencies.
+     */
+    async buildIntoStoreWithViews(token, rec, store, scopeKey, contextStore, globalStore) {
+        if (store.has(token))
+            return;
+        try {
+            switch (rec.kind) {
+                case common_1.ProviderKind.VALUE: {
+                    store.set(token, rec.useValue);
+                    return;
+                }
+                case common_1.ProviderKind.FACTORY: {
+                    const deps = this.invocationTokens(token, rec);
+                    const args = [];
+                    for (const d of deps) {
+                        args.push(await this.resolveFromViews(d, contextStore, globalStore, scopeKey));
+                    }
+                    const out = rec.useFactory(...args);
+                    const val = (0, token_utils_1.isPromise)(out)
+                        ? await this.withTimeout(out, this.asyncTimeoutMs, `${(0, token_utils_1.tokenName)(token)}.useFactory(...)`)
+                        : out;
+                    store.set(token, val);
+                    return;
+                }
+                case common_1.ProviderKind.CLASS:
+                case common_1.ProviderKind.CLASS_TOKEN: {
+                    const depsTokens = this.invocationTokens(token, rec);
+                    const deps = [];
+                    for (const d of depsTokens) {
+                        deps.push(await this.resolveFromViews(d, contextStore, globalStore, scopeKey));
+                    }
+                    const klass = rec.kind === common_1.ProviderKind.CLASS ? rec.useClass : rec.provide;
+                    if ((0, metadata_utils_1.hasAsyncWith)(klass)) {
+                        const out = klass.with(...deps);
+                        const val = (0, token_utils_1.isPromise)(out)
+                            ? await this.withTimeout(out, this.asyncTimeoutMs, `${klass.name}.with(...)`)
+                            : out;
+                        store.set(token, val);
+                    }
+                    else {
+                        const instance = new klass(...deps);
+                        const init = instance?.init;
+                        if (typeof init === 'function') {
+                            const ret = init.call(instance);
+                            if ((0, token_utils_1.isPromise)(ret))
+                                await this.withTimeout(ret, this.asyncTimeoutMs, `${klass.name}.init()`);
+                        }
+                        store.set(token, instance);
+                    }
+                    return;
+                }
+            }
+        }
+        catch (e) {
+            const msg = e?.message ?? e;
+            console.error(`Failed constructing (context-scoped):`, msg);
+            throw new Error(`Failed constructing (context-scoped) ${(0, token_utils_1.tokenName)(token)}: ${msg}`);
+        }
+    }
+    /**
+     * Resolve a dependency from the available views (context → global).
+     */
+    async resolveFromViews(token, contextStore, globalStore, scopeKey) {
+        // Check stores in order: context -> global -> instances
+        if (contextStore.has(token))
+            return contextStore.get(token);
+        if (globalStore.has(token))
+            return globalStore.get(token);
+        if (this.instances.has(token))
+            return this.instances.get(token);
+        // Try to build if it's a registered provider
+        const rec = this.defs.get(token);
+        if (rec) {
+            const scope = this.getProviderScope(rec);
+            if (scope === common_1.ProviderScope.GLOBAL) {
+                throw new Error(`GLOBAL dependency ${(0, token_utils_1.tokenName)(token)} is not instantiated`);
+            }
+            else {
+                // CONTEXT scope - build into context store
+                await this.buildIntoStoreWithViews(token, rec, contextStore, scopeKey, contextStore, globalStore);
+                return contextStore.get(token);
+            }
+        }
+        // Check parent hierarchy
+        const up = this.lookupDefInHierarchy(token);
+        if (up) {
+            const sc = up.registry.getProviderScope(up.rec);
+            if (sc === common_1.ProviderScope.GLOBAL) {
+                const v = up.registry.instances.get(token);
+                if (v !== undefined)
+                    return v;
+                throw new Error(`GLOBAL dependency ${(0, token_utils_1.tokenName)(token)} is not instantiated in parent`);
+            }
+        }
+        throw new Error(`Cannot resolve dependency ${(0, token_utils_1.tokenName)(token)} from views`);
+    }
+    /**
+     * Get a provider from the given views, checking context → global.
+     *
+     * @param token - The provider token to look up
+     * @param views - The provider views to search
+     * @returns The provider instance
+     * @throws Error if provider not found in any view
+     */
+    getScoped(token, views) {
+        // Check context first (unified session+request store)
+        if (views.context.has(token))
+            return views.context.get(token);
+        if (views.global.has(token))
+            return views.global.get(token);
+        // Check instances as fallback for global providers
+        if (this.instances.has(token))
+            return this.instances.get(token);
+        throw new Error(`Provider ${(0, token_utils_1.tokenName)(token)} not found in views. Ensure it was built via buildViews().`);
+    }
 }
 exports.default = ProviderRegistry;
 //# sourceMappingURL=provider.registry.js.map