Fixes: improve documentation consistency, add API key redaction in Debug output, and enhance robustness of models-dev-update binary

Author: Sewer56

src/llm-coding-tools-agents/README.md

@@ -44,6 +44,9 @@ permission:
 Prompt body goes here...
 ```
 
+**Note**: Provider selection is driven by the `provider:` prefix, not by URL inspection. OpenAI-compatible endpoints should still use `openai:` with a custom base URL provided via provider overrides.
+
+
 ### Mode Options
 
 The `mode` field controls how the agent can be invoked:
@@ -72,7 +75,7 @@ See `examples/serdesai-agents.rs` for the complete example.
 
 ```rust,no_run
 use llm_coding_tools_agents::{AgentCatalog, AgentLoader, Ruleset, Rule, PermissionAction};
-use llm_coding_tools_serdesai::{AgentDefaults, AgentRegistryBuilder, TaskTool, default_tools, TodoState};
+use llm_coding_tools_serdesai::{AgentDefaults, AgentRegistryBuilder, ProviderOverrides, TaskTool, default_tools, TodoState};
 use std::sync::Arc;
 
 // 1) Load agent configs
@@ -82,6 +85,8 @@ AgentLoader::new().add_directory(&mut catalog, "/home/user/.opencode")?;
 // 2) Build framework registry
 let defaults = AgentDefaults {
     model: "openai:hf:zai-org/GLM-4.7".into(),
+    model_resolver: None,
+    provider_overrides: ProviderOverrides::new(),
     api_key: Some(std::env::var("OPENAI_API_KEY").unwrap_or_default()),
     base_url: Some("https://api.synthetic.new/openai/v1".into()),
     temperature: None,

src/llm-coding-tools-agents/benches/fixtures/orchestrator-quality-gate-gpt5.md

@@ -73,7 +73,7 @@ These are areas where the implementer was uncertain — validate the approach or
 ## 7) Review tests
 - Tests: basic → ensure basic tests exist for new functionality and run tests
 - Tests: no → do not run tests; flag any found tests as overengineering
-- Check whole test files, not just diffs
+- Check the entire content of changed test files, not just the modified portions
 - WARNING IF [MEDIUM]: newly added tests duplicate existing test coverage without adding value (different context, edge case, or scenario)
 - WARNING IF [MEDIUM]: tests have significant duplication that would benefit from parameterization without sacrificing readability
 - FAIL IF: tests are non-deterministic (real I/O, time, network without mocking/seeding)

src/llm-coding-tools-core/README.md

@@ -15,7 +15,7 @@ This crate provides the foundational building blocks for coding tool implementat
 Task tools (for agent-to-agent delegation) are implemented as registry-driven tools in the framework-specific crates:
 - SerdesAI: See `llm-coding-tools-serdesai::TaskTool` (README for setup example)
 
-The serdesAI framework uses a unified flow: load agent configs into `AgentCatalog`, build a framework-specific registry, then construct a `TaskTool` with the registry and permission rules.
+The SerdesAI framework uses a unified flow: load agent configs into `AgentCatalog`, build a framework-specific registry, then construct a `TaskTool` with the registry and permission rules.
 
 ## Features
 

src/llm-coding-tools-models-dev/src/bin/models-dev-update.rs

@@ -56,10 +56,11 @@ struct ProviderSnapshot {
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let manifest_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
     let output = manifest_dir.join("data/models.dev.min.json");
+    if let Some(parent) = output.parent() {
+        fs::create_dir_all(parent).await?;
+    }
 
-    let client = Client::builder()
-        .timeout(Duration::from_secs(30))
-        .build()?;
+    let client = Client::builder().timeout(Duration::from_secs(30)).build()?;
     let response = client
         .get("https://models.dev/api.json")
         .send()

src/llm-coding-tools-serdesai/Cargo.toml

@@ -22,7 +22,16 @@ llm-coding-tools-models-dev = { version = "0.1.0", path = "../llm-coding-tools-m
 
 # serdes-ai provides Tool trait, ToolDefinition, RunContext
 serdes-ai = "0.1"
-serdes-ai-models = { version = "0.1", features = ["openai"] }
+serdes-ai-models = { version = "0.1", features = [
+  "openai",
+  "anthropic",
+  "groq",
+  "mistral",
+  "google",
+  "cohere",
+  "openrouter",
+  "huggingface",
+] }
 serdes-ai-streaming = "0.1"
 futures = "0.3"
 

src/llm-coding-tools-serdesai/README.md

@@ -98,13 +98,53 @@ Setup requires three steps:
 
 The example file shows the complete setup.
 
-**Note**: The `default_tools` function returns cloneable `ToolCatalogEntry` items that can be reused for building multiple agents. The `AgentRegistryBuilder` uses these to construct tool descriptions and filter based on agent permissions. The `deps` parameter is passed to registry agents at invocation time.
+**Note**: The `default_tools` function (defined in `examples/serdesai-agents.rs`) returns cloneable `ToolCatalogEntry` items that can be reused for building multiple agents. The `AgentRegistryBuilder` uses these to construct tool descriptions and filter based on agent permissions. The `deps` parameter is passed to registry agents at invocation time.
 
 Other tools: `BashTool`, `WebFetchTool`, `TodoReadTool`, `TodoWriteTool`.
 Use `SystemPromptBuilder` to track tools and pass `pb.build()` to `.system_prompt()`. Set `working_directory()` so the environment section is populated.
 Use `AgentBuilderExt::tool()` to add tools that implement `Tool<Deps>` to the agent.
 Context strings are re-exported in `llm_coding_tools_serdesai::context` (e.g., `BASH`, `READ_ABSOLUTE`).
 
+### models.dev Resolver
+
+Use the models.dev catalog to resolve per-provider API keys/base URLs:
+
+```rust,no_run
+# use std::env;
+# use llm_coding_tools_models_dev::ModelsDevCatalog;
+# use llm_coding_tools_serdesai::{AgentDefaults, ModelsDevResolver, ProviderOverride, ProviderOverrides};
+# fn main() -> Result<(), Box<dyn std::error::Error>> {
+let catalog = ModelsDevCatalog::load_shared_cache_or_bundled()?.catalog;
+let overrides = ProviderOverrides::new().insert_override(
+    "openai",
+    ProviderOverride { api_key: Some(env::var("OPENAI_API_KEY")?), base_url: None, endpoint_env: None },
+);
+let resolver = ModelsDevResolver::new(Some(catalog), overrides.clone());
+
+let defaults = AgentDefaults {
+    model: "openai:gpt-4o".into(),
+    model_resolver: Some(resolver),
+    provider_overrides: overrides,
+    api_key: None,
+    base_url: None,
+    temperature: None,
+    top_p: None,
+    options: Default::default(),
+};
+# Ok(())
+# }
+```
+
+**OpenAI-compatible providers**: serdesAI does not infer providers from base URLs. Use an `openai:` model spec and set a provider-specific `base_url` via overrides.
+
+**Reasoning models**: If you need `OpenAIResponsesModel` for `o1`, `o3`, or `gpt-5`, construct it directly instead of using `ModelConfig`.
+
+**OpenRouter/HuggingFace**: `build_model_with_config` does not support these providers; use `OpenRouterModel::new` or `HuggingFaceModel::new` directly.
+OpenRouter does not support base URL overrides; resolver should not surface `base_url` for this provider.
+
+**Resolver fallback behavior**: When no resolver is provided, the registry attempts to load the models.dev catalog from the shared cache or bundled snapshot. If that fails, it falls back to an empty catalog (meaning only explicit specs are usable and no provider mapping occurs).
+
+
 ### Migration from Legacy Task APIs
 
 The previous task setup using `TaskToolCore` and `SubagentRegistry` has been replaced with the registry-driven flow. Key changes:

src/llm-coding-tools-serdesai/examples/serdesai-agents.rs

@@ -13,13 +13,16 @@
 
 use futures::StreamExt;
 use llm_coding_tools_agents::{AgentCatalog, AgentLoader, PermissionAction, Rule, Ruleset};
+use llm_coding_tools_models_dev::ModelsDevCatalog;
 use llm_coding_tools_serdesai::agent_ext::AgentBuilderExt;
 use llm_coding_tools_serdesai::{
-    AgentDefaults, AgentRegistryBuilder, AllowedPathResolver, SystemPromptBuilder, TaskTool,
-    TodoState, default_tools,
+    AgentDefaults, AgentRegistryBuilder, AllowedPathResolver, ModelResolver, ModelsDevResolver,
+    ProviderOverride, ProviderOverrides, SystemPromptBuilder, TaskTool, TodoState, default_tools,
 };
 use serdes_ai::agent::ModelConfig;
 use serdes_ai::prelude::*;
+use serdes_ai_models::huggingface::HuggingFaceModel;
+use serdes_ai_models::openrouter::OpenRouterModel;
 use std::fmt::Write;
 use std::sync::Arc;
 
@@ -48,7 +51,7 @@ async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
     // Set OPENCODE_USE_ALLOWED environment variable to enable sandboxed (allowed) tools.
     // Without the env var, tools use absolute paths with no restrictions.
     let use_allowed = std::env::var("OPENCODE_USE_ALLOWED").is_ok();
-    let resolver = if use_allowed {
+    let allowed_path_resolver = if use_allowed {
         Some(AllowedPathResolver::new([
             std::env::current_dir()?,
             std::env::temp_dir(),
@@ -62,26 +65,41 @@ async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
     // Use default_tools to create a catalog of cloneable tools.
     // When use_allowed is true, tools are sandboxed to allowed directories.
     // When false, tools can access any path.
-    let tools = default_tools(true, resolver.clone(), TodoState::new());
+    let tools = default_tools(true, allowed_path_resolver.clone(), TodoState::new());
+
+    // === Load models.dev catalog and build model resolver ===
+    //
+    let models_dev_catalog = ModelsDevCatalog::load_shared_cache_or_bundled()?.catalog;
+    let provider_overrides = ProviderOverrides::new().insert_override(
+        "openai",
+        ProviderOverride {
+            api_key: Some(get_openai_api_key()),
+            base_url: Some(OPENAI_BASE_URL.to_string()),
+            endpoint_env: None,
+        },
+    );
+    let model_resolver =
+        ModelsDevResolver::new(Some(models_dev_catalog), provider_overrides.clone());
 
     // === Build registry ===
     //
     // AgentDefaults specifies the default model and sampling parameters
     // for agents that don't override them in their config.
     let defaults = AgentDefaults {
         model: OPENAI_MODEL.to_string(),
-        api_key: Some(get_openai_api_key()),
-        base_url: Some(OPENAI_BASE_URL.to_string()),
+        model_resolver: Some(model_resolver.clone()),
+        provider_overrides,
+        api_key: None,
+        base_url: None,
         temperature: None,
         top_p: None,
         options: Default::default(),
     };
 
-    // Build the registry from the catalog and tool catalog.
+    // Build the registry from the agent catalog and tool catalog.
     // The registry prebuilds all agents with their allowed tools from the catalog.
     //
-    // Note: For OpenAI models with "openai:" prefix, AgentBuilder::from_model
-    // will resolve the model using environment variables like OPENAI_API_KEY.
+    // Note: The model resolver is used to resolve model specs into per-provider settings.
     let registry = AgentRegistryBuilder::<()>::new(defaults, tools).build(&catalog)?;
 
     // === Task tool permissions (allow Task for the single subagent only) ===
@@ -98,21 +116,62 @@ async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
     // Build a system prompt that includes working directory and optionally allowed paths.
     let mut pb = SystemPromptBuilder::new()
         .working_directory(std::env::current_dir()?.display().to_string());
-    if let Some(ref resolver) = resolver {
+    if let Some(ref resolver) = allowed_path_resolver {
         pb = pb.allowed_paths(resolver);
     }
 
     // Create the primary agent with ONLY the Task tool (forces delegation to subagent).
     //
-    // Note: For OpenAI models with "openai:" prefix, use ModelConfig to set custom base URL.
-    let agent = AgentBuilder::<(), String>::from_config(
-        ModelConfig::new(OPENAI_MODEL)
-            .with_api_key(get_openai_api_key())
-            .with_base_url(OPENAI_BASE_URL),
-    )?
-    .tool(pb.track(task_tool))
-    .system_prompt(pb.build())
-    .build();
+    // Resolve the primary agent's model spec using the model resolver.
+    let resolved_primary = model_resolver.resolve(OPENAI_MODEL)?;
+    let (spec_provider, resolved_model_id) = resolved_primary
+        .spec
+        .split_once(':')
+        .unwrap_or(("", resolved_primary.spec.as_str()));
+    let resolved_provider = if resolved_primary.provider_id.is_empty() {
+        spec_provider
+    } else {
+        resolved_primary.provider_id.as_str()
+    };
+
+    // Branch on resolved provider to use appropriate constructor (same logic as registry)
+    let builder = match resolved_provider {
+        "openrouter" => {
+            let model = if let Some(api_key) = resolved_primary.api_key.as_deref() {
+                OpenRouterModel::new(resolved_model_id, api_key)
+            } else {
+                OpenRouterModel::from_env(resolved_model_id)?
+            };
+            // Note: OpenRouterModel does not support base URL overrides.
+            AgentBuilder::<(), String>::new(model)
+        }
+        "huggingface" => {
+            let mut model = if let Some(api_key) = resolved_primary.api_key.as_deref() {
+                HuggingFaceModel::new(resolved_model_id, api_key)
+            } else {
+                HuggingFaceModel::from_env(resolved_model_id)?
+            };
+            if let Some(endpoint) = resolved_primary.base_url.as_deref() {
+                model = model.with_endpoint(endpoint);
+            }
+            AgentBuilder::<(), String>::new(model)
+        }
+        _ => {
+            let mut model_config = ModelConfig::new(&resolved_primary.spec);
+            if let Some(api_key) = resolved_primary.api_key.clone() {
+                model_config = model_config.with_api_key(api_key);
+            }
+            if let Some(base_url) = resolved_primary.base_url.clone() {
+                model_config = model_config.with_base_url(base_url);
+            }
+            AgentBuilder::<(), String>::from_config(model_config)?
+        }
+    };
+
+    let agent = builder
+        .tool(pb.track(task_tool))
+        .system_prompt(pb.build())
+        .build();
 
     // === Print tool info ===
     println!("=== Agent Ready ({} tools) ===", agent.tools().len());