Add multi-model provider support and an agents page

- Named LLM providers under `agent.llm.providers` (LlmProviderProperties) with a
  per-provider ChatModelFactory SPI (OpenAI, Anthropic incl. Claude Code OAuth,
  Ollama, Google Gen AI) and a ChatClientRegistry that builds/caches a ChatClient
  per provider and rebuilds on configuration refresh.
- Hot-reload of configuration without a full restart (ConfigurationRebinder +
  ConfigurationRefreshedEvent; ConfigurationManager now tracks changed keys and
  supports removeProperty).
- Main agent ChatClient delegates to the default provider and rebuilds on refresh
  (MainChatClientProvider + DelegatingChatClient); subagent routing wired via the
  agent-utils TaskTool.
- Agents page + REST API (/api/agents): create/edit/delete agents; structured
  config (provider type, model, API key) is saved to application.yaml under
  agent.llm.providers.<name>, and description + instructions to
  workspace/agents/<name>.md.
- ProviderConnectionTester + /api/providers REST; onboarding now saves the selected
  provider as providers.default.
- Tests for registry fallback, connection tester, and the agent/provider controllers.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: arefbehboudi

app/src/main/java/ai/javaclaw/JavaClawApplication.java

@@ -44,8 +44,18 @@ public void run(ApplicationArguments args) throws Exception {
 
         @EventListener
         public void on(ConfigurationChangedEvent configurationChangedEvent) {
+            // Model-provider changes are applied at runtime via ConfigurationRebinder +
+            // ChatClientRegistry (hot reload), so they must NOT trigger a full restart.
+            boolean providerChangeOnly = !configurationChangedEvent.changedKeys().isEmpty()
+                    && configurationChangedEvent.changedKeys().stream()
+                    .allMatch(key -> key.equals("agent.llm.providers") || key.startsWith("agent.llm.providers."));
+            if (providerChangeOnly) {
+                log.info("Configuration change limited to model providers; applying without restart.");
+                return;
+            }
+
             ApplicationArguments args = applicationContext.getBean(ApplicationArguments.class);
-            
+
             Thread thread = new Thread(() -> {
                 try {
                     Thread.sleep(2000);

app/src/main/java/ai/javaclaw/onboarding/steps/S2_ProviderStep.java

@@ -1,6 +1,7 @@
 package ai.javaclaw.onboarding.steps;
 
 import ai.javaclaw.configuration.ConfigurationManager;
+import ai.javaclaw.llm.LlmProviderProperties;
 import ai.javaclaw.onboarding.AgentOnboardingProvider;
 import ai.javaclaw.onboarding.AgentOnboardingProviders;
 import ai.javaclaw.onboarding.OnboardingProvider;
@@ -63,14 +64,24 @@ public String processStep(Map<String, String> formParams, Map<String, Object> se
     @Override
     public void saveConfiguration(Map<String, Object> session, ConfigurationManager configurationManager) throws IOException {
         String providerId = (String) session.get(SESSION_PROVIDER);
+        if (providerId == null || providerId.isBlank()) {
+            return;
+        }
         String model = (String) session.get(SESSION_MODEL);
         String apiKey = (String) session.getOrDefault(SESSION_API_KEY, "");
 
         AgentOnboardingProvider agentOnboardingProvider = agentOnboardingProviders.getById(providerId);
+
+        // The single provider configured during onboarding becomes the "default" named provider.
+        String base = "agent.llm.providers." + LlmProviderProperties.DEFAULT_PROVIDER_NAME;
         Map<String, Object> props = new LinkedHashMap<>();
-        agentOnboardingProvider.saveProperty(props, "chat.options.model", model);
-        agentOnboardingProvider.saveProperty(props, "api-key", apiKey);
-        props.put("spring.ai.model.chat", agentOnboardingProvider.getId().replace(".", "-"));
+        props.put(base + ".provider", agentOnboardingProvider.getId());
+        if (model != null && !model.isBlank()) {
+            props.put(base + ".model", model);
+        }
+        if (apiKey != null && !apiKey.isBlank()) {
+            props.put(base + ".api-key", apiKey);
+        }
         configurationManager.updateProperties(props);
     }
 }

app/src/main/java/ai/javaclaw/providers/api/ProviderController.java

@@ -0,0 +1,256 @@
+package ai.javaclaw.providers.api;
+
+import ai.javaclaw.configuration.ConfigurationManager;
+import ai.javaclaw.llm.ChatModelFactory;
+import ai.javaclaw.llm.LlmProviderProperties;
+import ai.javaclaw.llm.LlmProviderProperties.ProviderConfig;
+import ai.javaclaw.llm.ProviderConnectionTester;
+import ai.javaclaw.llm.SubagentReferenceScanner;
+import ai.javaclaw.llm.TestResult;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.regex.Pattern;
+
+/**
+ * REST API for managing the named LLM providers under {@code agent.llm.providers}. Saving fires a
+ * {@code ConfigurationChangedEvent}, which the {@code ConfigurationRebinder} turns into a
+ * {@code ConfigurationRefreshedEvent} so the {@code ChatClientRegistry} rebuilds affected clients.
+ */
+@RestController
+@RequestMapping("/api/providers")
+public class ProviderController {
+
+    private static final Pattern NAME_PATTERN = Pattern.compile("[a-z0-9-]+");
+    private static final String CONFIG_PREFIX = "agent.llm.providers";
+    private static final long STATUS_CACHE_TTL_MS = 30_000L;
+
+    private static final String STATUS_OK = "OK";
+    private static final String STATUS_UNREACHABLE = "UNREACHABLE";
+
+    private final LlmProviderProperties properties;
+    private final ProviderConnectionTester connectionTester;
+    private final ConfigurationManager configurationManager;
+    private final SubagentReferenceScanner subagentScanner;
+    private final List<ChatModelFactory> chatModelFactories;
+
+    private final Map<String, CachedStatus> statusCache = new ConcurrentHashMap<>();
+
+    public ProviderController(LlmProviderProperties properties,
+                              ProviderConnectionTester connectionTester,
+                              ConfigurationManager configurationManager,
+                              SubagentReferenceScanner subagentScanner,
+                              List<ChatModelFactory> chatModelFactories) {
+        this.properties = properties;
+        this.connectionTester = connectionTester;
+        this.configurationManager = configurationManager;
+        this.subagentScanner = subagentScanner;
+        this.chatModelFactories = chatModelFactories;
+    }
+
+    private Map<String, ProviderConfig> currentProviders() {
+        return properties.getProviders();
+    }
+
+    @GetMapping
+    public List<ProviderDto> list() {
+        List<ProviderDto> result = new ArrayList<>();
+        currentProviders().forEach((name, config) ->
+                result.add(toDto(name, config, cachedStatus(name, config))));
+        return result;
+    }
+
+    @PostMapping("/test")
+    public TestResult test(@RequestBody ProviderForm form) {
+        return connectionTester.test(form.toConfig());
+    }
+
+    @PostMapping
+    public ResponseEntity<?> create(@RequestBody ProviderForm form) {
+        String name = form.name() == null ? "" : form.name().trim();
+        if (name.isBlank() || !NAME_PATTERN.matcher(name).matches()) {
+            return badRequest("Provider name must match [a-z0-9-]+");
+        }
+        if (LlmProviderProperties.DEFAULT_PROVIDER_NAME.equals(name)) {
+            return badRequest("The 'default' provider is created during onboarding and can only be edited");
+        }
+        if (currentProviders().containsKey(name)) {
+            return badRequest("A provider named '" + name + "' already exists");
+        }
+        if (!isKnownProviderType(form.provider())) {
+            return badRequest("Unknown provider type: " + form.provider());
+        }
+
+        TestResult testResult = connectionTester.test(form.toConfig());
+        if (!testResult.success()) {
+            return badRequest("Connection test failed: " + testResult.message());
+        }
+
+        save(name, form);
+        return ResponseEntity.status(HttpStatus.CREATED)
+                .body(toDto(name, form.toConfig(), STATUS_OK));
+    }
+
+    @PutMapping("/{name}")
+    public ResponseEntity<?> update(@PathVariable String name, @RequestBody ProviderForm form) {
+        ProviderConfig existing = currentProviders().get(name);
+        if (existing == null) {
+            return ResponseEntity.notFound().build();
+        }
+
+        // Name and provider type are immutable on edit.
+        String provider = existing.getProvider();
+        String newApiKey = form.apiKey();
+        String newBaseUrl = form.baseUrl();
+        String newModel = form.model();
+
+        boolean credentialsChanged =
+                !equalsNullSafe(newApiKey, existing.getApiKey()) || !equalsNullSafe(newBaseUrl, existing.getBaseUrl());
+        if (credentialsChanged) {
+            ProviderConfig candidate = new ProviderConfig(provider, newApiKey, newBaseUrl, newModel);
+            TestResult testResult = connectionTester.test(candidate);
+            if (!testResult.success()) {
+                return badRequest("Connection test failed: " + testResult.message());
+            }
+        }
+
+        ProviderForm effective = new ProviderForm(name, provider, newModel, newApiKey, newBaseUrl);
+        save(name, effective);
+        statusCache.remove(name);
+        return ResponseEntity.ok(toDto(name, effective.toConfig(), STATUS_OK));
+    }
+
+    @DeleteMapping("/{name}")
+    public ResponseEntity<?> delete(@PathVariable String name,
+                                    @RequestParam(defaultValue = "false") boolean force) {
+        if (!currentProviders().containsKey(name)) {
+            return ResponseEntity.notFound().build();
+        }
+        if (LlmProviderProperties.DEFAULT_PROVIDER_NAME.equals(name)) {
+            return badRequest("The default provider cannot be removed");
+        }
+
+        Set<String> referencedBy = subagentScanner.namesReferencing(name);
+        if (!referencedBy.isEmpty() && !force) {
+            Map<String, Object> body = new LinkedHashMap<>();
+            body.put("message", "'" + name + "' is referenced by " + referencedBy.size() + " subagent(s)");
+            body.put("affected", new ArrayList<>(referencedBy));
+            return ResponseEntity.status(HttpStatus.CONFLICT).body(body);
+        }
+
+        try {
+            configurationManager.removeProperty(CONFIG_PREFIX + "." + name);
+        } catch (IOException e) {
+            return ResponseEntity.internalServerError().body(error("Failed to update configuration: " + e.getMessage()));
+        }
+        statusCache.remove(name);
+        return ResponseEntity.noContent().build();
+    }
+
+    @GetMapping("/{name}/status")
+    public ResponseEntity<?> status(@PathVariable String name) {
+        ProviderConfig config = currentProviders().get(name);
+        if (config == null) {
+            return ResponseEntity.notFound().build();
+        }
+        TestResult result = connectionTester.test(config);
+        String status = result.success() ? STATUS_OK : STATUS_UNREACHABLE;
+        statusCache.put(name, new CachedStatus(status, now()));
+        return ResponseEntity.ok(Map.of("name", name, "status", status, "message", result.message()));
+    }
+
+    // --- helpers ---
+
+    private void save(String name, ProviderForm form) {
+        String base = CONFIG_PREFIX + "." + name;
+        Map<String, Object> props = new LinkedHashMap<>();
+        props.put(base + ".provider", form.provider());
+        if (notBlank(form.model())) props.put(base + ".model", form.model());
+        if (notBlank(form.apiKey())) props.put(base + ".api-key", form.apiKey());
+        if (notBlank(form.baseUrl())) props.put(base + ".base-url", form.baseUrl());
+        try {
+            configurationManager.updateProperties(props);
+        } catch (IOException e) {
+            throw new IllegalStateException("Failed to write provider configuration", e);
+        }
+    }
+
+    private boolean isKnownProviderType(String type) {
+        if (type == null || type.isBlank()) {
+            return false;
+        }
+        String normalized = type.trim().toLowerCase();
+        return chatModelFactories.stream().anyMatch(f -> f.supports(normalized));
+    }
+
+    private String cachedStatus(String name, ProviderConfig config) {
+        CachedStatus cached = statusCache.get(name);
+        if (cached != null && (now() - cached.timestamp()) < STATUS_CACHE_TTL_MS) {
+            return cached.status();
+        }
+        TestResult result = connectionTester.test(config);
+        String status = result.success() ? STATUS_OK : STATUS_UNREACHABLE;
+        statusCache.put(name, new CachedStatus(status, now()));
+        return status;
+    }
+
+    private ProviderDto toDto(String name, ProviderConfig config, String status) {
+        boolean isDefault = LlmProviderProperties.DEFAULT_PROVIDER_NAME.equals(name);
+        return new ProviderDto(name, config.getProvider(), config.getModel(),
+                config.getBaseUrl(), maskApiKey(config.getApiKey()), isDefault, status);
+    }
+
+    private static String maskApiKey(String apiKey) {
+        if (apiKey == null || apiKey.isBlank()) {
+            return "";
+        }
+        String key = apiKey.trim();
+        if (key.length() <= 7) {
+            return "••••";
+        }
+        return key.substring(0, 3) + "..." + key.substring(key.length() - 4);
+    }
+
+    private static boolean notBlank(String value) {
+        return value != null && !value.isBlank();
+    }
+
+    private static boolean equalsNullSafe(String a, String b) {
+        String na = a == null ? "" : a;
+        String nb = b == null ? "" : b;
+        return na.equals(nb);
+    }
+
+    private static long now() {
+        return System.currentTimeMillis();
+    }
+
+    private static ResponseEntity<Map<String, Object>> badRequest(String message) {
+        return ResponseEntity.badRequest().body(error(message));
+    }
+
+    private static Map<String, Object> error(String message) {
+        Map<String, Object> body = new LinkedHashMap<>();
+        body.put("message", message);
+        return body;
+    }
+
+    private record CachedStatus(String status, long timestamp) {
+    }
+}

app/src/main/java/ai/javaclaw/providers/api/ProviderDto.java

@@ -0,0 +1,23 @@
+package ai.javaclaw.providers.api;
+
+/**
+ * Read model for a configured provider as returned by {@code GET /api/providers}. Never carries the
+ * raw API key — only a masked form for display.
+ *
+ * @param name         provider name (the key under {@code agent.llm.providers})
+ * @param provider     provider type (openai | anthropic | ollama | google.genai | ...)
+ * @param model        configured model id
+ * @param baseUrl      base URL (relevant for ollama / self-hosted)
+ * @param apiKeyMasked masked API key for cloud providers, e.g. {@code sk-...a1b2}; empty otherwise
+ * @param isDefault    whether this is the reserved {@code default} provider
+ * @param status       live reachability: {@code OK}, {@code UNREACHABLE}, or {@code CHECKING}
+ */
+public record ProviderDto(
+        String name,
+        String provider,
+        String model,
+        String baseUrl,
+        String apiKeyMasked,
+        boolean isDefault,
+        String status) {
+}

app/src/main/java/ai/javaclaw/providers/api/ProviderForm.java

@@ -0,0 +1,19 @@
+package ai.javaclaw.providers.api;
+
+import ai.javaclaw.llm.LlmProviderProperties.ProviderConfig;
+
+/**
+ * Write model for creating/updating a provider and for the standalone connection test. Carries the
+ * raw API key (request bodies only — never serialized back to the client).
+ */
+public record ProviderForm(
+        String name,
+        String provider,
+        String model,
+        String apiKey,
+        String baseUrl) {
+
+    public ProviderConfig toConfig() {
+        return new ProviderConfig(provider, apiKey, baseUrl, model);
+    }
+}

app/src/main/java/ai/javaclaw/providers/api/SettingsController.java

@@ -0,0 +1,17 @@
+package ai.javaclaw.providers.api;
+
+import org.springframework.stereotype.Controller;
+import org.springframework.web.bind.annotation.GetMapping;
+
+/**
+ * Serves the post-onboarding settings pages. The Subagents page is a thin shell that talks to
+ * {@link SubagentController} (and reads provider names from {@link ProviderController}) via fetch.
+ */
+@Controller
+public class SettingsController {
+
+    @GetMapping("/settings/agents")
+    public String agents() {
+        return "settings/agents";
+    }
+}