Fix(provider): keep provider onboarding active until setup succeeds

Author: kesimo

CHANGELOG.md

@@ -7,6 +7,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.21.9] - 2026-05-10
+
+### Changed
+
+- **Runtime provider onboarding** - when the gateway starts or receives messages without a working LLM provider, it keeps running, answers with a provider-setup hint, reopens Placet onboarding as needed, and hot-loads the validated provider after setup completes.
+
 ## [0.21.8] - 2026-05-10
 
 ### Changed

facio/agent/loop.py

@@ -13,6 +13,7 @@
 
 from loguru import logger
 
+from facio.agent import status as agent_status
 from facio.agent.autocompact import AutoCompact
 from facio.agent.channel_context import (
     get_configured_keys_context,
@@ -25,29 +26,33 @@
 from facio.agent.loop_hook import LoopHook as _LoopHook
 from facio.agent.memory import Consolidator, Reflection
 from facio.agent.memory_search import MemorySearchDB
+from facio.agent.run_context import make_run_context, reset_run_context, set_run_context
 from facio.agent.runner import _MAX_INJECTIONS_PER_TURN, AgentRunner, AgentRunSpec
-from facio.agent.run_context import make_run_context, set_run_context, reset_run_context
 from facio.agent.session_state import (
     PENDING_USER_TURN_KEY,
     RUNTIME_CHECKPOINT_KEY,
     SessionCheckpointManager,
 )
-from facio.agent import status as agent_status
 from facio.agent.stream_session import StreamSession
 from facio.agent.subagent import SubagentManager
-from facio.agent.turn_executor import TurnExecutor
 from facio.agent.tools.file_state import FileStateStore, bind_file_states, reset_file_states
 from facio.agent.tools.registry import ToolRegistry
-from facio.bus.events import InboundMessage, OutboundMessage
+from facio.agent.turn_executor import TurnExecutor
 from facio.bus import metadata as bus_meta
+from facio.bus.events import InboundMessage, OutboundMessage
 from facio.bus.queue import MessageBus
 from facio.command import CommandContext, CommandRouter, register_builtin_commands
 from facio.config.schema import AgentDefaults
 from facio.providers.base import LLMProvider
 from facio.session.manager import Session, SessionManager
 
 if TYPE_CHECKING:
-    from facio.config.schema import ChannelsConfig, ExecToolConfig, WebToolsConfig
+    from facio.config.schema import (
+        BrowserToolsConfig,
+        ChannelsConfig,
+        ExecToolConfig,
+        WebToolsConfig,
+    )
     from facio.cron.service import CronService
     from facio.providers.pool import ProviderPool
 
@@ -93,15 +98,15 @@ def __init__(
         context_block_limit: int | None = None,
         max_tool_result_chars: int | None = None,
         provider_retry_mode: str = "standard",
-        web_config: WebToolsConfig | None = None,
+        web_config: "WebToolsConfig | None" = None,
         browser_config: "BrowserToolsConfig | None" = None,
-        exec_config: ExecToolConfig | None = None,
+        exec_config: "ExecToolConfig | None" = None,
         tool_timeout: int = 300,
         cron_service: CronService | None = None,
         restrict_to_workspace: bool = False,
         session_manager: SessionManager | None = None,
         mcp_servers: dict | None = None,
-        channels_config: ChannelsConfig | None = None,
+        channels_config: "ChannelsConfig | None" = None,
         timezone: str | None = None,
         session_ttl_minutes: int = 0,
         hooks: list[AgentHook] | None = None,
@@ -126,10 +131,12 @@ def __init__(
         policy_enabled: bool | None = None,
         policy_skip_cron: bool | None = None,
         credential_store: Any | None = None,
+        runtime_config: Any | None = None,
+        runtime_config_path: Path | None = None,
     ):
-        from facio.config.schema import BrowserToolsConfig, ExecToolConfig, WebToolsConfig
         from facio.agent.credential_store import CredentialStore
         from facio.config.paths import get_data_dir
+        from facio.config.schema import BrowserToolsConfig, ExecToolConfig, WebToolsConfig
 
         defaults = AgentDefaults()
         self.bus = bus
@@ -189,6 +196,9 @@ def __init__(
         # reaching into the runner's hook context.
         self._current_iteration: int = 0
         self.provider_pool = provider_pool
+        self._runtime_config = runtime_config
+        self._runtime_config_path = runtime_config_path
+        self._provider_setup_task: asyncio.Task | None = None
         self.vision_model = vision_model
         self.vision_provider = vision_provider
         self.image_model = image_model
@@ -529,6 +539,105 @@ def _effective_session_key(self, msg: InboundMessage) -> str:
             return UNIFIED_SESSION_KEY
         return msg.session_key
 
+    def _load_current_runtime_config(self) -> Any | None:
+        if self._runtime_config_path is None:
+            return self._runtime_config
+        from facio.config.loader import load_config, resolve_config_env_vars
+
+        config = resolve_config_env_vars(load_config(self._runtime_config_path))
+        config.agents.defaults.workspace = str(self.workspace)
+        self._runtime_config = config
+        return config
+
+    @staticmethod
+    def _placet_setup_available(config: Any) -> bool:
+        channels = config.model_dump(mode="json", by_alias=True).get("channels", {})
+        placet = channels.get("placet", {})
+        return bool(placet.get("enabled") or placet.get("instanceUrl"))
+
+    async def _maybe_handle_provider_setup(self, msg: InboundMessage) -> bool:
+        config = self._load_current_runtime_config()
+        if config is None:
+            return False
+
+        from facio.channels.placet_onboarding import (
+            has_functioning_provider,
+            provider_setup_message,
+        )
+
+        if has_functioning_provider(config):
+            if getattr(self.provider, "_facio_unconfigured", False):
+                await self._reload_provider_from_config(config)
+            return False
+
+        placet_available = self._placet_setup_available(config)
+        if placet_available:
+            self._start_provider_setup(config)
+        await self.bus.publish_outbound(OutboundMessage(
+            channel=msg.channel,
+            chat_id=msg.chat_id,
+            content=provider_setup_message(placet_available=placet_available),
+            metadata=dict(msg.metadata or {}),
+        ))
+        return True
+
+    def _start_provider_setup(self, config: Any) -> None:
+        if self._runtime_config_path is None:
+            return
+        if self._provider_setup_task is not None and not self._provider_setup_task.done():
+            return
+        self._provider_setup_task = asyncio.create_task(self._run_provider_setup(config))
+
+    async def _run_provider_setup(self, config: Any) -> None:
+        if self._runtime_config_path is None:
+            return
+        from facio.channels.placet_onboarding import run_onboarding
+
+        try:
+            if await run_onboarding(config, self._runtime_config_path):
+                await self._reload_provider_from_config()
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            logger.warning("runtime provider setup failed", exc_info=True)
+
+    async def _reload_provider_from_config(self, config: Any | None = None) -> bool:
+        config = config or self._load_current_runtime_config()
+        if config is None:
+            return False
+
+        from facio.channels.placet_onboarding import has_functioning_provider
+
+        if not has_functioning_provider(config):
+            return False
+
+        from facio.facio import _make_provider
+        from facio.providers.pool import ProviderPool
+
+        provider = _make_provider(config)
+        pool = ProviderPool(config)
+        primary_name = config.get_provider_name(config.agents.defaults.model)
+        if primary_name:
+            pool.seed(primary_name, provider)
+
+        self.provider = provider
+        self.model = config.agents.defaults.model
+        self.runner = AgentRunner(provider)
+        self.provider_pool = pool
+        self.subagents.provider = provider
+        self.subagents.runner = AgentRunner(provider)
+        self.subagents.model = self.model
+        self.subagents.subagent_model = config.agents.defaults.subagent_model or self.model
+        self.subagents.provider_pool = pool
+        self.consolidator.set_provider(provider, self.model, self.context_window_tokens)
+        self.reflection.set_provider(provider, self.model)
+        for tool in self._hitl_tools:
+            if hasattr(tool, "set_provider_pool"):
+                tool.set_provider_pool(pool)
+        self._runtime_config = config
+        logger.info("runtime provider setup completed with provider {}", primary_name)
+        return True
+
     def _replay_token_budget(self) -> int:
         """Derive a token budget for session history replay from the context window.
 
@@ -802,6 +911,9 @@ async def _dispatch(self, msg: InboundMessage) -> None:
             self._pending_queues[session_key] = pending
 
         try:
+            if await self._maybe_handle_provider_setup(msg):
+                _run_status["stop_reason"] = "provider_setup_required"
+                return
             async with lock, gate:
                 # Notify the runtime integration that the agent is busy.
                 await self._runtime.send_status(agent_status.BUSY)
@@ -976,6 +1088,9 @@ async def _dispatch(self, msg: InboundMessage) -> None:
 
     async def close_mcp(self) -> None:
         """Drain pending background archives, then close MCP connections."""
+        if self._provider_setup_task is not None and not self._provider_setup_task.done():
+            self._provider_setup_task.cancel()
+            await asyncio.gather(self._provider_setup_task, return_exceptions=True)
         if self._background_tasks:
             await asyncio.gather(*self._background_tasks, return_exceptions=True)
             self._background_tasks.clear()

facio/channels/placet_onboarding.py

@@ -22,7 +22,6 @@
 # ---------------------------------------------------------------------------
 # Provider catalogue shown in the onboarding form (derived from registry)
 # ---------------------------------------------------------------------------
-
 from facio.providers.registry import PROVIDERS as _REGISTRY_PROVIDERS
 
 # OAuth providers offered through Placet relay
@@ -130,18 +129,50 @@
 # Public API
 # ---------------------------------------------------------------------------
 
+def has_functioning_provider(config: Config) -> bool:
+    """Return True when the active model resolves to a usable provider config."""
+    from facio.providers.registry import find_by_name
+
+    model = config.agents.defaults.model
+    provider_name = config.get_provider_name(model)
+    if not provider_name:
+        return False
+    spec = find_by_name(provider_name)
+    provider = config.get_provider(model)
+    if spec is None or provider is None:
+        return False
+    if spec.backend == "azure_openai":
+        return bool(provider.api_key and provider.api_base)
+    if spec.is_oauth:
+        return True
+    if spec.is_local:
+        return bool(provider.api_base or spec.default_api_base)
+    if spec.name == "custom":
+        return bool(provider.api_base)
+    if spec.is_direct:
+        return bool(provider.api_key or provider.api_base or spec.default_api_base or spec.name == "bedrock")
+    return bool(provider.api_key)
+
+
 def needs_onboarding(config: Config) -> bool:
-    """Return True when Placet is enabled but no LLM provider key is set."""
+    """Return True when Placet is enabled but no usable LLM provider is set."""
     placet = _get_placet_cfg(config)
     if not (placet.get("enabled") or placet.get("instanceUrl")):
         return False
+    return not has_functioning_provider(config)
 
-    # Check every provider field for an existing api_key
-    for field_name in config.providers.model_fields:
-        p = getattr(config.providers, field_name, None)
-        if p and getattr(p, "api_key", ""):
-            return False
-    return True
+
+def provider_setup_message(*, placet_available: bool) -> str:
+    """Build the fallback message shown while provider setup is incomplete."""
+    lines = [
+        "No working LLM provider is configured yet.",
+        "Please complete the provider setup before I can answer normally.",
+    ]
+    if placet_available:
+        lines.append("I opened the Placet setup form for you. Submit a valid provider there, then send your message again.")
+    else:
+        lines.append("Configure a provider in Facio settings or config, then send your message again.")
+    return "\n\n".join(lines)
 
 
 async def run_onboarding(config: Config, config_path: Path) -> bool: