synaps_cli/extensions/runtime/
mod.rs

1//! Extension runtime trait and registry.
2
3pub mod process;
4pub mod restart;
5
6pub use restart::RestartPolicy;
7
8use async_trait::async_trait;
9use serde_json::Value;
10use crate::extensions::hooks::events::{HookEvent, HookResult};
11use self::process::{ProviderCompleteParams, ProviderCompleteResult, ProviderStreamEvent};
12use crate::extensions::info::PluginInfo;
13use crate::extensions::commands::CommandOutputEvent;
14use crate::extensions::tasks::TaskEvent;
15
16/// Streamed event delivered to a `command.invoke` caller.
17#[derive(Debug, Clone, PartialEq)]
18pub enum InvokeCommandEvent {
19    /// Command output event matching the caller's `request_id`.
20    Output(CommandOutputEvent),
21    /// Spontaneous plugin task event (any `request_id`).
22    Task(TaskEvent),
23}
24
25/// Health state for an extension handler.
26#[derive(Debug, Clone, Copy, PartialEq, Eq)]
27pub enum ExtensionHealth {
28    /// Manifest validated, process spawned, but `initialize` not yet completed.
29    Loaded,
30    /// Manifest failed validation — the extension never started.
31    FailedValidation,
32    /// `initialize` rpc failed — the extension started but couldn't capability-handshake.
33    FailedInitialize,
34    /// Healthy and serving requests.
35    Running,
36    /// Process restarting after transport failure but within restart budget.
37    Restarting,
38    /// Running, but at least one recent operation failed (e.g. hook timeout).
39    Degraded,
40    /// Permanent failure — restart budget exhausted or unrecoverable error.
41    Failed,
42}
43
44impl ExtensionHealth {
45    pub fn as_str(self) -> &'static str {
46        match self {
47            Self::Loaded => "loaded",
48            Self::FailedValidation => "failed_validation",
49            Self::FailedInitialize => "failed_initialize",
50            Self::Running => "running",
51            Self::Restarting => "restarting",
52            Self::Degraded => "degraded",
53            Self::Failed => "failed",
54        }
55    }
56}
57
58#[cfg(test)]
59#[allow(clippy::items_after_test_module)]
60mod health_tests {
61    use super::ExtensionHealth;
62
63    #[test]
64    fn as_str_covers_all_variants() {
65        assert_eq!(ExtensionHealth::Loaded.as_str(), "loaded");
66        assert_eq!(ExtensionHealth::FailedValidation.as_str(), "failed_validation");
67        assert_eq!(ExtensionHealth::FailedInitialize.as_str(), "failed_initialize");
68        assert_eq!(ExtensionHealth::Running.as_str(), "running");
69        assert_eq!(ExtensionHealth::Restarting.as_str(), "restarting");
70        assert_eq!(ExtensionHealth::Degraded.as_str(), "degraded");
71        assert_eq!(ExtensionHealth::Failed.as_str(), "failed");
72    }
73}
74
75/// Trait for extension runtimes that can handle hook events.
76#[async_trait]
77pub trait ExtensionHandler: Send + Sync {
78    /// Unique identifier for this extension.
79    fn id(&self) -> &str;
80
81    /// Handle a hook event. Returns the handler's decision.
82    async fn handle(&self, event: &HookEvent) -> HookResult;
83
84    /// Call an extension-provided tool.
85    async fn call_tool(&self, _name: &str, _input: Value) -> Result<Value, String> {
86        Err("extension runtime does not support tool.call".to_string())
87    }
88
89    /// Complete a chat request through an extension-provided model provider.
90    async fn provider_complete(&self, _params: ProviderCompleteParams) -> Result<ProviderCompleteResult, String> {
91        Err("extension runtime does not support provider.complete".to_string())
92    }
93
94    /// Stream a chat request through an extension-provided model provider.
95    ///
96    /// The handler must forward `provider.stream.event` notifications to `sink`
97    /// in order. The returned `ProviderCompleteResult` is the final aggregated
98    /// response (so callers that don't need streaming can use it as the final
99    /// state). Implementations that don't support streaming should return
100    /// `Err("provider.stream is not supported by this extension")`.
101    async fn provider_stream(
102        &self,
103        _params: ProviderCompleteParams,
104        _sink: tokio::sync::mpsc::UnboundedSender<ProviderStreamEvent>,
105    ) -> Result<ProviderCompleteResult, String> {
106        Err("provider.stream is not supported by this extension".to_string())
107    }
108
109    /// Invoke a plugin-registered interactive slash command. The handler must
110    /// forward `command.output` notifications matching `request_id` and any
111    /// `task.*` notifications to `sink`. Returns the final response value.
112    async fn invoke_command(
113        &self,
114        _command: &str,
115        _args: Vec<String>,
116        _request_id: &str,
117        _sink: tokio::sync::mpsc::UnboundedSender<InvokeCommandEvent>,
118    ) -> Result<Value, String> {
119        Err("extension runtime does not support command.invoke".to_string())
120    }
121
122    /// Fetch optional plugin capability/build/model information.
123    async fn get_info(&self) -> Result<PluginInfo, String> {
124        Err("extension runtime does not support info.get".to_string())
125    }
126
127    /// Ask the plugin to supply sidecar spawn arguments. Used by the
128    /// modality-neutral sidecar bootstrap path (see
129    /// `crate::sidecar::spawn`); plugins that don't host a sidecar
130    /// should leave the default `Err` in place. Core treats the
131    /// returned [`SidecarSpawnArgs::args`] as opaque.
132    async fn sidecar_spawn_args(&self) -> Result<crate::sidecar::spawn::SidecarSpawnArgs, String> {
133        Err("extension runtime does not support sidecar.spawn_args".to_string())
134    }
135
136    /// Open a plugin-owned custom settings editor and return its initial render payload.
137    async fn settings_editor_open(&self, _category: &str, _field: &str) -> Result<Value, String> {
138        Err("extension runtime does not support settings.editor.open".to_string())
139    }
140
141    /// Forward a keypress to the active plugin-owned custom settings editor.
142    async fn settings_editor_key(&self, _category: &str, _field: &str, _key: &str) -> Result<Value, String> {
143        Err("extension runtime does not support settings.editor.key".to_string())
144    }
145
146    /// Ask the plugin to commit a custom editor value selected by the UI.
147    async fn settings_editor_commit(&self, _category: &str, _field: &str, _value: Value) -> Result<Value, String> {
148        Err("extension runtime does not support settings.editor.commit".to_string())
149    }
150
151    /// Gracefully shut down the extension.
152    async fn shutdown(&self);
153
154    /// Current health state of this handler.
155    async fn health(&self) -> ExtensionHealth {
156        ExtensionHealth::Running
157    }
158
159    /// Number of transport restarts observed by this handler.
160    async fn restart_count(&self) -> usize {
161        0
162    }
163}
synaps_cli/extensions/runtime/mod.rs

synaps_cli/extensions/runtime/
mod.rs
