fix(providers): refresh unavailable providers on request (#357)

* fix(providers): refresh unavailable providers on request

* fix(providers): handle alias refresh and empty inventories

* fix(gateway): surface refresh target resolution errors

Author: SantiagoDePolonia

internal/aliases/service.go

@@ -149,6 +149,28 @@ func (s *Service) ResolveModel(requested core.RequestedModelSelector) (core.Mode
 	return resolution.Resolved, changed, nil
 }
 
+// ResolveRefreshTarget returns an alias target without consulting the current
+// catalog so callers can refresh an unavailable target provider before normal
+// alias resolution is retried.
+func (s *Service) ResolveRefreshTarget(requested core.RequestedModelSelector) (core.ModelSelector, bool, error) {
+	if s == nil || requested.ExplicitProvider {
+		return core.ModelSelector{}, false, nil
+	}
+	name := normalizeName(requested.Model)
+	if name == "" {
+		return core.ModelSelector{}, false, nil
+	}
+	alias, ok := s.Get(name)
+	if !ok || !alias.Enabled {
+		return core.ModelSelector{}, false, nil
+	}
+	target, err := alias.TargetSelector()
+	if err != nil {
+		return core.ModelSelector{}, false, err
+	}
+	return target, true, nil
+}
+
 // Supports reports whether an alias currently resolves to a concrete model.
 func (s *Service) Supports(model string) bool {
 	_, ok := s.resolveAlias(model)

internal/aliases/service_test.go

@@ -128,6 +128,43 @@ func TestServiceResolveAndExposeModels(t *testing.T) {
 	}
 }
 
+func TestServiceResolveRefreshTargetDoesNotRequireCatalogSupport(t *testing.T) {
+	service, err := NewService(newMemoryStore(Alias{
+		Name:           "smart",
+		TargetModel:    "qwen3:8b",
+		TargetProvider: "ollama",
+		Enabled:        true,
+	}), newTestCatalog())
+	if err != nil {
+		t.Fatalf("NewService() error = %v", err)
+	}
+	if err := service.Refresh(context.Background()); err != nil {
+		t.Fatalf("Refresh() error = %v", err)
+	}
+
+	selector, changed, err := service.ResolveModel(core.NewRequestedModelSelector("smart", ""))
+	if err != nil {
+		t.Fatalf("ResolveModel() error = %v", err)
+	}
+	if changed {
+		t.Fatal("ResolveModel() changed = true, want false while target is absent from catalog")
+	}
+	if got := selector.QualifiedModel(); got != "smart" {
+		t.Fatalf("ResolveModel() selector = %q, want smart", got)
+	}
+
+	target, ok, err := service.ResolveRefreshTarget(core.NewRequestedModelSelector("smart", ""))
+	if err != nil {
+		t.Fatalf("ResolveRefreshTarget() error = %v", err)
+	}
+	if !ok {
+		t.Fatal("ResolveRefreshTarget() ok = false, want true")
+	}
+	if got := target.QualifiedModel(); got != "ollama/qwen3:8b" {
+		t.Fatalf("ResolveRefreshTarget() = %q, want ollama/qwen3:8b", got)
+	}
+}
+
 func TestServiceUpsertRejectsAliasChainAndAllowsMasking(t *testing.T) {
 	catalog := newTestCatalog()
 	catalog.add("gpt-4o", "openai", core.Model{ID: "gpt-4o", Object: "model"})

internal/gateway/request_model_resolution.go

@@ -11,6 +11,14 @@ type modelCountProvider interface {
 	ModelCount() int
 }
 
+type providerModelRefresher interface {
+	RefreshProviderModels(ctx context.Context, providerSelector string) (int, error)
+}
+
+type modelRefreshTargetResolver interface {
+	ResolveRefreshTarget(requested core.RequestedModelSelector) (core.ModelSelector, bool, error)
+}
+
 // ResolvedProviderName returns the configured provider instance name for a selector.
 func ResolvedProviderName(provider core.RoutableProvider, selector core.ModelSelector, fallback string) string {
 	fallback = strings.TrimSpace(fallback)
@@ -64,8 +72,20 @@ func ResolveRequestModelWithAuthorizer(
 	requested = core.NewRequestedModelSelector(requested.Model, requested.ProviderHint)
 
 	resolvedSelector, aliasApplied, err := ResolveExecutionSelector(provider, resolver, requested)
+	refreshed := false
 	if err != nil {
-		return nil, core.NewInvalidRequestError(err.Error(), err)
+		var refreshErr error
+		refreshed, refreshErr = refreshProviderModelsForResolution(ctx, provider, resolver, requested, resolvedSelector)
+		if refreshErr != nil {
+			return nil, refreshErr
+		}
+		if !refreshed {
+			return nil, core.NewInvalidRequestError(err.Error(), err)
+		}
+		resolvedSelector, aliasApplied, err = ResolveExecutionSelector(provider, resolver, requested)
+		if err != nil {
+			return nil, core.NewInvalidRequestError(err.Error(), err)
+		}
 	}
 	if resolvedSelector == (core.ModelSelector{}) {
 		resolvedSelector, err = requested.Normalize()
@@ -75,9 +95,41 @@ func ResolveRequestModelWithAuthorizer(
 	}
 
 	resolvedModel := resolvedSelector.QualifiedModel()
+	if counted, ok := provider.(modelCountProvider); ok && counted.ModelCount() == 0 {
+		if !refreshed {
+			var refreshErr error
+			refreshed, refreshErr = refreshProviderModelsForResolution(ctx, provider, resolver, requested, resolvedSelector)
+			if refreshErr != nil {
+				return nil, refreshErr
+			}
+			if refreshed {
+				resolvedSelector, aliasApplied, err = ResolveExecutionSelector(provider, resolver, requested)
+				if err != nil {
+					return nil, core.NewInvalidRequestError(err.Error(), err)
+				}
+				resolvedModel = resolvedSelector.QualifiedModel()
+			}
+		}
+	}
 	if counted, ok := provider.(modelCountProvider); ok && counted.ModelCount() == 0 {
 		return nil, core.NewProviderError("", 0, "model registry not initialized", nil)
 	}
+	if !provider.Supports(resolvedModel) {
+		if !refreshed {
+			var refreshErr error
+			refreshed, refreshErr = refreshProviderModelsForResolution(ctx, provider, resolver, requested, resolvedSelector)
+			if refreshErr != nil {
+				return nil, refreshErr
+			}
+			if refreshed {
+				resolvedSelector, aliasApplied, err = ResolveExecutionSelector(provider, resolver, requested)
+				if err != nil {
+					return nil, core.NewInvalidRequestError(err.Error(), err)
+				}
+				resolvedModel = resolvedSelector.QualifiedModel()
+			}
+		}
+	}
 	if !provider.Supports(resolvedModel) {
 		return nil, core.NewInvalidRequestError("unsupported model: "+resolvedModel, nil)
 	}
@@ -96,6 +148,45 @@ func ResolveRequestModelWithAuthorizer(
 	}, nil
 }
 
+func refreshProviderModelsForResolution(
+	ctx context.Context,
+	provider core.RoutableProvider,
+	resolver ModelResolver,
+	requested core.RequestedModelSelector,
+	resolvedSelector core.ModelSelector,
+) (bool, error) {
+	refresher, ok := provider.(providerModelRefresher)
+	if !ok {
+		return false, nil
+	}
+
+	providerSelector := strings.TrimSpace(resolvedSelector.Provider)
+	if providerSelector == "" {
+		if targetResolver, ok := resolver.(modelRefreshTargetResolver); ok {
+			selector, ok, err := targetResolver.ResolveRefreshTarget(requested)
+			if err != nil {
+				return false, err
+			}
+			if ok {
+				providerSelector = strings.TrimSpace(selector.Provider)
+			}
+		}
+	}
+	if providerSelector == "" {
+		selector, err := requested.Normalize()
+		if err != nil {
+			return false, nil
+		}
+		providerSelector = strings.TrimSpace(selector.Provider)
+	}
+	if providerSelector == "" {
+		return false, nil
+	}
+
+	_, err := refresher.RefreshProviderModels(ctx, providerSelector)
+	return true, err
+}
+
 // ResolveExecutionSelector applies explicit and provider-owned selector resolution.
 func ResolveExecutionSelector(
 	provider core.RoutableProvider,
@@ -119,12 +210,15 @@ func ResolveExecutionSelector(
 	}
 
 	if providerResolver, ok := provider.(ModelResolver); ok {
-		var providerChanged bool
-		resolvedSelector, providerChanged, err = providerResolver.ResolveModel(requested)
+		providerSelector, providerChanged, err := providerResolver.ResolveModel(requested)
 		if err != nil {
+			if resolvedSelector != (core.ModelSelector{}) {
+				// Preserve alias targets so callers can refresh the concrete provider before retrying.
+				return resolvedSelector, aliasApplied, err
+			}
 			return core.ModelSelector{}, false, err
 		}
-		return resolvedSelector, aliasApplied || providerChanged, nil
+		return providerSelector, aliasApplied || providerChanged, nil
 	}
 
 	if resolvedSelector != (core.ModelSelector{}) {