Skip to main content

cpa_plugin/
transform.rs

1//! Translator hooks, thinking appliers and usage plugins
2//! (internal/pluginhost/adapters_usage_translation.go, sdk/translator/plugin_hooks.go).
3
4use bytes::Bytes;
5use cpa_common::gostr::GoStr;
6
7use crate::abi::method;
8use crate::api::{
9    ModelInfo, PayloadResponse, RequestTransformRequest, ResponseTransformRequest, ThinkingApplyRequest,
10    ThinkingConfig, UsageRecord,
11};
12use crate::callbacks::RequestScope;
13use crate::host::{Host, Inner, Record};
14use crate::rpc::Empty;
15use std::sync::{Arc, Weak};
16
17/// Providers with a built-in thinking applier; plugins cannot take them over
18/// (internal/thinking/apply.go and the provider packages' `RegisterProvider` calls).
19pub const NATIVE_THINKING_PROVIDERS: [&str; 11] = [
20    "gemini",
21    "claude",
22    "openai",
23    "codex",
24    "antigravity",
25    "kimi",
26    "kimi-ai",
27    "kimi.ai",
28    "kimi.com",
29    "xai",
30    "interactions",
31];
32
33/// One response-side hook call's inputs.
34#[derive(Debug, Clone, Default)]
35pub struct ResponseTransform<'a> {
36    pub from: &'a str,
37    pub to: &'a str,
38    pub model: &'a str,
39    pub original_request: &'a [u8],
40    pub translated_request: &'a [u8],
41    pub stream: bool,
42}
43
44impl Host {
45    /// Records with a hook; each call rechecks [`Host::live`].
46    fn hook_records(&self, has: impl Fn(&Record) -> bool) -> Vec<Record> {
47        self.active_records()
48            .into_iter()
49            .filter(|r| has(r) && !self.is_fused(&r.id))
50            .collect()
51    }
52
53    /// A transform call: the plugin's body when it answered with one.
54    fn transform<R: crate::gojson::GoStruct>(&self, record: &Record, method: &str, req: &R) -> Option<Bytes> {
55        if !self.live(record) {
56            return None;
57        }
58        match self.call_blocking::<PayloadResponse, _>(record, method, req) {
59            Ok(resp) if !resp.body.is_empty() => Some(resp.body),
60            _ => None,
61        }
62    }
63
64    /// Go `NormalizeRequest`: every request normalizer, chained.
65    pub fn normalize_request(&self, from: &str, to: &str, model: &str, body: Bytes, stream: bool) -> Bytes {
66        let mut current = body;
67        for record in self.hook_records(|r| r.plugin.caps.request_normalizer) {
68            let req = RequestTransformRequest {
69                from_format: from.into(),
70                to_format: to.into(),
71                model: model.into(),
72                stream,
73                body: current.clone(),
74            };
75            if let Some(out) = self.transform(&record, method::REQUEST_NORMALIZE, &req) {
76                current = out;
77            }
78        }
79        current
80    }
81
82    /// Go `TranslateRequest`: the first translator that answers wins.
83    pub fn translate_request(&self, from: &str, to: &str, model: &str, body: &Bytes, stream: bool) -> Option<Bytes> {
84        for record in self.hook_records(|r| r.plugin.caps.request_translator) {
85            let req = RequestTransformRequest {
86                from_format: from.into(),
87                to_format: to.into(),
88                model: model.into(),
89                stream,
90                body: body.clone(),
91            };
92            if let Some(out) = self.transform(&record, method::REQUEST_TRANSLATE, &req) {
93                return Some(out);
94            }
95        }
96        None
97    }
98
99    fn response_request(t: &ResponseTransform<'_>, body: Bytes) -> ResponseTransformRequest {
100        ResponseTransformRequest {
101            from_format: t.from.into(),
102            to_format: t.to.into(),
103            model: t.model.into(),
104            stream: t.stream,
105            original_request: Bytes::copy_from_slice(t.original_request),
106            translated_request: Bytes::copy_from_slice(t.translated_request),
107            body,
108        }
109    }
110
111    /// Go `NormalizeResponseBefore`: chained, before native translation.
112    pub fn normalize_response_before(&self, t: &ResponseTransform<'_>, body: Bytes) -> Bytes {
113        let mut current = body;
114        for record in self.hook_records(|r| r.plugin.caps.response_before_translator) {
115            let req = Self::response_request(t, current.clone());
116            if let Some(out) = self.transform(&record, method::RESPONSE_NORMALIZE_BEFORE, &req) {
117                current = out;
118            }
119        }
120        current
121    }
122
123    /// Go `TranslateResponse`: the first translator that answers wins.
124    pub fn translate_response(&self, t: &ResponseTransform<'_>, body: &Bytes) -> Option<Bytes> {
125        for record in self.hook_records(|r| r.plugin.caps.response_translator) {
126            let req = Self::response_request(t, body.clone());
127            if let Some(out) = self.transform(&record, method::RESPONSE_TRANSLATE, &req) {
128                return Some(out);
129            }
130        }
131        None
132    }
133
134    /// Go `NormalizeResponseAfter`: chained, after translation.
135    pub fn normalize_response_after(&self, t: &ResponseTransform<'_>, body: Bytes) -> Bytes {
136        let mut current = body;
137        for record in self.hook_records(|r| r.plugin.caps.response_after_translator) {
138            let req = Self::response_request(t, current.clone());
139            if let Some(out) = self.transform(&record, method::RESPONSE_NORMALIZE_AFTER, &req) {
140                current = out;
141            }
142        }
143        current
144    }
145
146    /// Go `hasResponseTranslator`.
147    pub fn has_response_translator(&self) -> bool {
148        !self.hook_records(|r| r.plugin.caps.response_translator).is_empty()
149    }
150
151    /// Go `refreshThinkingProviders` + `thinking.RegisterPluginProvider`: provider name to
152    /// the owning plugin, highest priority then lowest ID, never shadowing a native
153    /// provider. Identifiers are asked once per refresh.
154    pub(crate) async fn refresh_thinking_providers(&self) {
155        let mut providers: std::collections::BTreeMap<String, (String, i64)> = Default::default();
156        for record in self.hook_records(|r| r.plugin.caps.thinking_applier) {
157            let identifier = crate::rpc::identifier(&record.client, method::THINKING_IDENTIFIER)
158                .await
159                .go_lower();
160            if identifier.is_empty() || NATIVE_THINKING_PROVIDERS.contains(&identifier.as_str()) {
161                continue;
162            }
163            let replace = match providers.get(&identifier) {
164                None => true,
165                Some((owner, priority)) => {
166                    record.priority > *priority || (record.priority == *priority && record.id < *owner)
167                }
168            };
169            if replace {
170                providers.insert(identifier, (record.id.clone(), record.priority));
171            }
172        }
173        // Go `thinking.ClearPluginProviders` + `RegisterPluginProvider`: the process-wide
174        // table thinking consults for providers without a built-in applier.
175        cpa_common::thinking::clear_plugin_providers();
176        for (provider, (owner, priority)) in &providers {
177            let applier = Arc::new(ThinkingAdapter {
178                host: Arc::downgrade(&self.inner),
179                provider: provider.clone(),
180            });
181            cpa_common::thinking::register_plugin_provider(owner, provider, *priority, applier);
182        }
183        self.state().thinking_providers = providers.into_iter().map(|(k, (owner, _))| (k, owner)).collect();
184    }
185
186    /// The plugin that applies thinking for `provider`, if any.
187    pub fn thinking_provider(&self, provider: &str) -> Option<String> {
188        self.state()
189            .thinking_providers
190            .get(&provider.trim().go_lower())
191            .cloned()
192    }
193
194    /// Go `thinkingAdapter.Apply`: the plugin's body, or `body` unchanged on any failure.
195    pub fn apply_thinking(
196        &self,
197        provider: &str,
198        model: ModelInfo,
199        config: ThinkingConfig,
200        body: Bytes,
201        scope: &RequestScope,
202    ) -> Bytes {
203        let Some(owner) = self.thinking_provider(provider) else {
204            return body;
205        };
206        let Some(record) = self.record(&owner) else {
207            return body;
208        };
209        let req = ThinkingApplyRequest {
210            provider: provider.trim().go_lower(),
211            model,
212            config,
213            body: body.clone(),
214        };
215        match self.call_with_callback_blocking::<PayloadResponse, _>(&record, method::THINKING_APPLY, &req, scope) {
216            Ok(resp) if !resp.body.is_empty() => resp.body,
217            _ => body,
218        }
219    }
220
221    /// Go `usageAdapter.HandleUsage` for every usage plugin, in the background. The
222    /// caller resolves session fields the way the adapter does (see
223    /// [`usage_session_ids`]); failures are logged at debug level.
224    pub fn publish_usage(&self, record: UsageRecord) {
225        for plugin in self.hook_records(|r| r.plugin.caps.usage_plugin) {
226            let host = self.clone();
227            let record = record.clone();
228            tokio::spawn(async move {
229                // Go `currentUsagePlugin`: the plugin as it is when the record arrives.
230                let Some(plugin) = host.record(&plugin.id).filter(|r| r.plugin.caps.usage_plugin) else {
231                    return;
232                };
233                if let Err(e) = host.call::<Empty, _>(&plugin, method::USAGE_HANDLE, &record).await {
234                    tracing::debug!("pluginhost: usage.handle to {} failed: {e}", plugin.id);
235                }
236            });
237        }
238    }
239
240    /// Whether any usage plugin is active.
241    pub fn has_usage_plugins(&self) -> bool {
242        !self.hook_records(|r| r.plugin.caps.usage_plugin).is_empty()
243    }
244}
245
246/// The adapter's session fields: the record's own session wins; otherwise the client
247/// request's; the parent is dropped when it equals the session or no session is known.
248pub fn usage_session_ids(
249    record_session: &str,
250    record_parent: &str,
251    client_session: &str,
252    client_parent: &str,
253) -> (String, String) {
254    let mut session = record_session.trim().to_owned();
255    let mut parent = record_parent.trim().to_owned();
256    if session.is_empty() {
257        session = client_session.trim().to_owned();
258        parent = client_parent.trim().to_owned();
259    } else if parent.is_empty() && session == client_session.trim() {
260        parent = client_parent.trim().to_owned();
261    }
262    if session.is_empty() || session == parent {
263        parent.clear();
264    }
265    (session, parent)
266}
267
268/// Any of the translator hooks (Go `PluginHooks`).
269fn translator_hook(r: &Record) -> bool {
270    let c = &r.plugin.caps;
271    c.request_normalizer
272        || c.request_translator
273        || c.response_before_translator
274        || c.response_translator
275        || c.response_after_translator
276}
277
278impl Host {
279    /// This host as Go's `translator.PluginHooks` (`sdktranslator.SetPluginHooks(host)`).
280    /// It holds the host weakly, so installing it process-wide keeps nothing alive.
281    /// From then on, this host keeps cpa-translate's hook flag current, so with no
282    /// translator plugin the registry skips the hooks after one atomic load.
283    pub fn translator_hooks(&self) -> Arc<dyn cpa_translate::hooks::Hooks> {
284        self.inner
285            .hooks_installed
286            .store(true, std::sync::atomic::Ordering::Release);
287        let state = self.state();
288        self.publish_hook_activity(&state, &self.snapshot().records);
289        drop(state);
290        Arc::new(TranslatorHooks(Arc::downgrade(&self.inner)))
291    }
292
293    /// Publishes whether an unfused plugin among `records` offers a translator hook, and
294    /// an auth provider, to whichever of the registry and credential loading hold this
295    /// host. Callers hold the state lock, so updates follow the lifecycle's order.
296    pub(crate) fn publish_hook_activity(&self, state: &crate::host::State, records: &[Record]) {
297        use std::sync::atomic::Ordering;
298        let offers = |has: fn(&Record) -> bool| records.iter().any(|r| has(r) && !state.fused.contains_key(&r.id));
299        if self.inner.hooks_installed.load(Ordering::Acquire) {
300            cpa_translate::hooks::set_plugin_hooks_active(offers(translator_hook));
301        }
302        if self.inner.auth_parser_installed.load(Ordering::Acquire) {
303            // What auth parsing depends on: the plugins that parse, as loaded,
304            // configured and identified, and the host config every parse request
305            // carries. The same inputs publish the same signature, so an unchanged sync
306            // keeps cached answers.
307            use std::hash::{Hash, Hasher};
308            let mut providers = records
309                .iter()
310                .filter(|r| r.plugin.caps.auth_provider && !state.fused.contains_key(&r.id))
311                .peekable();
312            let signature = providers.peek().is_some().then(|| {
313                let mut hasher = std::collections::hash_map::DefaultHasher::new();
314                for r in providers {
315                    r.id.hash(&mut hasher);
316                    (Arc::as_ptr(&r.client) as usize).hash(&mut hasher);
317                    state.loaded.get(&r.id).map(|lp| &lp.config_yaml).hash(&mut hasher);
318                    crate::host::normalize_provider(&r.plugin.auth_identifier).hash(&mut hasher);
319                }
320                let summary = state.config.as_deref().map(crate::auth::host_config_summary_of);
321                summary.map(|s| crate::gojson::to_vec(&s)).hash(&mut hasher);
322                hasher.finish()
323            });
324            cpa_core::config::credentials::set_plugin_auth_providers(signature);
325        }
326    }
327
328    /// Whether an active, unfused plugin offers a hook `has` selects, without copying
329    /// the records.
330    fn offers(&self, has: impl Fn(&Record) -> bool) -> bool {
331        self.snapshot().records.iter().any(|r| has(r) && !self.is_fused(&r.id))
332    }
333}
334
335struct TranslatorHooks(Weak<Inner>);
336
337impl TranslatorHooks {
338    fn host(&self, has: impl Fn(&Record) -> bool) -> Option<Host> {
339        let host = Host {
340            inner: self.0.upgrade()?,
341        };
342        host.offers(has).then_some(host)
343    }
344}
345
346fn response_transform<'a>(t: &'a cpa_translate::hooks::Response<'a>) -> ResponseTransform<'a> {
347    ResponseTransform {
348        from: t.from,
349        to: t.to,
350        model: t.model,
351        original_request: t.original_request,
352        translated_request: t.translated_request,
353        stream: t.stream,
354    }
355}
356
357impl cpa_translate::hooks::Hooks for TranslatorHooks {
358    fn normalize_request(&self, from: &str, to: &str, model: &str, body: &[u8], stream: bool) -> Option<Vec<u8>> {
359        let host = self.host(|r| r.plugin.caps.request_normalizer)?;
360        Some(
361            host.normalize_request(from, to, model, Bytes::copy_from_slice(body), stream)
362                .to_vec(),
363        )
364    }
365
366    fn translate_request(&self, from: &str, to: &str, model: &str, body: &[u8], stream: bool) -> Option<Vec<u8>> {
367        let host = self.host(|r| r.plugin.caps.request_translator)?;
368        host.translate_request(from, to, model, &Bytes::copy_from_slice(body), stream)
369            .map(|b| b.to_vec())
370    }
371
372    fn normalize_response_before(&self, t: &cpa_translate::hooks::Response<'_>, body: &[u8]) -> Option<Vec<u8>> {
373        let host = self.host(|r| r.plugin.caps.response_before_translator)?;
374        Some(
375            host.normalize_response_before(&response_transform(t), Bytes::copy_from_slice(body))
376                .to_vec(),
377        )
378    }
379
380    fn translate_response(&self, t: &cpa_translate::hooks::Response<'_>, body: &[u8]) -> Option<Vec<u8>> {
381        let host = self.host(|r| r.plugin.caps.response_translator)?;
382        host.translate_response(&response_transform(t), &Bytes::copy_from_slice(body))
383            .map(|b| b.to_vec())
384    }
385
386    fn normalize_response_after(&self, t: &cpa_translate::hooks::Response<'_>, body: &[u8]) -> Option<Vec<u8>> {
387        let host = self.host(|r| r.plugin.caps.response_after_translator)?;
388        Some(
389            host.normalize_response_after(&response_transform(t), Bytes::copy_from_slice(body))
390                .to_vec(),
391        )
392    }
393}
394
395/// Go `thinkingAdapter`: a plugin's thinking applier for one provider. Any failure
396/// leaves the body unchanged.
397struct ThinkingAdapter {
398    host: Weak<Inner>,
399    provider: String,
400}
401
402impl cpa_common::thinking::PluginApplier for ThinkingAdapter {
403    fn apply(
404        &self,
405        body: &[u8],
406        config: &cpa_common::thinking::Config,
407        info: Option<&cpa_common::thinking::ModelCaps>,
408    ) -> Result<Vec<u8>, cpa_common::thinking::Error> {
409        let Some(inner) = self.host.upgrade() else {
410            return Ok(body.to_vec());
411        };
412        let config = ThinkingConfig {
413            mode: config.mode.as_str().to_owned(),
414            budget: config.budget,
415            level: config.level.clone(),
416        };
417        let out = Host { inner }.apply_thinking(
418            &self.provider,
419            plugin_model_info(info),
420            config,
421            Bytes::copy_from_slice(body),
422            &RequestScope::default(),
423        );
424        Ok(out.to_vec())
425    }
426}
427
428/// Go `registryModelInfoToPluginModelInfo` from the fields thinking resolves.
429// ponytail: thinking sees only `ModelCaps` (ID, type, completion limit, thinking support,
430// user-defined); the descriptive registry fields reach the plugin empty. Pass the full
431// `ModelInfo` through `ModelCaps` if a plugin needs them.
432fn plugin_model_info(info: Option<&cpa_common::thinking::ModelCaps>) -> ModelInfo {
433    let Some(info) = info else {
434        return ModelInfo::default();
435    };
436    ModelInfo {
437        id: info.id.clone(),
438        model_type: info.kind.clone(),
439        max_completion_tokens: info.max_completion_tokens,
440        thinking: info.thinking.as_ref().map(|t| crate::api::ThinkingSupport {
441            min: t.min,
442            max: t.max,
443            zero_allowed: t.zero_allowed,
444            dynamic_allowed: t.dynamic_allowed,
445            disable_type: t.disable_type.clone(),
446            levels: t.levels.clone(),
447        }),
448        user_defined: info.user_defined,
449        ..Default::default()
450    }
451}
452
453#[cfg(test)]
454mod tests {
455    use super::*;
456
457    /// Go TestPluginThinkingSupportCarriesDisableTypeBothWays, registry to plugin: a
458    /// plugin thinking applier sees the model's `DisableType`.
459    #[test]
460    fn plugin_model_info_keeps_the_disable_type() {
461        let caps = cpa_common::thinking::ModelCaps {
462            id: "m".into(),
463            thinking: Some(cpa_core::registry::ThinkingSupport {
464                levels: vec!["low".into()],
465                disable_type: "between_tools".into(),
466                ..Default::default()
467            }),
468            ..Default::default()
469        };
470        let got = plugin_model_info(Some(&caps)).thinking.unwrap();
471        assert_eq!(got.disable_type, "between_tools");
472    }
473
474    #[test]
475    fn usage_sessions_follow_the_go_adapter() {
476        assert_eq!(usage_session_ids("", "", " c ", "p"), ("c".into(), "p".into()));
477        assert_eq!(usage_session_ids("s", "", "s", "p"), ("s".into(), "p".into()));
478        assert_eq!(usage_session_ids("s", "", "other", "p"), ("s".into(), "".into()));
479        assert_eq!(usage_session_ids("s", "s", "", ""), ("s".into(), "".into()));
480        assert_eq!(usage_session_ids("", "x", "", ""), ("".into(), "".into()));
481    }
482}