Skip to main content

cpa_plugin/
models.rs

1//! Model registration and executor ownership (internal/pluginhost/adapters.go
2//! `RegisterModels`/`ModelsForAuth`, adapters_executors.go `RegisterExecutors`).
3//!
4//! The host decides which plugin models and executor providers exist; the server applies
5//! the returned changes to its model registry and executor table.
6
7use std::collections::{BTreeMap, HashMap, HashSet};
8use std::sync::Arc;
9
10use crate::abi::method;
11use crate::api::{
12    AuthModelRequest, ModelInfo, ModelRegistrationRequest, ModelRegistrationResponse, ModelResponse, StaticModelRequest,
13};
14use crate::auth::{AuthView, PluginAuth};
15use crate::callbacks::RequestScope;
16use crate::host::{Host, normalize_provider};
17use crate::rpc::CallError;
18
19/// Go `pluginModelRegistration`.
20#[derive(Debug, Clone, Default, PartialEq)]
21pub struct ModelRegistration {
22    pub plugin_id: String,
23    pub provider: String,
24    pub priority: i64,
25    pub models: Vec<ModelInfo>,
26    pub has_executor: bool,
27}
28
29/// Registry changes: clients to (re)register with their provider and models, then
30/// clients to remove.
31#[derive(Debug, Clone, Default, PartialEq)]
32pub struct ClientChanges {
33    pub register: Vec<(String, String, Vec<ModelInfo>)>,
34    pub unregister: Vec<String>,
35}
36
37/// Executor table changes from [`Host::register_executors`].
38#[derive(Debug, Clone, Default)]
39pub struct ExecutorChanges {
40    /// The registered executors, in registration order. Each keeps the plugin instance
41    /// it was registered from (Go `executorAdapter`), so a replaced plugin's successor
42    /// never serves a registration made for its predecessor.
43    pub register: Vec<crate::executor::Adapter>,
44    /// Providers whose plugin executor went away. The caller removes each only if the
45    /// executor registered for it is still a plugin executor (Go `ownsExecutor`).
46    pub unregister: Vec<String>,
47    pub clients: ClientChanges,
48}
49
50/// Go `AuthModelResult`.
51#[derive(Debug, Clone, Default)]
52pub struct AuthModelResult {
53    pub provider: String,
54    pub models: Vec<ModelInfo>,
55    pub auth: Option<PluginAuth>,
56    pub handled: bool,
57    pub error: Option<CallError>,
58}
59
60/// Model IDs trimmed; empty IDs dropped.
61fn clean_models(models: Vec<ModelInfo>) -> Vec<ModelInfo> {
62    models
63        .into_iter()
64        .filter_map(|mut m| {
65            m.id = m.id.trim().to_owned();
66            (!m.id.is_empty()).then_some(m)
67        })
68        .collect()
69}
70
71/// Go `appendModelsForProvider`: first occurrence of an ID wins.
72fn append_models(out: &mut BTreeMap<String, Vec<ModelInfo>>, provider: &str, models: &[ModelInfo]) {
73    let provider = normalize_provider(provider);
74    if provider.is_empty() || models.is_empty() {
75        return;
76    }
77    let list = out.entry(provider).or_default();
78    let mut seen: HashSet<String> = list.iter().map(|m| m.id.trim().to_owned()).collect();
79    for model in models {
80        let id = model.id.trim();
81        if !id.is_empty() && seen.insert(id.to_owned()) {
82            list.push(model.clone());
83        }
84    }
85}
86
87/// Go `authDataHasValue`.
88fn auth_data_has_value(d: &crate::api::AuthData) -> bool {
89    let filled = |s: &str| !s.trim().is_empty();
90    filled(&d.provider)
91        || filled(&d.id)
92        || filled(&d.file_name)
93        || filled(&d.label)
94        || filled(&d.prefix)
95        || filled(&d.proxy_url)
96        || d.disabled
97        || !d.storage_json.is_empty()
98        || !d.metadata.is_empty()
99        || !d.attributes.is_empty()
100        || !d.next_refresh_after.is_zero()
101}
102
103/// Go `authDataWithDefaults`.
104fn auth_data_with_defaults(mut d: crate::api::AuthData, auth: &AuthView) -> crate::api::AuthData {
105    let fill = |v: &mut String, from: &str| {
106        if v.trim().is_empty() {
107            *v = from.to_owned();
108        }
109    };
110    fill(&mut d.provider, &auth.provider);
111    fill(&mut d.id, &auth.id);
112    fill(&mut d.file_name, &auth.file_name);
113    fill(&mut d.label, &auth.label);
114    fill(&mut d.prefix, &auth.prefix);
115    fill(&mut d.proxy_url, &auth.proxy_url);
116    for (k, v) in &auth.metadata {
117        d.metadata.entry(k.clone()).or_insert_with(|| v.clone());
118    }
119    for (k, v) in &auth.attributes {
120        d.attributes.entry(k.clone()).or_insert_with(|| v.clone());
121    }
122    if d.storage_json.is_empty() {
123        d.storage_json = auth.storage_json.clone();
124    }
125    if d.next_refresh_after.is_zero() {
126        d.next_refresh_after = auth.next_refresh_after;
127    }
128    d
129}
130
131/// Go `pluginExecutorModelClientID`.
132pub fn executor_client_id(plugin_id: &str, provider: &str) -> String {
133    format!("plugin:{plugin_id}:{provider}:executor")
134}
135
136impl Host {
137    /// Go v8.0.35 `RegisterModels`: collects the static models of every model provider or
138    /// registrar whose executor scope allows static models. Nothing is published here:
139    /// catalog-only models reach the registry only through credentials of their provider
140    /// ([`Self::models_for_provider`]), executor plugins' through
141    /// [`Self::register_executors`].
142    pub async fn register_models(&self) {
143        let snapshot = self.snapshot();
144        let records: Vec<_> = snapshot
145            .records
146            .iter()
147            .filter(|r| self.record_current(r))
148            .cloned()
149            .collect();
150        let mut next_providers = HashMap::new();
151        let mut next_registrations = HashMap::new();
152        for record in records {
153            let caps = &record.plugin.caps;
154            if !(caps.model_provider || caps.model_registrar) || !record.plugin.allows_static_models() {
155                continue;
156            }
157            if self.is_fused(&record.id) || !self.record_current(&record) {
158                continue;
159            }
160            let result: Result<ModelRegistrationResponse, CallError> = if caps.model_provider {
161                let req = StaticModelRequest {
162                    plugin: record.plugin.metadata.clone(),
163                    host: self.host_config_summary(),
164                };
165                self.call::<ModelResponse, _>(&record, method::MODEL_STATIC, &req)
166                    .await
167                    .map(|r| ModelRegistrationResponse {
168                        provider: r.provider,
169                        models: r.models,
170                    })
171            } else {
172                let req = ModelRegistrationRequest {
173                    plugin: record.plugin.metadata.clone(),
174                };
175                self.call(&record, method::MODEL_REGISTER, &req).await
176            };
177            let resp = match result {
178                Ok(resp) => resp,
179                Err(e) => {
180                    tracing::warn!("pluginhost: model registrar {} failed: {e}", record.id);
181                    continue;
182                }
183            };
184            let provider = normalize_provider(&resp.provider);
185            let models = clean_models(resp.models);
186            if provider.is_empty() || models.is_empty() {
187                continue;
188            }
189            next_registrations.insert(
190                record.id.clone(),
191                ModelRegistration {
192                    plugin_id: record.id.clone(),
193                    provider: provider.clone(),
194                    priority: record.priority,
195                    models,
196                    has_executor: caps.executor,
197                },
198            );
199            next_providers.insert(record.id.clone(), provider);
200        }
201        let mut state = self.state();
202        if !Arc::ptr_eq(&self.snapshot(), &snapshot) {
203            return;
204        }
205        state.model_providers = next_providers;
206        state.model_registrations = next_registrations;
207    }
208
209    /// Go `ModelsForAuth`: the first model provider for the credential's provider (its
210    /// auth provider's identifier, else its registered or executor provider).
211    pub async fn models_for_auth(&self, auth: &AuthView, scope: &RequestScope) -> AuthModelResult {
212        let provider_key = normalize_provider(&auth.provider);
213        if provider_key.is_empty() {
214            return AuthModelResult::default();
215        }
216        for record in self.active_records() {
217            if !record.plugin.caps.model_provider || self.is_fused(&record.id) || !record.plugin.allows_oauth_models() {
218                continue;
219            }
220            if record.plugin.caps.auth_provider {
221                if normalize_provider(&record.plugin.auth_identifier) != provider_key {
222                    continue;
223                }
224            } else {
225                let mut record_provider = normalize_provider(
226                    &self
227                        .state()
228                        .model_providers
229                        .get(&record.id)
230                        .cloned()
231                        .unwrap_or_default(),
232                );
233                if record_provider.is_empty() && record.plugin.caps.executor {
234                    record_provider = self.executor_provider(&record).await.unwrap_or_default();
235                }
236                if record_provider != provider_key {
237                    continue;
238                }
239            }
240            if !self.record_current(&record) {
241                continue;
242            }
243            let req = AuthModelRequest {
244                plugin: record.plugin.metadata.clone(),
245                auth_id: auth.id.clone(),
246                auth_provider: auth.provider.clone(),
247                storage_json: auth.storage_json.clone(),
248                metadata: auth.metadata.clone(),
249                attributes: auth.attributes.clone(),
250                host: self.host_config_summary(),
251            };
252            let resp: ModelResponse = match self
253                .call_with_callback(&record, method::MODEL_FOR_AUTH, &req, scope)
254                .await
255            {
256                Ok(resp) => resp,
257                Err(e) => {
258                    tracing::warn!("pluginhost: models for auth {} failed: {e}", auth.id);
259                    return AuthModelResult {
260                        handled: true,
261                        error: Some(e),
262                        ..Default::default()
263                    };
264                }
265            };
266            let mut resp_provider = normalize_provider(&resp.provider);
267            if !resp_provider.is_empty() && resp_provider != provider_key {
268                continue;
269            }
270            if resp_provider.is_empty() {
271                resp_provider = provider_key.clone();
272            }
273            let path = auth
274                .attributes
275                .get(crate::auth::ATTRIBUTE_PATH)
276                .cloned()
277                .unwrap_or_default();
278            let updated = auth_data_has_value(&resp.auth_update)
279                .then(|| auth_data_with_defaults(resp.auth_update, auth))
280                .and_then(|data| {
281                    PluginAuth::from_auth_data(data, &path, &auth.file_name, &self.host_config_summary().auth_dir)
282                });
283            return AuthModelResult {
284                provider: resp_provider,
285                models: clean_models(resp.models),
286                auth: updated,
287                handled: true,
288                error: None,
289            };
290        }
291        AuthModelResult::default()
292    }
293
294    fn sorted_registrations(&self) -> Vec<ModelRegistration> {
295        let mut registrations: Vec<ModelRegistration> = self.state().model_registrations.values().cloned().collect();
296        registrations.sort_by(|a, b| b.priority.cmp(&a.priority).then_with(|| a.plugin_id.cmp(&b.plugin_id)));
297        registrations
298    }
299
300    /// Go `RegisterExecutors`. `native_provider` says whether a built-in executor serves
301    /// a provider; `model_providers` lists the providers registered for a model ID. A
302    /// plugin executor claims its provider only when no built-in executor does, and only
303    /// models no built-in provider serves; the first plugin (by priority) wins a model
304    /// and a provider. `None` when the plugin set changed meanwhile (Go
305    /// `commitExecutorState` then keeps the previous state).
306    pub async fn register_executors(
307        &self,
308        native_provider: &(dyn Fn(&str) -> bool + Sync),
309        model_providers: &(dyn Fn(&str) -> Vec<String> + Sync),
310    ) -> Option<ExecutorChanges> {
311        let snapshot = self.snapshot();
312        let records: Vec<_> = snapshot
313            .records
314            .iter()
315            .filter(|r| self.record_current(r))
316            .cloned()
317            .collect();
318        let mut provider_models: BTreeMap<String, Vec<ModelInfo>> = BTreeMap::new();
319        let mut claimed_models: HashSet<String> = HashSet::new();
320        for registration in self.sorted_registrations() {
321            if registration.has_executor {
322                continue;
323            }
324            append_models(&mut provider_models, &registration.provider, &registration.models);
325            // A catalog for a built-in provider reserves its models before plugin
326            // executors compete, whether or not a credential has published them yet.
327            if native_provider(&registration.provider) {
328                claimed_models.extend(
329                    registration
330                        .models
331                        .iter()
332                        .map(|m| m.id.trim().to_owned())
333                        .filter(|id| !id.is_empty()),
334                );
335            }
336        }
337        let registration_of = |id: &str| self.state().model_registrations.get(id).cloned().unwrap_or_default();
338        let model_native = |model: &str| model_providers(model).iter().any(|p| native_provider(p));
339        let mut selected: HashMap<String, Vec<ModelInfo>> = HashMap::new();
340        let mut claimed_providers: HashMap<String, String> = HashMap::new();
341        for record in &records {
342            if !record.plugin.caps.executor || self.is_fused(&record.id) {
343                continue;
344            }
345            let Some(provider) = self.executor_provider(record).await else {
346                continue;
347            };
348            let registration = registration_of(&record.id);
349            if native_provider(&provider) {
350                append_models(&mut provider_models, &provider, &registration.models);
351                continue;
352            }
353            if registration.models.is_empty() {
354                continue;
355            }
356            if claimed_providers
357                .get(&provider)
358                .is_some_and(|owner| owner != &record.id)
359            {
360                continue;
361            }
362            for model in &registration.models {
363                let id = model.id.trim();
364                if id.is_empty() || claimed_models.contains(id) || model_native(id) {
365                    continue;
366                }
367                claimed_models.insert(id.to_owned());
368                claimed_providers.insert(provider.clone(), record.id.clone());
369                selected.entry(record.id.clone()).or_default().push(model.clone());
370            }
371        }
372        let mut changes = ExecutorChanges::default();
373        let mut seen = HashSet::new();
374        let mut next_providers = HashSet::new();
375        let mut next_clients = HashSet::new();
376        for record in &records {
377            if !record.plugin.caps.executor || self.is_fused(&record.id) {
378                continue;
379            }
380            let Some(provider) = self.executor_provider(record).await else {
381                continue;
382            };
383            let registration = registration_of(&record.id);
384            let mine = selected.get(&record.id).cloned().unwrap_or_default();
385            if !registration.models.is_empty() && mine.is_empty() {
386                continue;
387            }
388            if !seen.insert(provider.clone()) || native_provider(&provider) {
389                continue;
390            }
391            next_providers.insert(provider.clone());
392            changes
393                .register
394                .push(self.adapter_for(record.clone(), provider.clone()));
395            append_models(&mut provider_models, &provider, &mine);
396            if !mine.is_empty() {
397                let client = executor_client_id(&record.id, &provider);
398                next_clients.insert(client.clone());
399                changes.clients.register.push((client, provider.clone(), mine));
400            }
401        }
402        let mut state = self.state();
403        if !Arc::ptr_eq(&self.snapshot(), &snapshot) {
404            return None;
405        }
406        state.provider_models = provider_models;
407        let mut stale: Vec<String> = state.executor_providers.difference(&next_providers).cloned().collect();
408        stale.sort();
409        state.executor_providers = next_providers;
410        let mut stale_clients: Vec<String> = state
411            .executor_model_client_ids
412            .difference(&next_clients)
413            .cloned()
414            .collect();
415        stale_clients.sort();
416        changes.clients.unregister = stale_clients;
417        state.executor_model_client_ids = next_clients;
418        drop(state);
419        // Go removes a stale provider only while the manager still holds this host's
420        // adapter; a built-in executor that replaced it stays.
421        stale.retain(|provider| !native_provider(provider));
422        changes.unregister = stale;
423        Some(changes)
424    }
425
426    /// Go `ModelsForProvider`.
427    pub fn models_for_provider(&self, provider: &str) -> Vec<ModelInfo> {
428        self.state()
429            .provider_models
430            .get(&normalize_provider(provider))
431            .cloned()
432            .unwrap_or_default()
433    }
434
435    /// Every provider's plugin models after the last [`Self::register_executors`].
436    pub fn provider_models(&self) -> BTreeMap<String, Vec<ModelInfo>> {
437        self.state().provider_models.clone()
438    }
439
440    /// The plugin executing `provider` after the last [`Self::register_executors`].
441    pub fn executor_providers(&self) -> HashSet<String> {
442        self.state().executor_providers.clone()
443    }
444
445    /// Go `HasExecutorCandidateProvider`.
446    pub async fn has_executor_candidate_provider(&self, provider: &str) -> bool {
447        let provider = normalize_provider(provider);
448        if provider.is_empty() {
449            return false;
450        }
451        for record in self.active_records() {
452            if record.plugin.caps.executor
453                && !self.is_fused(&record.id)
454                && self.executor_provider(&record).await.as_deref() == Some(provider.as_str())
455            {
456                return true;
457            }
458        }
459        false
460    }
461}