feat: launch first-time setup in webui (#5078)

nanobot/cli/commands.py

@@ -920,11 +920,10 @@ def _load_webui_setup_config(config_path: Path) -> Config:
 
 def _provider_setup_error(config: Config) -> str | None:
     """Return the provider setup error, or None when the current model can start."""
-    from nanobot.config.loader import resolve_config_env_vars
     from nanobot.providers.factory import build_provider_snapshot
 
     try:
-        build_provider_snapshot(resolve_config_env_vars(config.model_copy(deep=True)))
+        build_provider_snapshot(config)
     except ValueError as exc:
         return str(exc)
     return None
@@ -1427,7 +1426,7 @@ def webui(
     ),
 ) -> None:
     """Prepare the local WebUI, start the gateway, and open the browser workbench."""
-    from nanobot.config.loader import save_config
+    from nanobot.config.loader import resolve_config_env_vars, save_config
     from nanobot.gateway import GatewayRuntime, GatewayRuntimePaths, GatewayStartOptions
 
     _ensure_interactive_tty_mode()
@@ -1441,8 +1440,24 @@ def webui(
     if workspace:
         setup_config.agents.defaults.workspace = workspace
 
-    provider_error = _provider_setup_error(setup_config)
-    if provider_error:
+    try:
+        resolved_setup_config = resolve_config_env_vars(setup_config.model_copy(deep=True))
+    except ValueError as exc:
+        console.print(f"[red]Error: {exc}[/red]")
+        raise typer.Exit(1) from exc
+
+    provider_error = _provider_setup_error(resolved_setup_config)
+    settings_setup_error = provider_error if provider_error and created_config else None
+    if settings_setup_error:
+        console.print(f"[yellow]Model setup is incomplete: {provider_error}[/yellow]")
+        console.print("Configure a provider and model in WebUI Settings → Models.")
+        if background:
+            console.print(
+                "[red]First-time WebUI setup must run in the foreground. "
+                "Run `nanobot webui` without --background.[/red]"
+            )
+            raise typer.Exit(1)
+    elif provider_error:
         console.print(f"[dim]Provider check: {provider_error}[/dim]")
         setup_config = _run_quick_start_for_webui(setup_config, yes=yes)
         if workspace:
@@ -1585,6 +1600,7 @@ def webui(
         port=effective_gateway_port,
         open_browser_url=None if no_open else webui_url,
         webui_bundle_mode=webui_bundle_mode,
+        unconfigured_provider_error=settings_setup_error,
     )
 
 
@@ -1603,6 +1619,7 @@ def _run_gateway(
     webui_runtime_surface: str = "browser",
     webui_runtime_capabilities: dict[str, Any] | None = None,
     health_server_enabled: bool = True,
+    unconfigured_provider_error: str | None = None,
 ) -> None:
     """Shared gateway runtime; ``open_browser_url`` opens a tab once channels are up."""
     from nanobot.agent.model_presets import load_model_preset_catalog
@@ -1616,7 +1633,11 @@ def _run_gateway(
     from nanobot.cron.service import CronJobSkippedError, CronService
     from nanobot.cron.session_turns import is_bound_cron_job
     from nanobot.cron.types import CronJob
-    from nanobot.providers.factory import build_provider_snapshot, load_provider_snapshot
+    from nanobot.providers.factory import (
+        build_provider_snapshot,
+        build_unconfigured_provider_snapshot,
+        load_provider_snapshot,
+    )
     from nanobot.providers.fallback_provider import FallbackProvider
     from nanobot.providers.image_generation import image_gen_provider_configs
     from nanobot.session.manager import SessionManager
@@ -1664,13 +1685,24 @@ def _run_gateway(
         return snapshot
 
     def _load_gateway_provider_snapshot(*args: Any, **kwargs: Any):
-        return _observe_fallback_models(load_provider_snapshot(*args, **kwargs))
+        try:
+            return _observe_fallback_models(load_provider_snapshot(*args, **kwargs))
+        except ValueError as exc:
+            if unconfigured_provider_error is None:
+                raise
+            return build_unconfigured_provider_snapshot(config, str(exc))
 
-    try:
-        provider_snapshot = _observe_fallback_models(build_provider_snapshot(config))
-    except ValueError as exc:
-        console.print(f"[red]Error: {exc}[/red]")
-        raise typer.Exit(1) from exc
+    if unconfigured_provider_error is not None:
+        provider_snapshot = build_unconfigured_provider_snapshot(
+            config,
+            unconfigured_provider_error,
+        )
+    else:
+        try:
+            provider_snapshot = _observe_fallback_models(build_provider_snapshot(config))
+        except ValueError as exc:
+            console.print(f"[red]Error: {exc}[/red]")
+            raise typer.Exit(1) from exc
     session_manager = SessionManager(config.workspace_path)
 
     # Self-heal the gateway state file with the current PID after any restart.

nanobot/providers/factory.py

@@ -212,6 +212,22 @@ def make_provider(
     return provider
 
 
+def build_unconfigured_provider_snapshot(config: Config, setup_error: str) -> ProviderSnapshot:
+    """Build a non-networking runtime so the WebUI can collect first-time setup."""
+    from nanobot.providers.unconfigured_provider import UnconfiguredProvider
+
+    preset = config.resolve_preset()
+    provider = UnconfiguredProvider(preset.model)
+    provider.generation = preset.to_generation_settings()
+    return ProviderSnapshot(
+        provider=provider,
+        model=preset.model,
+        context_window_tokens=preset.context_window_tokens,
+        signature=("unconfigured", setup_error, preset.model),
+        generation=provider.generation,
+    )
+
+
 def provider_signature(
     config: Config,
     *,

nanobot/providers/unconfigured_provider.py

@@ -0,0 +1,36 @@
+"""Provider used while the local WebUI is waiting for first-time setup."""
+
+from __future__ import annotations
+
+from nanobot.providers.base import LLMProvider, LLMResponse
+
+
+class UnconfiguredProvider(LLMProvider):
+    """Keep the gateway available for settings before a model is configured."""
+
+    def __init__(self, default_model: str) -> None:
+        super().__init__()
+        self._default_model = default_model
+
+    async def chat(
+        self,
+        messages: list[dict],
+        tools: list[dict] | None = None,
+        model: str | None = None,
+        max_tokens: int = 4096,
+        temperature: float = 0.7,
+        reasoning_effort: str | None = None,
+        tool_choice: str | dict | None = None,
+    ) -> LLMResponse:
+        return LLMResponse(
+            content=(
+                "Nanobot needs a model before it can chat. Open Settings → Models "
+                "to configure a provider and model, then send your message again."
+            ),
+            finish_reason="error",
+            error_kind="configuration",
+            error_should_retry=False,
+        )
+
+    def get_default_model(self) -> str:
+        return self._default_model