[Feature]: refactor: Unify providers architecture and reqwest client management

[NiuBlibing]

Summary

refactor providers and reqwest builder

Problem statement

he current providers module suffers from inconsistent usage of reqwest and model construction parameters, with significant code duplication that leads to fragmented configuration. The main issues are:

• Inconsistent reqwest usage: The project mixes reqwest::blocking and async modes. Each provider constructs its own client independently, with timeout, proxy, and header configuration scattered across the codebase. There is no unified entry point and no global client reuse.
• Redundant provider constructors: Each provider exposes multiple semantic constructors (e.g. create_provider_with_xxx, create_provider_with_yyy), with inconsistent parameter passing. Adding a new field requires changes in many places.
• Inconsistent base configuration: Support for user-customizable settings (timeout, vision capability, default max_tokens, etc.) varies from one provider to another — some support a given option, others don't. This makes the module hard to maintain and extend.

As a result, adding a new provider means reinventing the wheel, and adjusting shared behavior (e.g. unifying proxy or timeout policy) requires touching multiple files and is error-prone.

Proposed solution

1. Migrate reqwest blocking → async

• Replace every remaining reqwest::blocking::Client in providers and its call chain with reqwest::Client (async).
• Update callers to async fn + .await, using tokio::spawn / futures::try_join! where concurrency helps.
• Remove implicit dependencies on a blocking runtime, eliminating the risk of nested blocking calls inside existing async contexts.

2. Unified provider configuration via a config struct + Default

Introduce a single provider configuration struct paired with the Default pattern:

#[derive(Debug, Clone)]
pub struct ProviderConfig {
    pub base_url: String,
    pub api_key: Option<String>,
    pub model: String,
    pub timeout: Duration,
    pub max_tokens: Option<u32>,
    pub supports_vision: bool,
    pub extra_headers: HeaderMap,
    // ...
}

impl Default for ProviderConfig { /* sensible defaults */ }

Associated changes:

• All providers are constructed through a single Provider::new(config: ProviderConfig).
• Remove semantic constructors such as create_provider_with_timeout, create_provider_with_vision, create_provider_with_proxy, etc. Callers override fields via ProviderConfig { timeout: ..., ..Default::default() }.
• Lift shared capabilities (vision support, max_tokens, timeout, etc.) into the provider trait layer so that behavior is consistent across channels.

3. Unified reqwest client entry point

Introduce a new http_client module as the single entry point for reqwest clients across the entire project:

• Provide an HttpClientBuilder supporting timeout, headers, proxy, user_agent, danger_accept_invalid_certs, etc.

• Cache clients globally keyed by their configuration (e.g. OnceCell<HashMap<ClientKey, reqwest::Client>> or moka), so identical configs reuse the same client and connection pool instead of rebuilding one per request.

• Expose a simple API, for example:

  let client = http_client::get_or_build(ClientConfig {
      timeout: Duration::from_secs(30),
      proxy: Some(proxy_url),
      ..Default::default()
  })?;

• Replace every direct reqwest::Client::builder() call under providers with a call through this entry point.

Non-goals / out of scope

• Extism-related code: The Extism plugin mechanism and its internal HTTP calls are not touched in this refactor.
• Health check / liveness probes: Rewriting the probing logic is out of scope. It should only be kept compatible with the new client entry point without behavior changes.

Alternatives considered

No response

Acceptance criteria

No response

Architecture impact

No response

Risk and rollback

No response

Breaking change?

No

Data hygiene checks

• I removed personal/sensitive data from examples, payloads, and logs.
• I used neutral, project-focused wording and placeholders.

[singlerider]

@WareWolf-MoonWall Can you evaluate this against our RFCs? I see some DRY ideas in here. Maybe there's a way to do this without breaking compatibility?

[jokemanfire]

If consider change the provider and agent to this repo ?
Reduce reinventing the wheel.

[WareWolf-MoonWall]

Thanks for the ping, @singlerider.

@NiuBlibing — appreciate the detailed writeup. The problem statement is accurate: the scattered reqwest client construction, the inconsistent provider constructors, and the blocking/async mix are real maintenance friction. You've clearly spent time looking at the codebase and the DRY instincts here are sound.

That said, I want to be honest about where we are and why the timing matters.

We're in the middle of an active architectural shift right now — the workspace split, CI stabilisation, the foundations layer, and the docs restructure are all in-flight or just landed. The goal of all of that work is to get the codebase into a state where a refactor like this one can be done cleanly, with confidence, and without creating merge conflicts across everything that's still moving. Doing a broad provider refactor before that settles would be working against ourselves.

So: this is work we want to do, but the sequencing matters. The right time is after the architectural ground stops moving, not during.

A few things worth noting for when this does get picked up:

What fits well:

• The blocking → async migration is warranted. Nested blocking calls in an async runtime are a latent soundness problem and cleaning that up is unambiguously good.
• A shared internal builder or config struct inside zeroclaw-providers makes sense. The inconsistency is real and a single construction path is easier to maintain.
• An http_client module for unified client construction is reasonable — OnceCell<reqwest::Client> gets you the reuse story without adding a caching dependency.

What needs more thought before implementation:

• ProviderConfig must stay internal to zeroclaw-providers. If it surfaces in the Provider trait definition in zeroclaw-api, it breaks the trait boundary — that's a hard constraint in our architecture. The trait stays stable; implementation details live below it.
• moka as a dependency for client caching is too heavy for what we'd be getting. The lightweight path (OnceCell or std::sync::OnceLock) covers the same need.
• Removing all semantic constructors at once is a large churn on a Beta crate. That's better approached incrementally — deprecate first, remove in a later cycle.

On @jokemanfire's suggestion to adopt rig: I understand the appeal — why build what exists? — but adopting an external agent framework at the provider/runtime layer would trade our vendor-neutral trait boundary for a hard external dependency. That cuts against a core architectural commitment. ZeroClaw's trait-driven design is specifically what makes it swappable and portable; we'd be giving that up, not improving it.

The right next step here is probably a focused RFC or issue that scopes the refactor into phases — async migration first, unified construction path second — and targets the milestone after the current architectural work is complete. If you want to drive that, I'm happy to review it. If it sits until a maintainer picks it up, that's fine too; this issue is a good enough record of the intent.

Thanks again for the thorough analysis.

[NiuBlibing]

@WareWolf-MoonWall Thank you so much for the detailed and thoughtful response! It really helps clarify the current state, priorities, and architectural constraints for the project.

I’ll take your feedback and continue refining the RFC to structure the refactor into clear phases (async migration first, then unified construction) as you suggested.

I also have a quick question about tracking the ongoing architectural work: I found #5574, but it’s already closed. Is there a centralized roadmap board or milestone where we can track the progress of the workspace split, foundations layer, and other refactoring efforts?

Additionally, I have some small feature requests like adding timeout controls and changing the custom temperature parameter to an Option (since Claude 4.7 removed support for it and passing the param will get error). Right now, adding these consistently across the codebase feels quite tedious and error-prone due to the scattered implementation. Could you share any advice on how to approach these improvements cleanly under the current architecture, to avoid missing places or introducing inconsistencies?
Thanks again for your guidance!

[WareWolf-MoonWall]

@WareWolf-MoonWall Thank you so much for the detailed and thoughtful response! It really helps clarify the current state, priorities, and architectural constraints for the project.

I’ll take your feedback and continue refining the RFC to structure the refactor into clear phases (async migration first, then unified construction) as you suggested.

I also have a quick question about tracking the ongoing architectural work: I found #5574, but it’s already closed. Is there a centralized roadmap board or milestone where we can track the progress of the workspace split, foundations layer, and other refactoring efforts?

Additionally, I have some small feature requests like adding timeout controls and changing the custom temperature parameter to an Option (since Claude 4.7 removed support for it and passing the param will get error). Right now, adding these consistently across the codebase feels quite tedious and error-prone due to the scattered implementation. Could you share any advice on how to approach these improvements cleanly under the current architecture, to avoid missing places or introducing inconsistencies? Thanks again for your guidance!

We are still working on maturing the whole repo. 5574 is more or less the guiding light when it comes to priority, but it's not a bunker disallowing additional content that folks find valuable and we can justify implementing.

As for your additional small feature requests - he's the advice I can offer. Get issues opened explaining your intent clearly so we can help prioritize (just like you did here). If you feel strongly about something, I'd recommend that after you have the issue opened tag a few of us. Part of the challenge with open source is that you have a million voices coming at you all the time, some genuine and valuable, some bots, some folks that are pitching their own projects. It's a lot of noise to filter through so reach out to a real person on the team will ensure your voice doesn't drown.

Hope that helps. 🐺

[singlerider]

@NiuBlibing

Additionally, I have some small feature requests like adding timeout controls and changing the custom temperature parameter to an Option (since Claude 4.7 removed support for it and passing the param will get error). Right now, adding these consistently across the codebase feels quite tedious and error-prone due to the scattered implementation. Could you share any advice on how to approach these improvements cleanly under the current architecture, to avoid missing places or introducing inconsistencies?

I have an open PR for the onboarding flow that, as a side-effect, properly exposes all of those temperature fields on all model providers.