lash_core/plugin/
runtime_impl.rs

1use std::collections::{BTreeMap, BTreeSet};
2use std::sync::Arc;
3use std::sync::{Mutex as StdMutex, Weak};
4
5use super::*;
6
7#[derive(Clone)]
8pub struct PluginHost {
9    factories: Arc<Vec<Arc<dyn PluginFactory>>>,
10    lashlang_abilities: lashlang::LashlangAbilities,
11    lashlang_language_features: lashlang::LashlangLanguageFeatures,
12    lashlang_resources: lashlang::ResourceCatalog,
13    sessions: Arc<StdMutex<BTreeMap<String, Weak<PluginSession>>>>,
14}
15
16struct BuildPluginSessionRequest<'a> {
17    session_id: String,
18    parent_session_id: Option<String>,
19    snapshot: Option<&'a PluginSessionSnapshot>,
20    tool_surface_overlay: ToolSurfaceContribution,
21    tool_snapshot: Option<crate::ToolState>,
22    authority: SessionAuthorityContext,
23}
24
25#[derive(Clone, Debug, Default)]
26pub struct SessionAuthorityContext {
27    pub tool_access: SessionToolAccess,
28    pub subagent: Option<SubagentSessionContext>,
29}
30
31impl PluginHost {
32    pub fn empty() -> Self {
33        Self::new(Vec::new())
34    }
35
36    pub fn new(factories: Vec<Arc<dyn PluginFactory>>) -> Self {
37        let override_ids: BTreeSet<&'static str> =
38            factories.iter().map(|factory| factory.id()).collect();
39        let mut all_factories = super::builtin_plugin_factories();
40        if !override_ids.is_empty() {
41            all_factories.retain(|factory| !override_ids.contains(factory.id()));
42        }
43        all_factories.extend(factories);
44        let lashlang_abilities = all_factories.iter().fold(
45            lashlang::LashlangAbilities::default(),
46            |abilities, factory| abilities.union(factory.lashlang_abilities()),
47        );
48        let lashlang_language_features = all_factories.iter().fold(
49            lashlang::LashlangLanguageFeatures::default(),
50            |features, factory| features.union(factory.lashlang_language_features()),
51        );
52        let lashlang_resources = all_factories.iter().fold(
53            lashlang::ResourceCatalog::new(),
54            |mut resources, factory| {
55                resources.extend(factory.lashlang_resources());
56                resources
57            },
58        );
59        Self {
60            factories: Arc::new(all_factories),
61            lashlang_abilities,
62            lashlang_language_features,
63            lashlang_resources,
64            sessions: Arc::new(StdMutex::new(BTreeMap::new())),
65        }
66    }
67
68    pub fn with_lashlang_abilities(mut self, abilities: lashlang::LashlangAbilities) -> Self {
69        self.lashlang_abilities = abilities;
70        self
71    }
72
73    pub fn with_lashlang_language_features(
74        mut self,
75        language_features: lashlang::LashlangLanguageFeatures,
76    ) -> Self {
77        self.lashlang_language_features = language_features;
78        self
79    }
80
81    pub fn with_lashlang_resources(mut self, resources: lashlang::ResourceCatalog) -> Self {
82        self.lashlang_resources = resources;
83        self
84    }
85
86    pub fn isolated_registry(&self) -> Self {
87        Self {
88            factories: Arc::clone(&self.factories),
89            lashlang_abilities: self.lashlang_abilities,
90            lashlang_language_features: self.lashlang_language_features,
91            lashlang_resources: self.lashlang_resources.clone(),
92            sessions: Arc::new(StdMutex::new(BTreeMap::new())),
93        }
94    }
95
96    pub fn lashlang_abilities(&self) -> lashlang::LashlangAbilities {
97        self.lashlang_abilities
98    }
99
100    pub fn lashlang_language_features(&self) -> lashlang::LashlangLanguageFeatures {
101        self.lashlang_language_features
102    }
103
104    pub fn lashlang_resources(&self) -> lashlang::ResourceCatalog {
105        self.lashlang_resources.clone()
106    }
107
108    pub fn factories(&self) -> &[Arc<dyn PluginFactory>] {
109        self.factories.as_ref().as_slice()
110    }
111
112    pub fn build_session(
113        &self,
114        session_id: impl Into<String>,
115        snapshot: Option<&PluginSessionSnapshot>,
116    ) -> Result<Arc<PluginSession>, PluginError> {
117        self.build_session_with_surface(
118            session_id,
119            snapshot,
120            ToolSurfaceContribution::default(),
121            None,
122        )
123    }
124
125    /// Variant of [`build_session`] that records the caller as the
126    /// parent of the new session. Plugin factories read
127    /// [`PluginSessionContext::is_root_session`] to gate root-only
128    /// behavior; anything that goes through the plain `build_session`
129    /// is treated as a root session by default.
130    pub fn build_session_with_parent(
131        &self,
132        session_id: impl Into<String>,
133        parent_session_id: Option<String>,
134        snapshot: Option<&PluginSessionSnapshot>,
135        authority: SessionAuthorityContext,
136    ) -> Result<Arc<PluginSession>, PluginError> {
137        self.build_session_with_parent_and_surface(
138            session_id,
139            parent_session_id,
140            snapshot,
141            ToolSurfaceContribution::default(),
142            None,
143            authority,
144        )
145    }
146
147    pub fn build_session_with_parent_and_surface(
148        &self,
149        session_id: impl Into<String>,
150        parent_session_id: Option<String>,
151        snapshot: Option<&PluginSessionSnapshot>,
152        tool_surface_overlay: ToolSurfaceContribution,
153        tool_snapshot: Option<crate::ToolState>,
154        authority: SessionAuthorityContext,
155    ) -> Result<Arc<PluginSession>, PluginError> {
156        self.build_session_inner(BuildPluginSessionRequest {
157            session_id: session_id.into(),
158            parent_session_id,
159            snapshot,
160            tool_surface_overlay,
161            tool_snapshot,
162            authority,
163        })
164    }
165
166    pub fn build_session_with_surface(
167        &self,
168        session_id: impl Into<String>,
169        snapshot: Option<&PluginSessionSnapshot>,
170        tool_surface_overlay: ToolSurfaceContribution,
171        tool_snapshot: Option<crate::ToolState>,
172    ) -> Result<Arc<PluginSession>, PluginError> {
173        self.build_session_inner(BuildPluginSessionRequest {
174            session_id: session_id.into(),
175            parent_session_id: None,
176            snapshot,
177            tool_surface_overlay,
178            tool_snapshot,
179            authority: SessionAuthorityContext::default(),
180        })
181    }
182
183    fn build_session_inner(
184        &self,
185        request: BuildPluginSessionRequest<'_>,
186    ) -> Result<Arc<PluginSession>, PluginError> {
187        let BuildPluginSessionRequest {
188            session_id,
189            parent_session_id,
190            snapshot,
191            tool_surface_overlay,
192            tool_snapshot,
193            authority,
194        } = request;
195        let ctx = PluginSessionContext {
196            session_id,
197            tool_access: authority.tool_access.clone(),
198            subagent: authority.subagent.clone(),
199            lashlang_abilities: self.lashlang_abilities,
200            lashlang_language_features: self.lashlang_language_features,
201            parent_session_id,
202        };
203        let session_id = ctx.session_id.clone();
204        let mut tool_snapshot = tool_snapshot;
205        if let Some(snapshot) = &mut tool_snapshot {
206            let hidden_tools = &authority.tool_access.hidden_tools;
207            if !hidden_tools.is_empty() {
208                snapshot.retain(|name, _| !hidden_tools.contains(name));
209            }
210        }
211        let mut plugins = Vec::new();
212        let mut reg = PluginRegistrar::new();
213        for factory in self.factories() {
214            let plugin = factory.build(&ctx)?;
215            reg.registering_plugin_id = Some(plugin.id().to_string());
216            plugin.register(&mut reg)?;
217            reg.registering_plugin_id = None;
218            plugins.push(plugin);
219        }
220        let mut contributions = reg.contributions;
221        let protocol_session = contributions.protocol_session.take().ok_or_else(|| {
222            PluginError::Registration("missing protocol session capability".to_string())
223        })?;
224        let protocol_driver = contributions.protocol_driver.take().ok_or_else(|| {
225            PluginError::Registration("missing protocol driver capability".to_string())
226        })?;
227        contributions.protocol_session = Some(protocol_session);
228        contributions.protocol_driver = Some(protocol_driver);
229        contributions
230            .turn_context_transforms
231            .sort_by_key(|entry| std::cmp::Reverse(entry.0));
232        contributions
233            .history_rewriters
234            .sort_by_key(|entry| std::cmp::Reverse(entry.0));
235        let host_events = crate::HostEventCatalog::from_events(contributions.host_events.clone())
236            .map_err(|message| {
237            PluginError::Registration(format!("invalid host event catalog: {message}"))
238        })?;
239        let mut lashlang_resources = self.lashlang_resources.clone();
240        for event in host_events.events() {
241            lashlang_resources
242                .add_trigger_source_constructor(
243                    event.source_type().split('.'),
244                    lashlang::TypeExpr::Object(Vec::new()),
245                    event.payload_type().clone(),
246                )
247                .map_err(|err| {
248                    PluginError::Registration(format!(
249                        "invalid host event trigger source `{}.{}`: {err}",
250                        event.alias, event.event
251                    ))
252                })?;
253        }
254        let registry = match tool_snapshot {
255            Some(snapshot) => Arc::new(
256                crate::ToolRegistry::from_tool_providers(contributions.tool_providers.clone())
257                    .map_err(|err| {
258                        PluginError::Registration(format!("failed to build tool registry: {err}"))
259                    })?
260                    .fork_with_state(snapshot)
261                    .map_err(|err| {
262                        PluginError::Session(format!(
263                            "tool state cannot be applied to this plugin host session: {err}"
264                        ))
265                    })?,
266            ),
267            None => Arc::new(
268                crate::ToolRegistry::from_tool_providers(contributions.tool_providers.clone())
269                    .map_err(|err| {
270                        PluginError::Registration(format!("failed to build tool registry: {err}"))
271                    })?,
272            ),
273        };
274        let tools = Arc::clone(&registry) as Arc<dyn ToolProvider>;
275
276        let session = Arc::new(PluginSession {
277            host: self.clone(),
278            session_id: ctx.session_id,
279            plugins,
280            tools,
281            tool_registry: registry,
282            tool_surface_overlay,
283            tool_access: authority.tool_access,
284            subagent: authority.subagent,
285            lashlang_abilities: self.lashlang_abilities,
286            lashlang_language_features: self.lashlang_language_features,
287            lashlang_resources,
288            host_events,
289            contributions,
290        });
291        self.register_session(&session_id, &session)?;
292        let ready = SessionReadyContext {
293            session_id: session.session_id.clone(),
294            host: self.clone(),
295        };
296        for plugin in &session.plugins {
297            plugin.session_ready(ready.clone())?;
298        }
299        if let Some(snapshot) = snapshot {
300            session.restore(snapshot)?;
301        }
302        Ok(session)
303    }
304
305    pub async fn invoke_plugin_action_sessionless(
306        &self,
307        name: &str,
308        args: serde_json::Value,
309    ) -> Result<ToolResult, PluginError> {
310        let session = self.build_session(
311            format!("__external__-{}", uuid::Uuid::new_v4().simple()),
312            None,
313        )?;
314        session
315            .invoke_plugin_action(
316                name,
317                args,
318                None,
319                false,
320                Arc::new(NoopSessionManager),
321                Arc::new(NoopSessionManager),
322                Arc::new(NoopSessionManager),
323                Arc::new(crate::UnavailableProcessService),
324            )
325            .await
326            .map_err(|err| PluginError::Invoke(err.to_string()))
327    }
328
329    fn register_session(
330        &self,
331        session_id: &str,
332        session: &Arc<PluginSession>,
333    ) -> Result<(), PluginError> {
334        let mut sessions = self.sessions.lock().map_err(|_| {
335            PluginError::Session("plugin host session registry poisoned".to_string())
336        })?;
337        if let Some(existing) = sessions.get(session_id).and_then(Weak::upgrade) {
338            if !Arc::ptr_eq(&existing, session) {
339                return Err(PluginError::Session(format!(
340                    "session `{session_id}` is already registered on this plugin host"
341                )));
342            }
343            return Ok(());
344        }
345        sessions.insert(session_id.to_string(), Arc::downgrade(session));
346        Ok(())
347    }
348
349    pub fn unregister_session(&self, session_id: &str) -> Result<(), PluginError> {
350        let mut sessions = self.sessions.lock().map_err(|_| {
351            PluginError::Session("plugin host session registry poisoned".to_string())
352        })?;
353        sessions.remove(session_id);
354        Ok(())
355    }
356
357    pub fn session(&self, session_id: &str) -> Result<Arc<PluginSession>, PluginActionInvokeError> {
358        let mut sessions = self
359            .sessions
360            .lock()
361            .map_err(|_| PluginActionInvokeError::SessionRegistryPoisoned)?;
362        let Some(weak) = sessions.get(session_id).cloned() else {
363            return Err(PluginActionInvokeError::UnknownSession(
364                session_id.to_string(),
365            ));
366        };
367        match weak.upgrade() {
368            Some(session) => Ok(session),
369            None => {
370                sessions.remove(session_id);
371                Err(PluginActionInvokeError::UnknownSession(
372                    session_id.to_string(),
373                ))
374            }
375        }
376    }
377
378    #[expect(
379        clippy::too_many_arguments,
380        reason = "host action invocation wires the runtime service bundle at the plugin boundary"
381    )]
382    pub async fn invoke_plugin_action_for_session(
383        &self,
384        session_id: &str,
385        name: &str,
386        args: serde_json::Value,
387        sessions: Arc<dyn SessionStateService>,
388        session_lifecycle: Arc<dyn SessionLifecycleService>,
389        session_graph: Arc<dyn SessionGraphService>,
390        processes: Arc<dyn crate::ProcessService>,
391    ) -> Result<ToolResult, PluginActionInvokeError> {
392        let session = self.session(session_id)?;
393        session
394            .invoke_plugin_action(
395                name,
396                args,
397                Some(session_id.to_string()),
398                false,
399                sessions,
400                session_lifecycle,
401                session_graph,
402                processes,
403            )
404            .await
405    }
406}
lash_core/plugin/runtime_impl.rs

lash_core/plugin/
runtime_impl.rs
