Skip to main content

tea_coding/config/
providers.rs

1use std::collections::BTreeMap;
2use std::fmt;
3use std::fs;
4use std::io::Read as _;
5use std::path::Path;
6use std::process::{Command, Stdio};
7use std::str::FromStr as _;
8use std::sync::Mutex;
9use std::thread;
10use std::time::{Duration, Instant};
11
12use serde::Deserialize;
13use tea_model::{HostedToolKind, ModelDisplayName, ProviderId, ReasoningProfile};
14use tea_protocol::{ModelId, ReasoningEffort, TokenCount};
15
16/// Maximum accepted size of one provider configuration file.
17pub const MAX_PROVIDERS_FILE_BYTES: usize = 256 * 1024;
18
19const MAX_CONFIGURED_PROVIDERS: usize = 64;
20const MAX_MODELS_PER_PROVIDER: usize = 256;
21const MAX_HOSTED_TOOLS_PER_MODEL: usize = 16;
22const MAX_COMMAND_OUTPUT_BYTES: u64 = 16 * 1024;
23const COMMAND_TIMEOUT: Duration = Duration::from_secs(10);
24
25/// Provider map loaded from a standalone `providers.json` file.
26#[derive(Clone, Default, PartialEq, Eq, Deserialize)]
27#[serde(deny_unknown_fields)]
28pub struct ProvidersConfig {
29    /// OpenAI-compatible providers keyed by canonical provider selector.
30    #[serde(default)]
31    pub providers: BTreeMap<String, ProviderConfig>,
32}
33
34impl fmt::Debug for ProvidersConfig {
35    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
36        formatter
37            .debug_struct("ProvidersConfig")
38            .field("providers", &self.providers)
39            .finish()
40    }
41}
42
43impl ProvidersConfig {
44    /// Overlays project/provider values on top of this configuration.
45    #[must_use]
46    pub fn merged(mut self, overlay: Self) -> Self {
47        for (provider_id, provider) in overlay.providers {
48            match self.providers.get_mut(&provider_id) {
49                Some(base) => base.apply(provider),
50                None => {
51                    self.providers.insert(provider_id, provider);
52                }
53            }
54        }
55        self
56    }
57}
58
59/// Sparse OpenAI-compatible provider connection and model catalog.
60#[derive(Clone, Default, PartialEq, Eq, Deserialize)]
61#[serde(deny_unknown_fields)]
62pub struct ProviderConfig {
63    /// Optional human-readable provider name.
64    pub name: Option<String>,
65    /// Optional API base URL.
66    pub base_url: Option<String>,
67    /// Optional API key literal, environment template, or `!command`.
68    pub api_key: Option<String>,
69    /// Optional HTTP header carrying the API key.
70    pub api_key_header: Option<String>,
71    /// Optional prefix prepended to the API key.
72    pub api_key_prefix: Option<String>,
73    /// Optional API mode: `chat-completions` or `responses`.
74    pub api_mode: Option<String>,
75    /// Optional `OpenAI` organization identifier.
76    pub org_id: Option<String>,
77    /// Optional `OpenAI` project identifier.
78    pub project_id: Option<String>,
79    /// Deprecated provider-wide reasoning default used only as a model-profile fallback.
80    pub reasoning_effort: Option<String>,
81    /// Whether models in this provider accept image input.
82    pub vision: Option<bool>,
83    /// Optional positive request timeout in milliseconds.
84    pub timeout_millis: Option<u64>,
85    /// Models advertised by this provider. A non-empty overlay replaces the base list.
86    #[serde(default)]
87    pub models: Vec<ModelDefinition>,
88}
89
90impl fmt::Debug for ProviderConfig {
91    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
92        formatter
93            .debug_struct("ProviderConfig")
94            .field("name", &self.name)
95            .field("base_url", &self.base_url)
96            .field("api_key", &self.api_key.as_ref().map(|_| "**REDACTED**"))
97            .field("api_key_header", &self.api_key_header)
98            .field("api_key_prefix", &self.api_key_prefix)
99            .field("api_mode", &self.api_mode)
100            .field("org_id", &self.org_id)
101            .field("project_id", &self.project_id)
102            .field("reasoning_effort", &self.reasoning_effort)
103            .field("vision", &self.vision)
104            .field("timeout_millis", &self.timeout_millis)
105            .field("models", &self.models)
106            .finish()
107    }
108}
109
110impl ProviderConfig {
111    fn apply(&mut self, overlay: Self) {
112        replace(&mut self.name, overlay.name);
113        replace(&mut self.base_url, overlay.base_url);
114        replace(&mut self.api_key, overlay.api_key);
115        replace(&mut self.api_key_header, overlay.api_key_header);
116        replace(&mut self.api_key_prefix, overlay.api_key_prefix);
117        replace(&mut self.api_mode, overlay.api_mode);
118        replace(&mut self.org_id, overlay.org_id);
119        replace(&mut self.project_id, overlay.project_id);
120        replace(&mut self.reasoning_effort, overlay.reasoning_effort);
121        replace(&mut self.vision, overlay.vision);
122        replace(&mut self.timeout_millis, overlay.timeout_millis);
123        if !overlay.models.is_empty() {
124            self.models = overlay.models;
125        }
126    }
127}
128
129/// One model advertised by a configured provider.
130#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
131#[serde(deny_unknown_fields)]
132pub struct ModelDefinition {
133    /// Canonical model identifier.
134    pub id: String,
135    /// Optional human-readable model name.
136    pub display_name: Option<String>,
137    /// Optional context window, defaulting to 128,000 tokens.
138    pub context_window_tokens: Option<u64>,
139    /// Optional output limit, defaulting to 16,384 tokens.
140    pub max_output_tokens: Option<u64>,
141    /// Explicit capabilities supported by this model at the configured endpoint.
142    #[serde(default)]
143    pub capabilities: ModelCapabilitiesConfig,
144}
145
146/// Explicit, fail-closed capabilities for one configured model and endpoint.
147#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
148#[serde(deny_unknown_fields)]
149pub struct ModelCapabilitiesConfig {
150    /// Model-specific provider-neutral reasoning support and wire mapping.
151    pub reasoning: Option<ModelReasoningConfig>,
152    /// Provider-hosted tools supported by this exact model and endpoint.
153    #[serde(default)]
154    pub hosted_tools: Vec<HostedToolCapability>,
155}
156
157/// Strict model-level reasoning profile and provider wire overrides.
158#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
159#[serde(deny_unknown_fields)]
160pub struct ModelReasoningConfig {
161    /// Default canonical effort for this model.
162    pub default_effort: ReasoningEffort,
163    /// Canonical effort to provider wire value; `null` explicitly disables a level.
164    #[serde(default)]
165    pub effort_map: BTreeMap<ReasoningEffort, Option<String>>,
166}
167
168impl ModelReasoningConfig {
169    /// Resolves default support and explicit overrides into a validated profile and wire map.
170    #[must_use]
171    pub fn resolved(&self) -> Option<(ReasoningProfile, BTreeMap<ReasoningEffort, String>)> {
172        if self.effort_map.len() > ReasoningEffort::ALL.len()
173            || self
174                .effort_map
175                .get(&ReasoningEffort::Off)
176                .is_some_and(Option::is_some)
177        {
178            return None;
179        }
180        let mut supported = Vec::new();
181        let mut wire_map = BTreeMap::new();
182        for effort in ReasoningEffort::ALL {
183            let configured = self.effort_map.get(&effort);
184            let enabled = if matches!(
185                effort,
186                ReasoningEffort::ExtraHigh | ReasoningEffort::Maximum
187            ) {
188                configured.is_some_and(Option::is_some)
189            } else {
190                !configured.is_some_and(Option::is_none)
191            };
192            if !enabled {
193                continue;
194            }
195            supported.push(effort);
196            if effort != ReasoningEffort::Off {
197                let wire = configured
198                    .and_then(Option::as_deref)
199                    .unwrap_or_else(|| effort.as_str());
200                if !valid_wire_effort(wire) {
201                    return None;
202                }
203                wire_map.insert(effort, wire.to_owned());
204            }
205        }
206        let profile = ReasoningProfile::new(self.default_effort, supported).ok()?;
207        Some((profile, wire_map))
208    }
209}
210
211/// Provider-hosted capability accepted in custom model configuration.
212#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Deserialize)]
213#[serde(rename_all = "snake_case")]
214pub enum HostedToolCapability {
215    /// Searches the public web inside the provider response lifecycle.
216    WebSearch,
217}
218
219impl HostedToolCapability {
220    /// Returns the provider-neutral model capability represented by this value.
221    #[must_use]
222    pub const fn kind(self) -> HostedToolKind {
223        match self {
224            Self::WebSearch => HostedToolKind::WebSearch,
225        }
226    }
227}
228
229/// Safe classification for a provider configuration load failure.
230#[derive(Debug, Clone, Copy, PartialEq, Eq)]
231pub enum ProvidersConfigLoadError {
232    /// The file could not be read.
233    Read,
234    /// The file exceeded [`MAX_PROVIDERS_FILE_BYTES`].
235    TooLarge,
236    /// JSON, schema, or configured collection bounds were invalid.
237    Invalid,
238}
239
240/// Soft-failing provider configuration load result.
241#[derive(Debug, Clone, Default, PartialEq, Eq)]
242pub struct ProvidersConfigLoad {
243    /// Parsed configuration, or an empty map on failure/missing input.
244    pub config: ProvidersConfig,
245    /// Safe failure classification. Missing files are not errors.
246    pub error: Option<ProvidersConfigLoadError>,
247}
248
249impl ProvidersConfigLoad {
250    fn success(config: ProvidersConfig) -> Self {
251        Self {
252            config,
253            error: None,
254        }
255    }
256
257    fn failure(error: ProvidersConfigLoadError) -> Self {
258        Self {
259            config: ProvidersConfig::default(),
260            error: Some(error),
261        }
262    }
263}
264
265/// Loads a strict, bounded provider configuration without propagating file errors.
266#[must_use]
267pub fn load_providers_file(path: &Path) -> ProvidersConfigLoad {
268    let bytes = match fs::read(path) {
269        Ok(bytes) => bytes,
270        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
271            return ProvidersConfigLoad::success(ProvidersConfig::default());
272        }
273        Err(_) => return ProvidersConfigLoad::failure(ProvidersConfigLoadError::Read),
274    };
275    if bytes.len() > MAX_PROVIDERS_FILE_BYTES {
276        return ProvidersConfigLoad::failure(ProvidersConfigLoadError::TooLarge);
277    }
278    let Ok(config) = serde_json::from_slice::<ProvidersConfig>(&bytes) else {
279        return ProvidersConfigLoad::failure(ProvidersConfigLoadError::Invalid);
280    };
281    if !valid_config(&config) {
282        return ProvidersConfigLoad::failure(ProvidersConfigLoadError::Invalid);
283    }
284    ProvidersConfigLoad::success(config)
285}
286
287/// Resolves provider values from environment templates and cached shell commands.
288pub struct ProviderValueResolver {
289    environment: BTreeMap<String, String>,
290    commands: Mutex<BTreeMap<String, Option<String>>>,
291}
292
293impl fmt::Debug for ProviderValueResolver {
294    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
295        formatter
296            .debug_struct("ProviderValueResolver")
297            .field("environment", &"**REDACTED**")
298            .field("commands", &"**REDACTED**")
299            .finish()
300    }
301}
302
303impl ProviderValueResolver {
304    /// Creates a resolver with an explicit, hermetic command environment.
305    #[must_use]
306    pub fn new(environment: BTreeMap<String, String>) -> Self {
307        Self {
308            environment,
309            commands: Mutex::new(BTreeMap::new()),
310        }
311    }
312
313    /// Resolves `$NAME`/`${NAME}` templates or a leading `!command`.
314    ///
315    /// Missing environment values and failed, empty, oversized, or timed-out
316    /// commands resolve to `None`.
317    #[must_use]
318    pub fn resolve(&self, configured: &str) -> Option<String> {
319        if let Some(command) = configured.strip_prefix('!') {
320            return self.resolve_command(command.trim());
321        }
322        resolve_template(configured, &self.environment)
323    }
324
325    fn resolve_command(&self, command: &str) -> Option<String> {
326        if command.is_empty() {
327            return None;
328        }
329        if let Ok(cache) = self.commands.lock()
330            && let Some(value) = cache.get(command)
331        {
332            return value.clone();
333        }
334        let value = execute_command(command, &self.environment);
335        if let Ok(mut cache) = self.commands.lock() {
336            cache.insert(command.to_owned(), value.clone());
337        }
338        value
339    }
340}
341
342fn replace<T>(base: &mut Option<T>, overlay: Option<T>) {
343    if overlay.is_some() {
344        *base = overlay;
345    }
346}
347
348fn valid_config(config: &ProvidersConfig) -> bool {
349    config.providers.len() <= MAX_CONFIGURED_PROVIDERS
350        && config.providers.iter().all(|(provider_id, provider)| {
351            ProviderId::from_str(provider_id).is_ok()
352                && provider.models.len() <= MAX_MODELS_PER_PROVIDER
353                && provider
354                    .api_mode
355                    .as_deref()
356                    .is_none_or(|mode| matches!(mode, "chat-completions" | "responses"))
357                && provider
358                    .reasoning_effort
359                    .as_deref()
360                    .is_none_or(|effort| ReasoningEffort::from_str(effort).is_ok())
361                && provider.timeout_millis.is_none_or(|timeout| timeout > 0)
362                && valid_models(&provider.models)
363        })
364}
365
366fn valid_models(models: &[ModelDefinition]) -> bool {
367    let mut ids = std::collections::BTreeSet::new();
368    models.iter().all(|model| {
369        let context = model.context_window_tokens.unwrap_or(128_000);
370        let output = model.max_output_tokens.unwrap_or(16_384);
371        ids.insert(model.id.as_str())
372            && ModelId::from_str(&model.id).is_ok()
373            && ModelDisplayName::from_str(model.display_name.as_deref().unwrap_or(&model.id))
374                .is_ok()
375            && TokenCount::new(context).is_ok()
376            && TokenCount::new(output).is_ok()
377            && output <= context
378            && model
379                .capabilities
380                .reasoning
381                .as_ref()
382                .is_none_or(|reasoning| reasoning.resolved().is_some())
383            && valid_hosted_tools(&model.capabilities.hosted_tools)
384    })
385}
386
387fn valid_wire_effort(value: &str) -> bool {
388    !value.is_empty()
389        && value.len() <= 64
390        && value
391            .bytes()
392            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-' | b'.'))
393}
394
395fn valid_hosted_tools(tools: &[HostedToolCapability]) -> bool {
396    let mut unique = std::collections::BTreeSet::new();
397    tools.len() <= MAX_HOSTED_TOOLS_PER_MODEL && tools.iter().all(|tool| unique.insert(*tool))
398}
399
400fn resolve_template(value: &str, environment: &BTreeMap<String, String>) -> Option<String> {
401    let bytes = value.as_bytes();
402    let mut output = String::with_capacity(value.len());
403    let mut index = 0;
404    while index < bytes.len() {
405        if bytes[index] != b'$' {
406            let character = value[index..].chars().next()?;
407            output.push(character);
408            index += character.len_utf8();
409            continue;
410        }
411        match bytes.get(index + 1).copied() {
412            Some(b'$') => {
413                output.push('$');
414                index += 2;
415            }
416            Some(b'!') => {
417                output.push('!');
418                index += 2;
419            }
420            Some(b'{') => {
421                let Some(relative_end) = value[index + 2..].find('}') else {
422                    output.push('$');
423                    index += 1;
424                    continue;
425                };
426                let end = index + 2 + relative_end;
427                let name = &value[index + 2..end];
428                if valid_environment_name(name) {
429                    output.push_str(environment.get(name)?);
430                } else {
431                    output.push_str(&value[index..=end]);
432                }
433                index = end + 1;
434            }
435            Some(_) => {
436                let name_end = value[index + 1..]
437                    .char_indices()
438                    .take_while(|(offset, character)| {
439                        if *offset == 0 {
440                            *character == '_' || character.is_ascii_alphabetic()
441                        } else {
442                            *character == '_' || character.is_ascii_alphanumeric()
443                        }
444                    })
445                    .map(|(offset, character)| index + 1 + offset + character.len_utf8())
446                    .last();
447                if let Some(end) = name_end {
448                    output.push_str(environment.get(&value[index + 1..end])?);
449                    index = end;
450                } else {
451                    output.push('$');
452                    index += 1;
453                }
454            }
455            None => {
456                output.push('$');
457                index += 1;
458            }
459        }
460    }
461    Some(output)
462}
463
464fn valid_environment_name(name: &str) -> bool {
465    let mut characters = name.chars();
466    characters
467        .next()
468        .is_some_and(|character| character == '_' || character.is_ascii_alphabetic())
469        && characters.all(|character| character == '_' || character.is_ascii_alphanumeric())
470}
471
472fn execute_command(command: &str, environment: &BTreeMap<String, String>) -> Option<String> {
473    let mut process = configured_shell(environment);
474    process
475        .env_clear()
476        .envs(environment)
477        .arg(command)
478        .stdin(Stdio::null())
479        .stdout(Stdio::piped())
480        .stderr(Stdio::null());
481    let mut child = process.spawn().ok()?;
482    let stdout = child.stdout.take()?;
483    let reader = thread::spawn(move || {
484        let mut bytes = Vec::new();
485        stdout
486            .take(MAX_COMMAND_OUTPUT_BYTES + 1)
487            .read_to_end(&mut bytes)
488            .ok()?;
489        Some(bytes)
490    });
491    let deadline = Instant::now() + COMMAND_TIMEOUT;
492    let status = loop {
493        match child.try_wait() {
494            Ok(Some(status)) => break Some(status),
495            Ok(None) if Instant::now() < deadline => thread::sleep(Duration::from_millis(10)),
496            Ok(None) | Err(_) => {
497                let _ = child.kill();
498                let _ = child.wait();
499                break None;
500            }
501        }
502    };
503    let bytes = reader.join().ok()??;
504    if !status?.success() || u64::try_from(bytes.len()).ok()? > MAX_COMMAND_OUTPUT_BYTES {
505        return None;
506    }
507    let output = String::from_utf8(bytes).ok()?;
508    let output = output.trim();
509    (!output.is_empty()).then(|| output.to_owned())
510}
511
512#[cfg(unix)]
513fn configured_shell(environment: &BTreeMap<String, String>) -> Command {
514    let mut command = Command::new(
515        environment
516            .get("TEA_SHELL")
517            .map_or("/bin/sh", String::as_str),
518    );
519    command.arg(
520        environment
521            .get("TEA_SHELL_FLAG")
522            .map_or("-c", String::as_str),
523    );
524    command
525}
526
527#[cfg(windows)]
528fn configured_shell(environment: &BTreeMap<String, String>) -> Command {
529    let mut command = Command::new(
530        environment
531            .get("TEA_SHELL")
532            .or_else(|| environment.get("COMSPEC"))
533            .map_or("cmd.exe", String::as_str),
534    );
535    command.arg(
536        environment
537            .get("TEA_SHELL_FLAG")
538            .map_or("/C", String::as_str),
539    );
540    command
541}
542
543#[cfg(test)]
544mod tests {
545    use super::*;
546
547    #[test]
548    fn templates_expand_and_escape_environment_values() {
549        let resolver = ProviderValueResolver::new(BTreeMap::from([
550            ("TOKEN".to_owned(), "secret".to_owned()),
551            ("SUFFIX_2".to_owned(), "tail".to_owned()),
552        ]));
553        assert_eq!(
554            resolver.resolve("pre-$TOKEN-${SUFFIX_2}-$$-$!"),
555            Some("pre-secret-tail-$-!".to_owned())
556        );
557        assert_eq!(resolver.resolve("$MISSING"), None);
558        assert_eq!(
559            resolver.resolve("${bad-name}"),
560            Some("${bad-name}".to_owned())
561        );
562    }
563
564    #[cfg(unix)]
565    #[test]
566    fn command_values_are_trimmed_and_cached() {
567        let resolver = ProviderValueResolver::new(BTreeMap::new());
568        assert_eq!(
569            resolver.resolve("!printf ' key\\n'"),
570            Some("key".to_owned())
571        );
572        assert_eq!(
573            resolver.resolve("!printf ' key\\n'"),
574            Some("key".to_owned())
575        );
576        assert_eq!(resolver.commands.lock().unwrap().len(), 1);
577    }
578
579    #[test]
580    fn provider_debug_output_redacts_api_keys() {
581        let provider = ProviderConfig {
582            api_key: Some("secret-provider-key".to_owned()),
583            ..ProviderConfig::default()
584        };
585        assert!(!format!("{provider:?}").contains("secret-provider-key"));
586    }
587}