agentnode-sdk 0.14.0__tar.gz → 0.16.0__tar.gz

{agentnode_sdk-0.14.0 → agentnode_sdk-0.16.0}/CHANGELOG.md

@@ -1,5 +1,93 @@
 # Changelog
 
+## 0.16.0 — Registry providers in auth CLI and setup wizard
+
+### Added
+
+- **`agentnode auth status` now surfaces all registry providers** — OpenAI,
+  Anthropic, OpenRouter, DeepSeek, Mistral, Qwen, Gemini — with their storage
+  backend and effective source, plus **Ollama as a local keyless provider**
+  (shown as selected/configured/not selected instead of "missing"). Custom
+  providers configured under `llm.providers.<name>` appear automatically.
+- **`agentnode auth test` supports the registry providers.** Compatible
+  providers are validated with a free, no-completion `GET {base_url}/models`
+  probe; `agentnode auth test ollama` is a keyless reachability check
+  (exit 0 reachable, exit 3 unreachable — never "rejected", and it never
+  starts Ollama). Custom configured endpoints can be tested the same way.
+- **The setup wizard lists all registry providers**, grouped for readability
+  (Recommended / More / Local), with Skip remaining the default. Selecting
+  Ollama never asks for an API key — it sets `llm.default_provider` through
+  the wizard's normal save step.
+- Additive `vendor` field in host-side LLM bindings: logs and tooling can now
+  show the real provider name; the protocol discriminator used by the broker
+  is unchanged.
+
+### Changed
+
+- The auth CLI and the setup wizard now use the provider registry as their
+  single source of truth — no hardcoded provider lists or environment
+  variable names remain in those surfaces.
+- OpenRouter keeps its dedicated `/auth/key` validation path (its `/models`
+  endpoint is unauthenticated and validates nothing).
+
+### Hardened
+
+- Provider response bodies are never printed (they can echo key fragments);
+  keys are never printed, logged, or exposed in exceptions.
+- Ollama is never started or probed automatically — only an explicit
+  `agentnode auth test ollama` performs a localhost reachability check.
+- The `vendor` field stays host-side and does not change the broker/sandbox
+  wire shape.
+
+### BREAKING / Upgrade Notes
+
+- None. All changes are additive; existing `auth` and `setup` flows behave
+  identically for the previously supported providers.
+
+## 0.15.0 — Generic OpenAI-compatible LLM providers
+
+### Added
+
+- **Generic OpenAI-compatible provider registry.** The LLM runtime can now
+  bind any endpoint that speaks the OpenAI-compatible protocol. Custom
+  endpoints are plain config entries — `llm.providers.<name>` with
+  `base_url`, `model`, and optionally `api_key_env`/`requires_key` — no code
+  changes needed per provider.
+- **Built-in presets** for OpenRouter, DeepSeek, Mistral, Qwen, Gemini
+  (Google's OpenAI-compatible endpoint) and Ollama, each with the canonical
+  base URL, API-key environment variable, and a sensible default model
+  (overridable via `llm.providers.<name>.model`).
+- **Ollama as a key-free local provider** — the first agent path with no
+  account and no per-token cost. Opt-in only: select it explicitly with
+  `agentnode config set llm.default_provider ollama` (or configure it under
+  `llm.providers`); AgentNode never probes or binds it by surprise.
+- Per-provider credentials: each provider's environment variable (e.g.
+  `DEEPSEEK_API_KEY`, `GEMINI_API_KEY`) and stored vault credentials both
+  work; the environment always overrides the stored key.
+
+### Changed
+
+- The OpenRouter binding now goes through the shared provider registry
+  (same behavior, including the namespaced default model — one code path
+  instead of a special case).
+- The sandboxed-agent LLM broker automatically inherits every compatible
+  provider: keys stay host-side, the container still sees only RPC
+  completions, and the C1/C2 access policy applies unchanged.
+
+### Hardened
+
+- No provider keys in logs or error messages (client failures are reported
+  by exception type only).
+- A custom provider without a configured model is skipped instead of
+  guessing — a wrong default model would fail confusingly at call time.
+- Keyless providers are never attempted unless explicitly selected or
+  configured.
+
+### BREAKING / Upgrade Notes
+
+- None. Existing OpenAI/Anthropic setups (env vars, vault, per-agent config)
+  behave identically; the new providers are purely additive.
+
 ## 0.14.0 — Setup wizard: guided credentials + sandbox onboarding
 
 ### Added

{agentnode_sdk-0.14.0 → agentnode_sdk-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentnode-sdk
-Version: 0.14.0
+Version: 0.16.0
 Summary: Python SDK for AgentNode — the open upgrade and discovery infrastructure for AI agents.
 Project-URL: Homepage, https://agentnode.net
 Project-URL: Repository, https://github.com/agentnode-ai/agentnode

{agentnode_sdk-0.14.0 → agentnode_sdk-0.16.0}/agentnode_sdk/__init__.py

@@ -38,7 +38,7 @@ from agentnode_sdk.runtime import AgentNodeRuntime
 Client = AgentNodeClient
 ToolError = AgentNodeToolError
 
-__version__ = "0.14.0"
+__version__ = "0.16.0"
 __all__ = [
     "AgentNode",
     "AsyncAgentNode",

{agentnode_sdk-0.14.0 → agentnode_sdk-0.16.0}/agentnode_sdk/cli/auth.py

@@ -10,7 +10,6 @@ import os
 import sys
 
 from agentnode_sdk.credential_store import (
-    LLM_PROVIDER_ENV,
     has_credential,
     list_credentials,
     load_credentials,
@@ -30,17 +29,28 @@ def _storage_short(storage: str) -> str:
     return "OS keychain" if storage == "keyring" else "plaintext file"
 
 
-def _llm_effective_source(provider: str) -> tuple[str | None, str]:
+def _host_config() -> dict:
+    try:
+        from agentnode_sdk.config import load_config
+        return load_config() or {}
+    except Exception:
+        return {}
+
+
+def _llm_effective_source(provider: str, host_config: dict | None = None) -> tuple[str | None, str]:
     """(effective key or None, human-readable source) for an LLM provider.
 
     Mirrors the runtime's resolution: env (incl. ~/.agentnode/.env) overrides
-    the stored credential. Uses metadata only for the stored check here —
+    the stored credential. Env var names come from the provider REGISTRY
+    (single source of truth). Uses metadata only for the stored check here —
     the real keychain read happens in ``auth test``."""
+    from agentnode_sdk.llm_providers import resolve_provider_spec
     from agentnode_sdk.runtimes.agent_runner import _load_agentnode_env
     _load_agentnode_env()
 
-    env_var = LLM_PROVIDER_ENV[provider]
-    env_key = os.environ.get(env_var) or None
+    spec = resolve_provider_spec(provider, host_config) or {}
+    env_var = spec.get("api_key_env") or ""
+    env_key = (os.environ.get(env_var) or None) if env_var else None
     meta = load_credentials().get("providers", {}).get(provider)
     stored = isinstance(meta, dict)
     storage = (meta or {}).get("storage", "file")
@@ -54,6 +64,19 @@ def _llm_effective_source(provider: str) -> tuple[str | None, str]:
     return None, "not configured"
 
 
+def _registry_key_providers(host_config: dict | None) -> list[str]:
+    """Key-requiring providers from the registry (presets + custom config
+    entries), in stable registry order."""
+    from agentnode_sdk.llm_providers import known_provider_names, resolve_provider_spec
+
+    names: list[str] = []
+    for name in known_provider_names(host_config):
+        spec = resolve_provider_spec(name, host_config)
+        if spec and spec.get("requires_key", True):
+            names.append(name)
+    return names
+
+
 def _resolve_auth_type(provider: str) -> str:
     """Read auth_type from lockfile connector entry. Falls back to 'api_key'.
 
@@ -132,15 +155,25 @@ def cmd_auth_remove(provider: str) -> int:
 
 def cmd_auth_status() -> int:
     # --- LLM providers (host runtime / sandbox broker) -----------------------
+    host_cfg = _host_config()
     print()
     print(section("LLM Providers"))
     print(f"  {'Provider':<14}{'Status':<16}{'Effective source'}")
     print(f"  {'--------':<14}{'------':<16}{'----------------'}")
-    for provider in sorted(LLM_PROVIDER_ENV):
-        key, source = _llm_effective_source(provider)
+    for provider in _registry_key_providers(host_cfg):
+        key, source = _llm_effective_source(provider, host_cfg)
         configured = key is not None or source not in ("not configured",)
         status = "configured" if configured else "missing"
         print(f"  {provider:<14}{status:<16}{source}")
+    # ollama: keyless local provider — selection is config, not a credential
+    llm_cfg = host_cfg.get("llm") or {}
+    if llm_cfg.get("default_provider") == "ollama":
+        ollama_source = "selected via llm.default_provider"
+    elif "ollama" in (llm_cfg.get("providers") or {}):
+        ollama_source = "configured via llm.providers"
+    else:
+        ollama_source = "not selected — agentnode config set llm.default_provider ollama"
+    print(f"  {'ollama':<14}{'local (keyless)':<16}{ollama_source}")
     print(dim("  Env vars always override stored credentials. "
               "Test a key: agentnode auth test <provider>"))
 
@@ -183,61 +216,97 @@ def cmd_auth_status() -> int:
 
 
 # Free, cost-less validation endpoints (no completion call, no charge).
-# anthropic REQUIRES the anthropic-version header (a 400 without it would be
-# misread as a bad key); openrouter's /models is UNAUTHENTICATED (validates
-# nothing) — /auth/key is the correct probe.
-_TEST_REQUESTS = {
-    "openai": lambda key: (
+# GENERIC rule for OpenAI-compatible providers: GET {base_url}/models with a
+# Bearer token (authenticated on deepseek/mistral/qwen/gemini and most custom
+# endpoints). EXCEPTIONS: openai (official URL), anthropic (REQUIRES the
+# anthropic-version header — a 400 without it would be misread as a bad key),
+# openrouter (its /models is UNAUTHENTICATED, validates nothing — /auth/key is
+# the correct probe).
+_TEST_EXCEPTIONS = {
+    "openai": lambda key, spec: (
         "https://api.openai.com/v1/models",
         {"Authorization": f"Bearer {key}"},
     ),
-    "anthropic": lambda key: (
+    "anthropic": lambda key, spec: (
         "https://api.anthropic.com/v1/models",
         {"x-api-key": key, "anthropic-version": "2023-06-01"},
     ),
-    "openrouter": lambda key: (
+    "openrouter": lambda key, spec: (
         "https://openrouter.ai/api/v1/auth/key",
         {"Authorization": f"Bearer {key}"},
     ),
 }
 
 
+def _test_request(provider: str, key: str | None, spec: dict) -> tuple[str, dict] | None:
+    if provider in _TEST_EXCEPTIONS:
+        return _TEST_EXCEPTIONS[provider](key, spec)
+    base = (spec.get("base_url") or "").rstrip("/")
+    if not base:
+        return None  # no compat endpoint to probe
+    headers = {"Authorization": f"Bearer {key}"} if key else {}
+    return (base + "/models", headers)
+
+
 def cmd_auth_test(provider: str) -> int:
     """Validate the EFFECTIVE key for an LLM provider (env beats vault) via a
-    free endpoint. Exit codes: 0 valid / 1 rejected (401/403) / 2 not
-    configured or unsupported / 3 indeterminate (network/5xx — never reported
-    as invalid). Never prints the key (masked last-4 only) and never echoes
-    the provider's response body (it can contain key fragments)."""
+    free endpoint — registry-driven, so custom ``llm.providers`` entries work
+    too. Exit codes: 0 valid (key providers) / reachable (keyless) · 1
+    rejected (401/403, key providers only) · 2 not configured or unsupported ·
+    3 indeterminate (network/5xx — never reported as invalid; for keyless
+    providers this means unreachable). Never prints the key (masked last-4
+    only), never echoes provider response bodies (they can contain key
+    fragments), never starts anything."""
     provider = provider.lower().strip()
-    if provider not in _TEST_REQUESTS:
-        supported = ", ".join(sorted(_TEST_REQUESTS))
-        print(f"  auth test supports: {supported}", file=sys.stderr)
+    host_cfg = _host_config()
+    from agentnode_sdk.llm_providers import resolve_provider_spec
+    spec = resolve_provider_spec(provider, host_cfg)
+    if spec is None:
+        print(f"  Unknown provider '{provider}'. Known: see `agentnode auth status`; "
+              "custom endpoints go under llm.providers.<name>.", file=sys.stderr)
         return 2
 
-    key, source = _llm_effective_source(provider)
-    if key is None:
-        # No env override — resolve the stored credential (real keychain read).
-        from agentnode_sdk.credential_store import get_llm_api_key
-        key = get_llm_api_key(provider)
-    if not key:
-        print(f"\n  {provider}: not configured. Run `agentnode auth set {provider}`.\n")
+    requires_key = spec.get("requires_key", True)
+    if requires_key:
+        key, source = _llm_effective_source(provider, host_cfg)
+        if key is None:
+            # No env override — resolve the stored credential (real keychain read).
+            from agentnode_sdk.credential_store import get_llm_api_key
+            key = get_llm_api_key(provider)
+        if not key:
+            print(f"\n  {provider}: not configured. Run `agentnode auth set {provider}`.\n")
+            return 2
+        shown = f"{_masked(key)}, {source}"
+    else:
+        key, shown = None, "local (keyless)"
+
+    req = _test_request(provider, key, spec)
+    if req is None:
+        print(f"\n  {provider}: no endpoint to probe (no base_url configured).\n")
         return 2
+    url, headers = req
 
-    url, headers = _TEST_REQUESTS[provider](key)
     import httpx
     try:
         resp = httpx.get(url, headers=headers, timeout=10.0)
     except Exception:
-        print(f"\n  {provider} ({_masked(key)}, {source}): could not reach the "
-              "provider — key validity unknown.\n")
+        if not requires_key:
+            print(f"\n  {provider} ({shown}): could not reach {url} — "
+                  "is the local server (e.g. Ollama) running?\n")
+        else:
+            print(f"\n  {provider} ({shown}): could not reach the "
+                  "provider — key validity unknown.\n")
         return 3
     if resp.status_code == 200:
-        print(f"\n  {provider} ({_masked(key)}, {source}): key is valid.\n")
+        if requires_key:
+            print(f"\n  {provider} ({shown}): key is valid.\n")
+        else:
+            print(f"\n  {provider} ({shown}): endpoint is reachable.\n")
         return 0
-    if resp.status_code in (401, 403):
-        print(f"\n  {provider} ({_masked(key)}, {source}): key was rejected by "
+    if requires_key and resp.status_code in (401, 403):
+        print(f"\n  {provider} ({shown}): key was rejected by "
               f"the provider (HTTP {resp.status_code}).\n")
         return 1
-    print(f"\n  {provider} ({_masked(key)}, {source}): unexpected provider "
-          f"response (HTTP {resp.status_code}) — key validity unknown.\n")
+    print(f"\n  {provider} ({shown}): unexpected response "
+          f"(HTTP {resp.status_code}) — status unknown.\n")
     return 3

{agentnode_sdk-0.14.0 → agentnode_sdk-0.16.0}/agentnode_sdk/cli/setup_wizard.py

@@ -22,7 +22,14 @@ from agentnode_sdk.config import (
 )
 from agentnode_sdk.cli.output import bold, dim, kv, section
 
-_LLM_CHOICES = {"1": "openai", "2": "anthropic", "3": "openrouter"}
+# Key-provider menu (grouped for readability); choice 8 = ollama (keyless,
+# handled separately — never a key prompt), choice 9 = skip (the default).
+_LLM_CHOICES = {
+    "1": "openai", "2": "anthropic", "3": "openrouter",
+    "4": "deepseek", "5": "mistral", "6": "qwen", "7": "gemini",
+}
+_OLLAMA_CHOICE = "8"
+_SKIP_CHOICE = "9"
 
 
 def run_wizard() -> int:
@@ -59,15 +66,16 @@ def _store_llm_key(provider: str) -> str | None:
     import os
 
     from agentnode_sdk.cli.auth import _masked, _storage_short, cmd_auth_test
-    from agentnode_sdk.credential_store import LLM_PROVIDER_ENV, set_credential
+    from agentnode_sdk.credential_store import set_credential
 
-    env_var = LLM_PROVIDER_ENV[provider]
+    from agentnode_sdk.llm_providers import resolve_provider_spec
+    env_var = (resolve_provider_spec(provider) or {}).get("api_key_env") or ""
     try:
         from agentnode_sdk.runtimes.agent_runner import _load_agentnode_env
         _load_agentnode_env()
     except Exception:
         pass
-    env_val = (os.environ.get(env_var) or "").strip()
+    env_val = (os.environ.get(env_var) or "").strip() if env_var else ""
 
     token = ""
     if env_val:
@@ -101,9 +109,11 @@ def _store_llm_key(provider: str) -> str | None:
     return _storage_short(storage)
 
 
-def _credentials_screen() -> list[tuple[str, str]]:
-    """Screen 5: LLM credentials (optional, default = skip). Returns the
-    (provider, storage label) pairs stored in this run."""
+def _credentials_screen(cfg: dict) -> list[tuple[str, str]]:
+    """Screen 5: LLM credentials (optional, default = skip). Key providers
+    come from the registry-backed menu; ollama is a keyless CONFIG selection
+    (written to the wizard cfg, persisted only via the normal Save confirm).
+    Returns the (provider, storage label) pairs selected in this run."""
     import sys
 
     print()
@@ -120,19 +130,38 @@ def _credentials_screen() -> list[tuple[str, str]]:
         return []
 
     stored: list[tuple[str, str]] = []
+    all_options = list(_LLM_CHOICES) + [_OLLAMA_CHOICE, _SKIP_CHOICE]
     while True:
-        print("  [1] OpenAI   [2] Anthropic   [3] OpenRouter   [4] Skip for now")
-        c = _choice("  Choice", ["1", "2", "3", "4"], "4")
-        if c == "4":
+        print("  Recommended:  [1] OpenAI    [2] Anthropic   [3] OpenRouter")
+        print("  More:         [4] DeepSeek  [5] Mistral     [6] Qwen      [7] Gemini")
+        print("  Local:        [8] Ollama — keyless, requires a running Ollama")
+        print("  [9] Skip for now")
+        c = _choice("  Choice", all_options, _SKIP_CHOICE)
+        if c == _SKIP_CHOICE:
             break
-        provider = _LLM_CHOICES[c]
-        if any(p == provider for p, _ in stored):
-            print(f"  {provider} already added in this run.")
+        if c == _OLLAMA_CHOICE:
+            # keyless local provider: a config selection, NOT a credential.
+            # No key prompt, no probing, no starting anything.
+            if any(p == "ollama" for p, _ in stored):
+                print("  ollama already selected in this run.")
+            else:
+                print("  Ollama runs models locally — no API key, no per-token cost.")
+                print(dim("  Requires a running Ollama (https://ollama.com); the wizard"))
+                print(dim("  does not start or probe it."))
+                use = _prompt("  Use Ollama as your default LLM provider? [Y/n]: ", "y")
+                if use.lower() != "n":
+                    cfg["llm"]["default_provider"] = "ollama"
+                    stored.append(("ollama", "local, keyless"))
+                    print(dim("  Selected. Test later with `agentnode auth test ollama`."))
         else:
-            label = _store_llm_key(provider)
-            if label is not None:
-                stored.append((provider, label))
-        if len(stored) >= len(_LLM_CHOICES):
+            provider = _LLM_CHOICES[c]
+            if any(p == provider for p, _ in stored):
+                print(f"  {provider} already added in this run.")
+            else:
+                label = _store_llm_key(provider)
+                if label is not None:
+                    stored.append((provider, label))
+        if len(stored) >= len(_LLM_CHOICES) + 1:
             break
         more = _prompt("  Add another provider? [y/N]: ", "n")
         if more.lower() != "y":
@@ -283,8 +312,9 @@ def _wizard_flow() -> dict | None:
         c = _choice("  Choice", ["1", "2", "3"], "1")
         cfg["trust"]["minimum_trust_level"] = {"1": "verified", "2": "trusted", "3": "curated"}[c]
 
-    # Screen 5: LLM credentials (optional — UX-3A)
-    stored_providers = _credentials_screen()
+    # Screen 5: LLM credentials (optional — UX-3A; provider list from the
+    # registry incl. keyless ollama — Endpoint-B)
+    stored_providers = _credentials_screen(cfg)
 
     # Screen 6: Local sandbox (UX-3B)
     sandbox_status, image_missing = _sandbox_screen(cfg)

{agentnode_sdk-0.14.0 → agentnode_sdk-0.16.0}/agentnode_sdk/config.py

@@ -46,6 +46,7 @@ DEFAULTS: dict[str, Any] = {
     },
     "llm": {
         "default_provider": "openai",
+        "providers": {},
     },
 }
 
@@ -68,7 +69,10 @@ VALID_VALUES: dict[str, tuple[str, ...]] = {
     "guard.compute": ("allow", "prompt", "deny"),
     "guard.unknown": ("allow", "prompt", "deny"),
     "agent_sandbox.enabled": ("true", "false"),
-    "llm.default_provider": ("openai", "anthropic", "openrouter"),
+    "llm.default_provider": (
+        "openai", "anthropic", "openrouter", "deepseek", "mistral", "qwen",
+        "gemini", "ollama",
+    ),
 }
 
 
@@ -160,6 +164,10 @@ def _merge_defaults(data: dict) -> dict[str, Any]:
         for k in ("default_provider",):
             if k in data["llm"]:
                 cfg["llm"][k] = data["llm"][k]
+        # llm.providers holds nested endpoint specs (base_url/model/...) —
+        # pass through verbatim, like agent_sandbox.llm above.
+        if isinstance(data["llm"].get("providers"), dict):
+            cfg["llm"]["providers"] = data["llm"]["providers"]
     return cfg
 
 

{agentnode_sdk-0.14.0 → agentnode_sdk-0.16.0}/agentnode_sdk/credential_store.py

@@ -47,12 +47,19 @@ CREDENTIALS_FILE = "credentials.json"
 CURRENT_VERSION = 1
 
 # Canonical env vars for the LLM providers the host runtime understands.
+# DERIVED from the provider registry (single source of truth, Endpoint-B).
 # Env always OVERRIDES the stored credential (explicit/CI intent wins).
-LLM_PROVIDER_ENV: dict[str, str] = {
-    "openai": "OPENAI_API_KEY",
-    "anthropic": "ANTHROPIC_API_KEY",
-    "openrouter": "OPENROUTER_API_KEY",
-}
+def _derive_llm_provider_env() -> dict[str, str]:
+    from agentnode_sdk.llm_providers import KNOWN_PROVIDERS
+
+    return {
+        name: spec["api_key_env"]
+        for name, spec in KNOWN_PROVIDERS.items()
+        if spec.get("api_key_env")
+    }
+
+
+LLM_PROVIDER_ENV: dict[str, str] = _derive_llm_provider_env()
 
 # One keychain item per provider: service "agentnode:<provider>", a fixed
 # username. (NOT service="agentnode" + username=provider — Windows WinVault

agentnode_sdk-0.16.0/agentnode_sdk/llm_providers.py

@@ -0,0 +1,116 @@
+"""OpenAI-compatible LLM provider registry (Endpoint-A).
+
+One shared source of truth for the LLM endpoints AgentNode can bind: built-in
+presets (OpenRouter, DeepSeek, Mistral, Qwen, Ollama — plus the official
+OpenAI/Anthropic entries) and user-defined entries/overrides from
+``llm.providers.<name>`` in ~/.agentnode/config.json.
+
+The runtime (``_auto_detect_llm``) builds standard OpenAI-compatible bindings
+from these specs, so the host LLM broker — and therefore sandboxed agents —
+inherit every provider automatically, with the key staying host-side and no
+broker/sandbox change.
+
+Compat presets MUST carry a default model: the broker's bare OpenAI default
+("gpt-4o-mini") would 404 on most compatible endpoints. ``requires_key:
+False`` providers (Ollama) are bound only on explicit selection — never by
+probing.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+# Built-in presets. base_url=None means the provider SDK's official endpoint.
+# default_model="" lets the broker pick its own official default.
+KNOWN_PROVIDERS: dict[str, dict[str, Any]] = {
+    "openai": {
+        "base_url": None,
+        "api_key_env": "OPENAI_API_KEY",
+        "default_model": "",
+        "requires_key": True,
+    },
+    "anthropic": {
+        "base_url": None,
+        "api_key_env": "ANTHROPIC_API_KEY",
+        "default_model": "",
+        "requires_key": True,
+    },
+    "openrouter": {
+        "base_url": "https://openrouter.ai/api/v1",
+        "api_key_env": "OPENROUTER_API_KEY",
+        "default_model": "openai/gpt-4o-mini",
+        "requires_key": True,
+    },
+    "deepseek": {
+        "base_url": "https://api.deepseek.com/v1",
+        "api_key_env": "DEEPSEEK_API_KEY",
+        "default_model": "deepseek-chat",
+        "requires_key": True,
+    },
+    "mistral": {
+        "base_url": "https://api.mistral.ai/v1",
+        "api_key_env": "MISTRAL_API_KEY",
+        "default_model": "mistral-small-latest",
+        "requires_key": True,
+    },
+    "qwen": {
+        "base_url": "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
+        "api_key_env": "DASHSCOPE_API_KEY",
+        "default_model": "qwen-plus",
+        "requires_key": True,
+    },
+    "gemini": {
+        # Google's own OpenAI-compatible endpoint (trailing slash required).
+        "base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
+        "api_key_env": "GEMINI_API_KEY",
+        "default_model": "gemini-2.0-flash",
+        "requires_key": True,
+    },
+    "ollama": {
+        # key-free local inference: the first agent path with no account and
+        # no per-token cost. Bound ONLY when explicitly selected (no probing).
+        "base_url": "http://localhost:11434/v1",
+        "api_key_env": "OLLAMA_API_KEY",
+        "default_model": "llama3.2",
+        "requires_key": False,
+    },
+}
+
+_SPEC_KEYS = ("base_url", "api_key_env", "default_model", "requires_key")
+
+
+def _config_providers(host_config: dict | None) -> dict:
+    llm = (host_config or {}).get("llm") or {}
+    providers = llm.get("providers")
+    return providers if isinstance(providers, dict) else {}
+
+
+def resolve_provider_spec(name: str, host_config: dict | None = None) -> dict | None:
+    """Effective spec for ``name`` = preset merged with the config override
+    (``llm.providers.<name>``), or None for an unknown name without a config
+    entry. ``model`` is accepted as a friendlier config alias for
+    ``default_model``."""
+    name = (name or "").lower().strip()
+    preset = KNOWN_PROVIDERS.get(name)
+    override = _config_providers(host_config).get(name)
+    if preset is None and not isinstance(override, dict):
+        return None
+
+    spec: dict[str, Any] = dict(preset) if preset else {
+        "base_url": None, "api_key_env": "", "default_model": "", "requires_key": True,
+    }
+    if isinstance(override, dict):
+        for k in _SPEC_KEYS:
+            if k in override:
+                spec[k] = override[k]
+        if "model" in override:
+            spec["default_model"] = override["model"]
+    return spec
+
+
+def known_provider_names(host_config: dict | None = None) -> list[str]:
+    """Preset names first (stable order), then custom config-defined names."""
+    names = list(KNOWN_PROVIDERS)
+    for n in _config_providers(host_config):
+        if n not in names:
+            names.append(n)
+    return names