@vybestack/llxprt-code-core 0.4.8 → 0.5.0-nightly.251102.f115237d

package/dist/src/providers/ProviderManager.js

@@ -7,11 +7,42 @@
 import { LoggingProviderWrapper } from './LoggingProviderWrapper.js';
 import { logProviderSwitch, logProviderCapability, } from '../telemetry/loggers.js';
 import { ProviderSwitchEvent, ProviderCapabilityEvent, } from '../telemetry/types.js';
-import { getSettingsService } from '../settings/settingsServiceInstance.js';
+import { getActiveProviderRuntimeContext, } from '../runtime/providerRuntimeContext.js';
+import { MissingProviderRuntimeError, ProviderRuntimeNormalizationError, } from './errors.js';
+import { createRuntimeInvocationContext } from '../runtime/RuntimeInvocationContext.js';
+const PROVIDER_CAPABILITY_HINTS = {
+    gemini: {
+        hasModelSelection: true,
+        hasApiKeyConfig: true,
+        hasBaseUrlConfig: false,
+    },
+    openai: {
+        hasModelSelection: true,
+        hasApiKeyConfig: true,
+        hasBaseUrlConfig: true,
+    },
+    'openai-responses': {
+        hasModelSelection: false,
+        hasApiKeyConfig: true,
+        hasBaseUrlConfig: true,
+    },
+    anthropic: {
+        hasModelSelection: true,
+        hasApiKeyConfig: true,
+        hasBaseUrlConfig: true,
+    },
+};
 export class ProviderManager {
     providers;
     serverToolsProvider;
     config;
+    /**
+     * @plan PLAN-20250218-STATELESSPROVIDER.P05
+     * @requirement REQ-SP-001
+     * @pseudocode provider-invocation.md lines 8-15
+     */
+    settingsService;
+    runtime;
     providerCapabilities = new Map();
     sessionTokenUsage = {
         input: 0,
@@ -21,19 +52,86 @@ export class ProviderManager {
         thought: 0,
         total: 0,
     };
-    constructor() {
+    constructor(init) {
+        const resolved = this.resolveInit(init);
         this.providers = new Map();
         this.serverToolsProvider = null;
+        this.settingsService = resolved.settingsService;
+        this.config = resolved.config ?? this.config;
+        this.runtime = resolved.runtime;
+    }
+    /**
+     * @plan PLAN-20250218-STATELESSPROVIDER.P05
+     * @requirement REQ-SP-001
+     * @pseudocode provider-invocation.md lines 8-15
+     * @plan:PLAN-20251018-STATELESSPROVIDER2.P03
+     * @requirement:REQ-SP2-002
+     * @pseudocode multi-runtime-baseline.md lines 3-4
+     */
+    resolveInit(init) {
+        let fallback = null;
+        const ensureFallback = () => {
+            if (!fallback) {
+                fallback = getActiveProviderRuntimeContext();
+            }
+            return fallback;
+        };
+        if (!init) {
+            const resolved = ensureFallback();
+            return {
+                settingsService: resolved.settingsService,
+                config: resolved.config,
+                runtime: resolved,
+            };
+        }
+        if (typeof init === 'object' &&
+            init !== null &&
+            'settingsService' in init &&
+            ('runtimeId' in init || 'metadata' in init)) {
+            const context = init;
+            return {
+                settingsService: context.settingsService,
+                config: context.config,
+                runtime: context,
+            };
+        }
+        const initObj = init;
+        const runtime = initObj.runtime;
+        let settingsService = initObj.settingsService ?? runtime?.settingsService ?? null;
+        let config = initObj.config ?? runtime?.config ?? undefined;
+        if (!settingsService || !config) {
+            const resolved = ensureFallback();
+            settingsService = settingsService ?? resolved.settingsService;
+            config = config ?? resolved.config;
+            return {
+                settingsService,
+                config,
+                runtime: runtime ?? resolved,
+            };
+        }
+        return {
+            settingsService,
+            config,
+            runtime,
+        };
     }
     setConfig(config) {
         const oldLoggingEnabled = this.config?.getConversationLoggingEnabled() ?? false;
         const newLoggingEnabled = config.getConversationLoggingEnabled();
         this.config = config;
+        this.runtime = this.runtime
+            ? { ...this.runtime, config }
+            : { settingsService: this.settingsService, config };
         // If logging state changed, update provider wrapping
         if (oldLoggingEnabled !== newLoggingEnabled) {
             this.updateProviderWrapping();
         }
     }
+    /**
+     * @plan PLAN-20251018-STATELESSPROVIDER2.P06
+     * @requirement REQ-SP2-001
+     * @pseudocode base-provider-call-contract.md lines 3-5
+     */
     updateProviderWrapping() {
         // Re-wrap all providers (ALWAYS wrap for token tracking)
         const providers = new Map(this.providers);
@@ -43,13 +141,13 @@ export class ProviderManager {
             if ('wrappedProvider' in provider && provider.wrappedProvider) {
                 baseProvider = provider.wrappedProvider;
             }
+            this.syncProviderRuntime(baseProvider);
             // ALWAYS wrap with LoggingProviderWrapper for token tracking
             let finalProvider = baseProvider;
             if (this.config) {
-                baseProvider.setConfig?.(this.config);
                 finalProvider = new LoggingProviderWrapper(baseProvider, this.config);
-                finalProvider.setConfig?.(this.config);
             }
+            this.syncProviderRuntime(finalProvider);
             this.providers.set(name, finalProvider);
             // Update server tools provider reference if needed
             if (this.serverToolsProvider && this.serverToolsProvider.name === name) {
@@ -57,17 +155,261 @@ export class ProviderManager {
             }
         }
     }
-    registerProvider(provider) {
-        if (this.config) {
-            provider.setConfig?.(this.config);
+    /**
+     * @plan PLAN-20250218-STATELESSPROVIDER.P05
+     * @requirement REQ-SP-001
+     * @pseudocode provider-invocation.md lines 8-15
+     * @plan:PLAN-20251023-STATELESS-HARDENING.P05
+     * @requirement:REQ-SP4-001
+     * @pseudocode provider-runtime-handling.md lines 10-15
+     */
+    syncProviderRuntime(provider) {
+        const runtimeAware = provider;
+        runtimeAware.setRuntimeSettingsService?.(this.settingsService);
+        if (this.config && runtimeAware.setConfig) {
+            runtimeAware.setConfig(this.config);
+        }
+        if (runtimeAware.setRuntimeContextResolver &&
+            typeof runtimeAware.setRuntimeContextResolver === 'function') {
+            runtimeAware.setRuntimeContextResolver(() => this.snapshotRuntimeContext('ProviderManager.syncProviderRuntime'));
+        }
+        if (runtimeAware.setOptionsNormalizer &&
+            typeof runtimeAware.setOptionsNormalizer === 'function') {
+            runtimeAware.setOptionsNormalizer((options, providerName) => this.normalizeRuntimeInputs(options, providerName));
+        }
+    }
+    /**
+     * @plan:PLAN-20251023-STATELESS-HARDENING.P05
+     * @requirement:REQ-SP4-001
+     * @pseudocode provider-runtime-handling.md lines 10-15
+     */
+    snapshotRuntimeContext(source) {
+        const baseRuntime = this.runtime ?? {
+            settingsService: this.settingsService,
+            config: this.config,
+            runtimeId: 'provider-manager.default-runtime',
+            metadata: { source: 'ProviderManager', requirement: 'REQ-SP4-001' },
+        };
+        if (!this.runtime) {
+            this.runtime = baseRuntime;
+        }
+        else if (!this.runtime.config && baseRuntime.config) {
+            this.runtime = { ...this.runtime, config: baseRuntime.config };
+        }
+        const settingsService = baseRuntime.settingsService;
+        if (!settingsService) {
+            throw new MissingProviderRuntimeError({
+                providerKey: 'ProviderManager',
+                missingFields: ['settings'],
+                stage: source,
+                metadata: {
+                    requirement: 'REQ-SP4-001',
+                    hint: 'ProviderManager requires a SettingsService to construct runtime contexts.',
+                },
+            });
+        }
+        const config = baseRuntime.config ?? this.config;
+        if (!config) {
+            throw new MissingProviderRuntimeError({
+                providerKey: 'ProviderManager',
+                missingFields: ['config'],
+                stage: source,
+                metadata: {
+                    requirement: 'REQ-SP4-001',
+                    hint: 'Call ProviderManager.setConfig before invoking providers.',
+                },
+            });
+        }
+        const baseMetadata = baseRuntime.metadata ?? {};
+        const callMetadata = {
+            ...baseMetadata,
+            source,
+            requirement: 'REQ-SP4-001',
+            generatedAt: new Date().toISOString(),
+        };
+        const baseId = baseRuntime.runtimeId;
+        const callRuntimeId = typeof baseId === 'string' && baseId.trim() !== ''
+            ? `${baseId}:${Math.random().toString(36).slice(2, 10)}`
+            : `provider-manager:${source}:${Date.now().toString(36)}`;
+        return {
+            settingsService,
+            config,
+            runtimeId: callRuntimeId,
+            metadata: callMetadata,
+        };
+    }
+    /**
+     * @plan:PLAN-20251023-STATELESS-HARDENING.P08
+     * @requirement:REQ-SP4-002
+     * @requirement:REQ-SP4-003
+     * @requirement:REQ-SP4-004
+     * @requirement:REQ-SP4-005
+     * @pseudocode provider-runtime-handling.md lines 10-16
+     *
+     * Normalize runtime inputs per call - no stored settings/config fallbacks.
+     * This method enforces that all runtime context is provided per-call and that
+     * providers cannot rely on stored state.
+     */
+    normalizeRuntimeInputs(rawOptions, providerName) {
+        const runtimeId = rawOptions.runtime?.runtimeId || 'unknown';
+        const targetProvider = providerName || this.getActiveProviderName();
+        // REQ-SP4-002: Check for required settings service and config in runtime context
+        const settingsService = rawOptions.settings ?? rawOptions.runtime?.settingsService;
+        const config = rawOptions.config ?? rawOptions.runtime?.config;
+        if (!settingsService) {
+            throw new ProviderRuntimeNormalizationError({
+                providerKey: 'ProviderManager',
+                message: 'ProviderManager requires call-scoped settings; legacy provider state is disabled.',
+                requirement: 'REQ-SP4-002',
+                runtimeId,
+                stage: 'normalizeRuntimeInputs',
+                metadata: {
+                    hint: 'SettingsService must be provided in options.settings or runtime.settingsService',
+                },
+            });
+        }
+        if (!config) {
+            throw new ProviderRuntimeNormalizationError({
+                providerKey: 'ProviderManager',
+                message: 'ProviderManager requires call-scoped config; legacy provider state is disabled.',
+                requirement: 'REQ-SP4-002',
+                runtimeId,
+                stage: 'normalizeRuntimeInputs',
+                metadata: {
+                    hint: 'Config must be provided in options.config or runtime.config',
+                },
+            });
+        }
+        // REQ-SP4-003: Compose normalized.resolved with runtime helpers
+        const providerSettings = settingsService.getProviderSettings(targetProvider);
+        const providerInstance = this.providers.get(targetProvider);
+        const resolved = {
+            model: rawOptions.resolved?.model ??
+                config.getModel?.() ??
+                providerSettings.model ??
+                (providerInstance
+                    ? this.getStoredModelName(providerInstance)
+                    : undefined),
+            baseURL: rawOptions.resolved?.baseURL ??
+                providerSettings.baseURL,
+            authToken: rawOptions.resolved?.authToken ??
+                providerSettings.apiKey,
+            telemetry: {
+                ...rawOptions.resolved?.telemetry,
+                runtimeId,
+                normalizedAt: new Date().toISOString(),
+                provider: targetProvider,
+            },
+        };
+        // REQ-SP4-003: Validate required fields in resolved options
+        const missingFields = [];
+        if (!resolved.model)
+            missingFields.push('model');
+        // Note: Gemini and some providers don't require baseURL/authToken in all configurations
+        const baseUrlOptionalProviders = new Set([
+            'gemini',
+            'openai',
+            'openai-responses',
+            'anthropic',
+        ]);
+        if (!resolved.baseURL && !baseUrlOptionalProviders.has(targetProvider)) {
+            missingFields.push('baseURL');
+        }
+        if (!resolved.authToken && targetProvider !== 'gemini') {
+            // Check if provider can resolve auth lazily (e.g., via OAuth)
+            // If the provider has getAuthToken(), it can handle its own auth precedence
+            const providerInstance = this.providers.get(targetProvider);
+            let actualProvider = providerInstance;
+            if (providerInstance && 'wrappedProvider' in providerInstance) {
+                actualProvider = providerInstance
+                    .wrappedProvider;
+            }
+            const canResolveAuth = actualProvider &&
+                'getAuthToken' in actualProvider &&
+                typeof actualProvider.getAuthToken === 'function';
+            if (!canResolveAuth) {
+                // Only fail for providers without lazy auth resolution capability
+                missingFields.push('authToken');
+            }
+            // Otherwise let the provider run its multi-modal precedence chain:
+            // 1. Manual key (from /key)
+            // 2. Keyfile (from /keyfile)
+            // 3. Environment variables
+            // 4. OAuth token (if enabled)
+        }
+        if (missingFields.length > 0) {
+            throw new ProviderRuntimeNormalizationError({
+                providerKey: 'ProviderManager',
+                message: `Incomplete runtime resolution (${missingFields.join(', ')}) for runtimeId=${runtimeId}`,
+                requirement: 'REQ-SP4-003',
+                runtimeId,
+                stage: 'normalizeRuntimeInputs',
+                metadata: { missingFields, provider: targetProvider },
+            });
         }
+        // REQ-SP4-005: Ensure normalized.userMemory and metadata derive from runtime context
+        const userMemory = rawOptions.userMemory ?? config.getUserMemory?.();
+        const metadata = {
+            ...rawOptions.metadata,
+            ...rawOptions.runtime?.metadata,
+            _normalized: true,
+            _normalizationTime: new Date().toISOString(),
+            _runtimeId: runtimeId,
+            _provider: targetProvider,
+        };
+        const normalizedRuntime = {
+            ...(rawOptions.runtime ?? {}),
+            settingsService,
+            config,
+            runtimeId,
+            metadata,
+        };
+        const userMemorySnapshot = typeof userMemory === 'string' ? userMemory : config.getUserMemory?.();
+        const invocation = rawOptions.invocation ??
+            createRuntimeInvocationContext({
+                runtime: normalizedRuntime,
+                settings: settingsService,
+                providerName: targetProvider,
+                ephemeralsSnapshot: this.buildEphemeralsSnapshot(settingsService, targetProvider),
+                telemetry: resolved.telemetry,
+                metadata,
+                userMemory: userMemorySnapshot ?? undefined,
+                fallbackRuntimeId: runtimeId,
+            });
+        return {
+            ...rawOptions,
+            settings: settingsService,
+            config,
+            runtime: normalizedRuntime,
+            resolved,
+            userMemory,
+            metadata,
+            invocation,
+        };
+    }
+    buildEphemeralsSnapshot(settingsService, providerName) {
+        const globalEphemerals = settingsService.getAllGlobalSettings();
+        const providerEphemerals = settingsService.getProviderSettings(providerName);
+        const snapshot = {
+            ...globalEphemerals,
+        };
+        snapshot[providerName] = { ...providerEphemerals };
+        return snapshot;
+    }
+    /**
+     * @plan PLAN-20251018-STATELESSPROVIDER2.P06
+     * @requirement REQ-SP2-001
+     * @pseudocode base-provider-call-contract.md lines 3-5
+     */
+    registerProvider(provider) {
+        this.syncProviderRuntime(provider);
         // ALWAYS wrap provider to enable token tracking
         // (LoggingProviderWrapper handles both token tracking AND conversation logging)
         let finalProvider = provider;
         if (this.config) {
             finalProvider = new LoggingProviderWrapper(provider, this.config);
-            finalProvider.setConfig?.(this.config);
         }
+        this.syncProviderRuntime(finalProvider);
         this.providers.set(provider.name, finalProvider);
         // Capture provider capabilities
         const capabilities = this.captureProviderCapabilities(provider);
@@ -78,10 +420,9 @@ export class ProviderManager {
             logProviderCapability(this.config, new ProviderCapabilityEvent(provider.name, capabilities, context));
         }
         // If this is the default provider and no provider is active, set it as active
-        const settingsService = getSettingsService();
-        const currentActiveProvider = settingsService.get('activeProvider');
+        const currentActiveProvider = this.settingsService.get('activeProvider');
         if (provider.isDefault && !currentActiveProvider) {
-            settingsService.set('activeProvider', provider.name);
+            this.settingsService.set('activeProvider', provider.name);
         }
         // If registering Gemini and we don't have a serverToolsProvider, use it
         if (provider.name === 'gemini' && !this.serverToolsProvider) {
@@ -92,22 +433,26 @@ export class ProviderManager {
             this.serverToolsProvider = provider;
         }
     }
+    /**
+     * @plan PLAN-20251018-STATELESSPROVIDER2.P06
+     * @requirement REQ-SP2-001
+     * @pseudocode base-provider-call-contract.md lines 3-5
+     */
     setActiveProvider(name) {
         if (!this.providers.has(name)) {
             throw new Error('Provider not found');
         }
         // Store reference to the current active provider before switching
-        const settingsService = getSettingsService();
-        const previousProviderName = settingsService.get('activeProvider') || '';
+        const previousProviderName = this.settingsService.get('activeProvider') || '';
         // Only clear state from the provider we're switching FROM
         // BUT never clear the serverToolsProvider's state
         if (previousProviderName && previousProviderName !== name) {
             const previousProvider = this.providers.get(previousProviderName);
-            if (previousProvider && previousProvider.clearState) {
-                // Don't clear state if this provider is also the serverToolsProvider
-                if (previousProvider !== this.serverToolsProvider) {
-                    previousProvider.clearState();
-                }
+            if (previousProvider &&
+                previousProvider !== this.serverToolsProvider &&
+                'clearState' in previousProvider) {
+                const candidate = previousProvider;
+                candidate.clearState?.();
             }
         }
         // Log provider switch if conversation logging enabled
@@ -117,7 +462,7 @@ export class ProviderManager {
             logProviderSwitch(this.config, new ProviderSwitchEvent(previousProviderName, name, this.generateConversationId(), this.isContextPreserved(previousProviderName, name)));
         }
         // Update SettingsService as the single source of truth
-        settingsService.set('activeProvider', name);
+        this.settingsService.set('activeProvider', name);
         // If switching to Gemini, use it as both active and serverTools provider
         // BUT only if we don't already have a Gemini serverToolsProvider with auth state
         if (name === 'gemini') {
@@ -134,16 +479,36 @@ export class ProviderManager {
         }
     }
     clearActiveProvider() {
-        const settingsService = getSettingsService();
-        settingsService.set('activeProvider', '');
+        this.settingsService.set('activeProvider', '');
     }
     getActiveProvider() {
-        const settingsService = getSettingsService();
-        const activeProviderName = settingsService.get('activeProvider') || '';
-        if (!activeProviderName) {
+        const activeProviderName = this.settingsService.get('activeProvider') || '';
+        let resolvedName = activeProviderName;
+        if (!resolvedName) {
+            const preferredFromConfig = this.config?.getProvider?.();
+            if (preferredFromConfig && this.providers.has(preferredFromConfig)) {
+                resolvedName = preferredFromConfig;
+            }
+            else if (this.providers.has('openai')) {
+                resolvedName = 'openai';
+            }
+            else {
+                const firstProvider = this.providers.keys().next();
+                resolvedName = firstProvider.done ? '' : firstProvider.value;
+            }
+            if (resolvedName) {
+                try {
+                    this.setActiveProvider(resolvedName);
+                }
+                catch (error) {
+                    throw new Error(`Unable to set default provider '${resolvedName}': ${String(error)}`);
+                }
+            }
+        }
+        if (!resolvedName) {
             throw new Error('No active provider set');
         }
-        const provider = this.providers.get(activeProviderName);
+        const provider = this.providers.get(resolvedName);
         if (!provider) {
             throw new Error('Active provider not found');
         }
@@ -178,12 +543,10 @@ export class ProviderManager {
         return this.providers.get(name);
     }
     getActiveProviderName() {
-        const settingsService = getSettingsService();
-        return settingsService.get('activeProvider') || '';
+        return this.settingsService.get('activeProvider') || '';
     }
     hasActiveProvider() {
-        const settingsService = getSettingsService();
-        const activeProviderName = settingsService.get('activeProvider') || '';
+        const activeProviderName = this.settingsService.get('activeProvider') || '';
         return activeProviderName !== '' && this.providers.has(activeProviderName);
     }
     getServerToolsProvider() {
@@ -218,39 +581,55 @@ export class ProviderManager {
         // Context is considered preserved if compatibility is high
         return capabilityScore > 0.7;
     }
+    getStoredModelName(provider) {
+        const providerSettings = this.settingsService.getProviderSettings(provider.name);
+        const storedModel = providerSettings.model;
+        if (storedModel && typeof storedModel === 'string' && storedModel.trim()) {
+            return storedModel;
+        }
+        if (this.config &&
+            typeof this.config.getProvider === 'function' &&
+            this.config.getProvider() === provider.name) {
+            const configModel = this.config.getModel();
+            if (configModel) {
+                return configModel;
+            }
+        }
+        return provider.getDefaultModel?.() ?? '';
+    }
     captureProviderCapabilities(provider) {
+        const hints = PROVIDER_CAPABILITY_HINTS[provider.name] ?? {};
         return {
             supportsStreaming: true, // All current providers support streaming
             supportsTools: provider.getServerTools().length > 0,
             supportsVision: this.detectVisionSupport(provider),
             maxTokens: this.getProviderMaxTokens(provider),
             supportedFormats: this.getSupportedToolFormats(provider),
-            hasModelSelection: typeof provider.setModel === 'function',
-            hasApiKeyConfig: typeof provider.setApiKey === 'function',
-            hasBaseUrlConfig: typeof provider.setBaseUrl === 'function',
+            hasModelSelection: hints.hasModelSelection ?? true,
+            hasApiKeyConfig: hints.hasApiKeyConfig ?? true,
+            hasBaseUrlConfig: hints.hasBaseUrlConfig ?? true,
             supportsPaidMode: typeof provider.isPaidMode === 'function',
         };
     }
     detectVisionSupport(provider) {
         // Provider-specific vision detection logic
+        const model = this.getStoredModelName(provider).toLowerCase();
         switch (provider.name) {
             case 'gemini': {
                 return true;
             }
             case 'openai': {
-                const model = provider.getCurrentModel?.() || '';
                 return model.includes('vision') || model.includes('gpt-4');
             }
             case 'anthropic': {
-                const claudeModel = provider.getCurrentModel?.() || '';
-                return claudeModel.includes('claude-3');
+                return model.includes('claude-3');
             }
             default:
                 return false;
         }
     }
     getProviderMaxTokens(provider) {
-        const model = provider.getCurrentModel?.() || '';
+        const model = this.getStoredModelName(provider).toLowerCase();
         switch (provider.name) {
             case 'gemini':
                 if (model.includes('pro'))
@@ -285,10 +664,12 @@ export class ProviderManager {
         }
     }
     createProviderContext(provider, capabilities) {
+        const providerSettings = this.settingsService.getProviderSettings(provider.name);
+        const toolFormatSetting = providerSettings.toolFormat ?? 'auto';
         return {
             providerName: provider.name,
-            currentModel: provider.getCurrentModel?.() || 'unknown',
-            toolFormat: provider.getToolFormat?.() || 'unknown',
+            currentModel: this.getStoredModelName(provider) || 'unknown',
+            toolFormat: toolFormatSetting,
             isPaidMode: provider.isPaidMode?.() || false,
             capabilities,
             sessionStartTime: Date.now(),
@@ -388,10 +769,81 @@ export class ProviderManager {
         // Conversation ID is now managed by the logging system
     }
     getProviderCapabilities(providerName) {
-        const settingsService = getSettingsService();
-        const name = providerName || settingsService.get('activeProvider') || '';
+        const name = providerName ||
+            this.settingsService.get('activeProvider') ||
+            '';
         return this.providerCapabilities.get(name);
     }
+    /* @plan:PLAN-20251023-STATELESS-HARDENING.P06 */
+    /* @requirement:REQ-SP4-004 */
+    prepareStatelessProviderInvocation(context) {
+        const stage = 'ProviderManager.prepareStatelessProviderInvocation';
+        const runtimeContext = context ?? this.runtime;
+        if (!runtimeContext) {
+            throw new MissingProviderRuntimeError({
+                providerKey: 'ProviderManager',
+                missingFields: ['runtime'],
+                requirement: 'REQ-SP4-004',
+                stage,
+                metadata: {
+                    hint: 'Register CLI runtime context before invoking providers.',
+                },
+            });
+        }
+        if (!runtimeContext.settingsService) {
+            throw new MissingProviderRuntimeError({
+                providerKey: 'ProviderManager',
+                missingFields: ['settings'],
+                requirement: 'REQ-SP4-004',
+                stage,
+                metadata: {
+                    runtimeId: runtimeContext.runtimeId,
+                    hint: 'ProviderManager requires a SettingsService for stateless invocation.',
+                },
+            });
+        }
+        const resolvedConfig = runtimeContext.config ?? this.config;
+        if (!resolvedConfig) {
+            throw new MissingProviderRuntimeError({
+                providerKey: 'ProviderManager',
+                missingFields: ['config'],
+                requirement: 'REQ-SP4-004',
+                stage,
+                metadata: {
+                    runtimeId: runtimeContext.runtimeId,
+                    hint: 'ProviderManager requires Config before stateless invocation.',
+                },
+            });
+        }
+        const statelessMetadata = {
+            ...(runtimeContext.metadata ?? {}),
+            statelessHardening: 'strict',
+            statelessProviderMode: 'strict',
+            statelessGuards: true,
+            statelessMode: 'strict',
+            requirement: 'REQ-SP4-004',
+            source: stage,
+            preparedAt: new Date().toISOString(),
+        };
+        this.runtime = {
+            ...runtimeContext,
+            settingsService: runtimeContext.settingsService,
+            config: resolvedConfig,
+            metadata: statelessMetadata,
+        };
+        this.settingsService = runtimeContext.settingsService;
+        this.config = resolvedConfig;
+        for (const provider of this.providers.values()) {
+            this.attachStatelessRuntimeMetadata(provider, statelessMetadata);
+        }
+    }
+    attachStatelessRuntimeMetadata(provider, metadata) {
+        const statelessAware = provider;
+        statelessAware.attachStatelessRuntimeMetadata?.(metadata);
+        if (statelessAware.wrappedProvider) {
+            this.attachStatelessRuntimeMetadata(statelessAware.wrappedProvider, metadata);
+        }
+    }
     compareProviders(provider1, provider2) {
         const cap1 = this.providerCapabilities.get(provider1);
         const cap2 = this.providerCapabilities.get(provider2);