fix(runtime): defer provider resolution until agent use (#242)

Author: AkiKurisu

specs/architecture/runtime-module-boundaries.md

@@ -120,7 +120,7 @@ open databases, bind ports, start processes, or run background loops.
 The owning Generic Host controls the lifecycle:
 
 1. Registration adds Runtime, selected providers, optional features, and optional AppServer.
-2. Host startup validates configuration and required capabilities.
+2. Host startup validates provider-independent configuration and required host capabilities.
 3. Runtime provisions the workspace, initializes persistent services, starts owned background
    services, and becomes ready.
 4. Requests use the single Core service graph owned by that host.
@@ -131,7 +131,11 @@ A startup failure never exposes a partially ready Runtime. Resources acquired be
 released through the host startup-failure path. Stop and disposal are safe when invoked through the
 normal Generic Host lifecycle.
 
-Missing providers, invalid workspace configuration, and conflicting registrations fail before the
+Missing model providers, model preferences, and provider implementations are validated when an
+operation first builds an agent or otherwise requires model access. A Runtime without a resolvable
+model remains available for provider-independent work such as config-schema inspection, agent
+profile, skill, and command discovery, thread indexing, and recovery export. Invalid
+provider-independent workspace configuration and conflicting registrations still fail before the
 Runtime accepts work. Transport failures follow the AppServer protocol contract and do not expose
 internal exception types as wire contracts.
 

src/DotCraft.Core/Agents/Runtime/AgentFactory.cs

@@ -29,7 +29,7 @@ namespace DotCraft.Agents;
 public sealed class AgentFactory : IAsyncDisposable
 {
     private readonly AppConfig _config;
-    private readonly IChatClient _chatClient;
+    private readonly IChatClient? _chatClientOverride;
     private readonly ConcurrentDictionary<string, TokenTracker> _tokenTrackers = new();
     private readonly ConcurrentDictionary<CompactionPipelineKey, CompactionPipeline> _compactionPipelines = new();
     private readonly TraceCollector? _traceCollector;
@@ -42,6 +42,8 @@ public sealed class AgentFactory : IAsyncDisposable
     private readonly IRemoteToolHostClient? _remoteToolHostClient;
     private readonly ChatClientRegistry _chatClientRegistry;
     private readonly IChatClient? _compactionChatClientOverride;
+    private CompactionPipeline? _defaultCompactionPipeline;
+    private IMemoryConsolidator? _defaultConsolidator;
     private static readonly ConcurrentDictionary<MethodInfo, bool> StreamArgumentsOptOutCache = new();
     private readonly CustomCommandLoader? _customCommandLoader;
     private readonly PlanStore? _planStore;
@@ -92,6 +94,7 @@ public AgentFactory(
         _onConsolidatorStatus = onConsolidatorStatus;
         _memoryConsolidatorOverride = memoryConsolidator;
         _compactionChatClientOverride = compactionChatClient;
+        _chatClientOverride = chatClient;
         _toolDispatcher = toolDispatcher ?? new ToolDispatcher();
         _remoteToolHostClient = remoteToolHostClient;
         _loggerFactory = loggerFactory ?? NullLoggerFactory.Instance;
@@ -101,67 +104,11 @@ public AgentFactory(
                               ?? runtimeContext?.ChatClientRegistry
                               ?? new ChatClientRegistry(new ModelProviderRegistry([]));
 
-        var mainRuntime = _chatClientRegistry.ResolveMainRuntime(config);
-        var mainModel = mainRuntime.Model;
-        var mainCompactionConfig = ModelCatalog.ResolveCompactionConfig(config, mainModel);
-        _chatClient = chatClient ?? _chatClientRegistry.GetChatClient(mainRuntime);
-        var consolidationRuntime = _chatClientRegistry.ResolveConsolidationRuntime(
-            config,
-            mainRuntime.ProviderId,
-            mainModel);
-        var maintenanceMainChatClient = ProviderChatClientAdapters.CreateRequestAdaptedClient(
-            _chatClient,
-            config,
-            mainRuntime,
-            useDefaultReasoning: false);
-        var consolidationChatClient = chatClient ?? _chatClientRegistry.GetChatClient(consolidationRuntime);
-        var legacyConsolidator = new MemoryConsolidator(
-            ProviderChatClientAdapters.CreateRequestAdaptedClient(
-                consolidationChatClient,
-                config,
-                consolidationRuntime,
-                useDefaultReasoning: false),
-            memoryStore,
-            onConsolidatorStatus);
-        Consolidator = _memoryConsolidatorOverride
-            ?? new MemoryForkConsolidator(
-                new MaintenanceForkRunner(
-                    maintenanceMainChatClient,
-                    cacheOptions: new MaintenanceForkCacheOptions(
-                        mainRuntime.Protocol,
-                        _config.PromptCaching,
-                        mainModel)),
-                legacyConsolidator,
-                memoryStore,
-                mainModel,
-                consolidationRuntime.Model,
-                mainCompactionConfig.BlockingLimit(),
-                workspacePath);
-
-        CompactionPipeline = new CompactionPipeline(
-            mainCompactionConfig,
-            ProviderChatClientAdapters.CreateRequestAdaptedClient(
-                _compactionChatClientOverride ?? _chatClient,
-                config,
-                mainRuntime,
-                useDefaultReasoning: false),
-            _traceCollector,
-            new MaintenanceForkCacheOptions(
-                mainRuntime.Protocol,
-                _config.PromptCaching,
-                mainModel),
-            runtimeContext?.Contributions,
-            logger: _logger);
-
-        // Build the source-neutral runtime context.
         _runtimeContext = runtimeContext ?? new AgentRuntimeContext
         {
             Config = config,
-            ChatClient = _chatClient,
+            ChatClient = chatClient,
             ChatClientRegistry = _chatClientRegistry,
-            EffectiveProviderId = mainRuntime.ProviderId,
-            EffectiveProviderProtocol = mainRuntime.Protocol,
-            EffectiveMainModel = mainModel,
             WorkspacePath = workspacePath,
             BotPath = dotcraftPath,
             MemoryStore = memoryStore,
@@ -260,7 +207,8 @@ await source.ReleaseRetiredThreadResourcesAsync(threadId, cancellationToken)
     /// <summary>
     /// Gets the layered context-compaction pipeline (auto / reactive / manual).
     /// </summary>
-    public CompactionPipeline CompactionPipeline { get; }
+    public CompactionPipeline CompactionPipeline =>
+        _defaultCompactionPipeline ??= GetCompactionPipeline(string.Empty);
 
     /// <summary>
     /// Gets the context-compaction pipeline for a thread's effective main model.
@@ -289,6 +237,7 @@ public CompactionPipeline GetCompactionPipeline(
             var (factory, resolvedConfig, config) = state;
             var runtime = pipelineKey.ToRuntime();
             var baseChatClient = factory._compactionChatClientOverride
+                ?? factory._chatClientOverride
                 ?? factory._chatClientRegistry.GetChatClient(runtime);
             return new CompactionPipeline(
                 resolvedConfig,
@@ -327,7 +276,7 @@ public CompactionPipeline GetCompactionPipeline(
             mainRuntime.Model);
         var fallback = new MemoryConsolidator(
             ProviderChatClientAdapters.CreateRequestAdaptedClient(
-                _chatClientRegistry.GetChatClient(consolidationRuntime),
+                _chatClientOverride ?? _chatClientRegistry.GetChatClient(consolidationRuntime),
                 config,
                 consolidationRuntime,
                 useDefaultReasoning: false),
@@ -337,7 +286,7 @@ public CompactionPipeline GetCompactionPipeline(
         return new MemoryForkConsolidator(
             new MaintenanceForkRunner(
                 ProviderChatClientAdapters.CreateRequestAdaptedClient(
-                    _chatClientRegistry.GetChatClient(mainRuntime),
+                    _chatClientOverride ?? _chatClientRegistry.GetChatClient(mainRuntime),
                     config,
                     mainRuntime,
                     useDefaultReasoning: false),
@@ -362,7 +311,8 @@ public CompactionPipeline GetCompactionPipeline(
     /// Session Core drives consolidation independently from context
     /// compaction, using completed thread history as input.
     /// </summary>
-    public IMemoryConsolidator? Consolidator { get; }
+    public IMemoryConsolidator? Consolidator =>
+        _defaultConsolidator ??= CreateConsolidatorForRuntime(_config, null, null);
 
     /// <summary>
     /// Gets or creates a token tracker for the specified session.
@@ -386,7 +336,7 @@ public TokenTracker GetOrCreateTokenTracker(string sessionKey)
     public void RemoveTokenTracker(string sessionKey)
     {
         _tokenTrackers.TryRemove(sessionKey, out _);
-        CompactionPipeline.Forget(sessionKey);
+        _defaultCompactionPipeline?.Forget(sessionKey);
         foreach (var pair in _compactionPipelines.Where(pair =>
                      string.Equals(pair.Key.SessionKey, sessionKey, StringComparison.Ordinal)).ToArray())
         {
@@ -713,7 +663,10 @@ when string.Equals(
                 }
             }
         };
-        var chatClientBuilder = new ChatClientBuilder(ctx.ChatClient);
+        var baseChatClient = ctx.ChatClient
+            ?? _chatClientOverride
+            ?? _chatClientRegistry.GetChatClient(runtime);
+        var chatClientBuilder = new ChatClientBuilder(baseChatClient);
         var isNativeSubAgent = ctx.CurrentThreadSource?.SubAgent is { } subAgentSource
             && string.Equals(
                 subAgentSource.RuntimeType,

src/DotCraft.Core/Agents/Runtime/AgentRuntimeContext.cs

@@ -31,7 +31,7 @@ public AgentRuntimeContext()
 
     /// <summary>
     /// Copies every member of <paramref name="source"/> so a clone site only states its deltas and cannot
-    /// silently drop one. Lazily defaulted members are materialized from the source as it is read.
+    /// silently drop one. Unresolved model runtime values remain unresolved in the clone.
     /// </summary>
     [SetsRequiredMembers]
     public AgentRuntimeContext(AgentRuntimeContext source)
@@ -40,9 +40,9 @@ public AgentRuntimeContext(AgentRuntimeContext source)
         Config = source.Config;
         ChatClient = source.ChatClient;
         ChatClientRegistry = source.ChatClientRegistry;
-        EffectiveMainModel = source.EffectiveMainModel;
-        EffectiveProviderId = source.EffectiveProviderId;
-        EffectiveProviderProtocol = source.EffectiveProviderProtocol;
+        _effectiveMainModel = source._effectiveMainModel;
+        _effectiveProviderId = source._effectiveProviderId;
+        _effectiveProviderProtocol = source._effectiveProviderProtocol;
         EffectiveReasoning = source.EffectiveReasoning;
         EffectiveSpeed = source.EffectiveSpeed;
         WorkspacePath = source.WorkspacePath;
@@ -95,10 +95,10 @@ public AgentRuntimeContext(AgentRuntimeContext source)
     public required AppConfig Config { get; init; }
 
     /// <summary>
-    /// The chat client for AI interactions.
-    /// Required for subagent spawning and other AI-powered tools.
+    /// The resolved chat client for AI interactions.
+    /// Root workspace contexts may leave this unset until an agent is built.
     /// </summary>
-    public required IChatClient ChatClient { get; init; }
+    public IChatClient? ChatClient { get; init; }
 
     /// <summary>
     /// Central provider-neutral registry used to resolve model-specific chat clients.
@@ -112,30 +112,40 @@ public ChatClientRegistry ChatClientRegistry
     /// <summary>
     /// Effective MainAgent model represented by <see cref="ChatClient"/>.
     /// </summary>
+    private string? _effectiveMainModel;
+
     public string EffectiveMainModel
     {
-        get => string.IsNullOrWhiteSpace(field) ? ChatClientRegistry.ResolveMainModel(Config) : field;
-        init;
+        get => string.IsNullOrWhiteSpace(_effectiveMainModel)
+            ? ChatClientRegistry.ResolveMainModel(Config)
+            : _effectiveMainModel;
+        init => _effectiveMainModel = value;
     }
 
     /// <summary>
     /// Effective provider id represented by <see cref="ChatClient"/>.
     /// </summary>
+    private string? _effectiveProviderId;
+
     public string EffectiveProviderId
     {
-        get => string.IsNullOrWhiteSpace(field) ? ChatClientRegistry.ResolveMainProviderId(Config) : field;
-        init;
+        get => string.IsNullOrWhiteSpace(_effectiveProviderId)
+            ? ChatClientRegistry.ResolveMainProviderId(Config)
+            : _effectiveProviderId;
+        init => _effectiveProviderId = value;
     }
 
     /// <summary>
     /// Effective provider protocol represented by <see cref="ChatClient"/>.
     /// </summary>
+    private string? _effectiveProviderProtocol;
+
     public string EffectiveProviderProtocol
     {
-        get => string.IsNullOrWhiteSpace(field)
+        get => string.IsNullOrWhiteSpace(_effectiveProviderProtocol)
             ? ChatClientRegistry.ResolveMainRuntime(Config, EffectiveProviderId, EffectiveMainModel).Protocol
-            : field;
-        init;
+            : _effectiveProviderProtocol;
+        init => _effectiveProviderProtocol = value;
     }
 
     /// <summary>

src/DotCraft.Core/Dreams/DreamsSessionRunner.cs

@@ -37,7 +37,7 @@ public sealed class DreamsSessionRunner(
     DreamStore dreamStore,
     ILogger<DreamsSessionRunner>? logger = null) : IDreamsRunner
 {
-    public string ModelId { get; } = chatClientRegistry.ResolveConsolidationModel(config);
+    public string ModelId => chatClientRegistry.ResolveConsolidationModel(config);
 
     public async Task<DreamsGenerationResult> GenerateAsync(
         DreamsRunInput input,
@@ -55,9 +55,9 @@ public async Task<DreamsGenerationResult> GenerateAsync(
         var turnIds = new List<string>();
         var usage = new TokenUsageInfo();
         DreamStoreDescriptor? outputStore = null;
-        var effectiveModelId = string.IsNullOrWhiteSpace(modelId) ? ModelId : modelId.Trim();
         try
         {
+            var effectiveModelId = string.IsNullOrWhiteSpace(modelId) ? ModelId : modelId.Trim();
             outputStore = string.IsNullOrWhiteSpace(outputStoreId)
                 ? dreamStore.CreateOutputStore(runId, DateTimeOffset.UtcNow)
                 : dreamStore.GetStoreDescriptor(outputStoreId);

src/DotCraft.Core/Sessions/Runtime/SessionService.cs

@@ -99,7 +99,7 @@ public Task CompleteAsync()
 /// </summary>
 public sealed partial class SessionService(
     AgentFactory agentFactory,
-    ChatClientAgent defaultAgent,
+    ChatClientAgent? defaultAgent,
     SessionPersistenceService persistence,
     SessionGate sessionGate,
     HookRunner? hookRunner = null,
@@ -155,6 +155,8 @@ private sealed class ThreadLoadGate
     private MaintenanceCoordinator? _maintenanceCoordinator;
     private static readonly AsyncLocal<bool> SuppressGoalBroadcastContext = new();
     private readonly IAppConfigMonitor? _appConfigMonitor = appConfigMonitor;
+    private readonly bool _hasExplicitDefaultAgent = defaultAgent != null;
+    private ChatClientAgent? _defaultAgent = defaultAgent;
     private string DataPath => persistence.DataPath;
     private readonly ConcurrentDictionary<string, byte> _sessionStartHookThreads = new(StringComparer.Ordinal);
 
@@ -325,7 +327,8 @@ internal static List<ChatMessage> BuildNativeSubAgentForkHistory(
 
     private McpAppTransientContextStore? McpAppTransientContexts => mcpAppTransientContextStore;
 
-    private ChatClientAgent DefaultAgent => defaultAgent;
+    private ChatClientAgent DefaultAgent =>
+        _defaultAgent ??= agentFactory.CreateAgentForMode(AgentMode.Agent);
 
     private AgentFactory AgentFactory => agentFactory;
 
@@ -337,7 +340,7 @@ internal static List<ChatMessage> BuildNativeSubAgentForkHistory(
     private ChatClientAgent GetThreadAgentOrDefault(string threadId) =>
         _runtimeRegistry.TryGetRuntime(threadId, out var runtime) && runtime.Agent != null
             ? runtime.Agent
-            : defaultAgent;
+            : DefaultAgent;
 
     private bool HasThreadAgent(string threadId) =>
         _runtimeRegistry.TryGetRuntime(threadId, out var runtime) && runtime.Agent != null;
@@ -1735,12 +1738,14 @@ private async Task<TurnExecutionResources> CaptureTurnExecutionResourcesAsync(
         ThreadRuntime runtime,
         CancellationToken ct)
     {
+        if (!_hasExplicitDefaultAgent || _forcePerThreadAgents)
+            await EnsurePerThreadAgentIfMissingAsync(runtime.Thread.Id, runtime.Thread, ct).ConfigureAwait(false);
         using (await AcquireThreadAgentLockAsync(runtime.Thread.Id, ct).ConfigureAwait(false))
         {
             if (!_runtimeRegistry.IsCurrent(runtime.Thread.Id, runtime))
                 throw new InvalidOperationException($"Thread '{runtime.Thread.Id}' runtime was replaced during Turn admission.");
             return new TurnExecutionResources(
-                runtime.Agent ?? defaultAgent,
+                runtime.Agent ?? DefaultAgent,
                 runtime.LatestToolSnapshot);
         }
     }
@@ -1906,7 +1911,6 @@ async Task RunRegularTurnAsync()
 
             IDisposable? gateLock = null;
             IDisposable? approvalOverride = null;
-            var agent = defaultAgent;
             List<ChatMessage>? session = null;
             TokenTracker? tokenTracker = null;
             var itemProjector = new TurnItemProjector(
@@ -2683,7 +2687,7 @@ await FailAndPersistTurnAsync(
                 // Resource capture was ordered at admission. It may wait for an in-flight
                 // publication, but later configuration changes cannot overtake it.
                 var executionResources = await turnContext.Resources.WaitAsync(executionCt).ConfigureAwait(false);
-                agent = executionResources.Agent;
+                var agent = executionResources.Agent;
                 turnRuntime.ToolSnapshot = executionResources.ToolSnapshot;
 
                 // Bind tracing and token tracking before model history reconstruction.
@@ -6342,11 +6346,12 @@ private static bool TryResolveProviderFunctionCall(
 
     private static IChatClient ResolveThreadChatClient(AgentRuntimeContext baseContext, EffectiveModelRuntime runtime)
     {
-        if (string.Equals(runtime.ProviderId, baseContext.EffectiveProviderId, StringComparison.OrdinalIgnoreCase)
+        if (baseContext.ChatClient is { } chatClient
+            && string.Equals(runtime.ProviderId, baseContext.EffectiveProviderId, StringComparison.OrdinalIgnoreCase)
             && string.Equals(runtime.Protocol, baseContext.EffectiveProviderProtocol, StringComparison.OrdinalIgnoreCase)
             && string.Equals(runtime.Model, baseContext.EffectiveMainModel, StringComparison.Ordinal))
         {
-            return baseContext.ChatClient;
+            return chatClient;
         }
 
         return baseContext.ChatClientRegistry.GetChatClient(runtime);

src/DotCraft.Core/Sessions/Runtime/SessionServiceFactory.cs

@@ -14,8 +14,8 @@ namespace DotCraft.Sessions;
 
 /// <summary>
 /// Factory helper that constructs a <see cref="SessionService"/> from an already-built
-/// <see cref="DotCraft.Agents.AgentFactory"/> and <see cref="ChatClientAgent"/> plus shared DI services.
-/// Avoids boilerplate across channel hosts that each build their own AgentFactory.
+/// <see cref="DotCraft.Agents.AgentFactory"/>, an optional default <see cref="ChatClientAgent"/>,
+/// and shared DI services. When omitted, the default agent is built on first use.
 /// </summary>
 public static class SessionServiceFactory
 {
@@ -26,7 +26,7 @@ public static class SessionServiceFactory
     /// </summary>
     public static SessionService Create(
         AgentFactory agentFactory,
-        ChatClientAgent agent,
+        ChatClientAgent? agent,
         IServiceProvider sp,
         TimeSpan? approvalTimeout = null)
     {