Skip to main content

objectiveai_mcp_plugin_framework/
command_executor.rs

1//! Running ObjectiveAI CLI commands from inside a plugin.
2//!
3//! A plugin cannot run the CLI itself — there is no binary in its
4//! container and no daemon it is allowed to dial. What it has is the
5//! MCP connection the host already opened, and an extension that runs
6//! backwards along it: the plugin declares the `objectiveai`
7//! capability, pushes a `notifications/objectiveai/cli_request` frame
8//! naming the command it wants, and the HOST runs it and POSTs the
9//! results back, one frame per item, to
10//! `{mcp_url}/objectiveai/command`.
11//!
12//! [`command_executor`] wraps that exchange in the SDK's own
13//! [`CommandExecutor`] trait, so a plugin issues commands exactly the
14//! way anything else in ObjectiveAI does.
15//!
16//! ```no_run
17//! # use objectiveai_sdk::cli::command::CommandExecutor as _;
18//! # async fn example() -> Result<(), objectiveai_mcp_plugin_framework::command_executor::Error> {
19//! # let request: objectiveai_sdk::cli::command::update::Request = todo!();
20//! let executor = objectiveai_mcp_plugin_framework::command_executor();
21//! let _item: serde_json::Value = executor.execute_one(request, None).await?;
22//! # Ok(())
23//! # }
24//! ```
25//!
26//! **An executor can be taken before [`serve`][crate::serve::serve] is
27//! called.** All of its state is process-global, so the value itself
28//! carries nothing that has to exist yet. Used before a client has
29//! connected, `execute` simply WAITS for one rather than failing:
30//! there is no peer to push a notification to until then, and a plugin
31//! that built its executor during startup should not be punished for
32//! it.
33//!
34//! **Every exchange is independent.** Each run has its own correlation
35//! id and its own channel, and the response endpoint routes purely by
36//! id through a sharded map — so any number of commands run at once
37//! and none of them queue behind another. Frame order is guaranteed
38//! per run, never across runs.
39
40use std::pin::Pin;
41use std::sync::LazyLock;
42
43use dashmap::DashMap;
44use futures::{Stream, StreamExt as _};
45use objectiveai_sdk::cli::command::{CommandRequest, CommandResponse};
46use objectiveai_sdk::identity::Identity;
47use objectiveai_sdk::mcp::CliResponse;
48use rmcp::model::{CustomNotification, ServerNotification};
49use rmcp::service::Peer;
50use rmcp::RoleServer;
51use tokio::sync::mpsc;
52
53/// The notification a plugin pushes to ask the host to run a command.
54const CLI_REQUEST_METHOD: &str = "notifications/objectiveai/cli_request";
55
56/// Where the host POSTs the answering frames — the MCP endpoint plus
57/// [`objectiveai_sdk::mcp::CLI_COMMAND_ENDPOINT_SUFFIX`]. `serve`
58/// mounts it; it is here because this is the half that gives it
59/// meaning.
60pub(crate) const COMMAND_PATH: &str = objectiveai_sdk::mcp::CLI_COMMAND_ENDPOINT_SUFFIX;
61
62/// Runs in flight, by correlation id.
63///
64/// A `DashMap` rather than one lock: the response endpoint touches it
65/// on EVERY frame of EVERY run, and two runs answering at once must
66/// not serialize against each other.
67static PENDING: LazyLock<DashMap<String, mpsc::UnboundedSender<CliResponse>>> =
68    LazyLock::new(DashMap::new);
69
70/// The connected client, once one is. `serve` publishes it on
71/// `initialize`; `execute` waits on it.
72///
73/// A `watch` rather than a slot plus a notify: a waiter that arrives
74/// after the peer was published must not block forever waiting for a
75/// signal that already fired, and `watch` is the channel whose
76/// semantics are "the current value, and tell me when it changes".
77static PEER: LazyLock<(
78    tokio::sync::watch::Sender<Option<Peer<RoleServer>>>,
79    tokio::sync::watch::Receiver<Option<Peer<RoleServer>>>,
80)> = LazyLock::new(|| tokio::sync::watch::channel(None));
81
82/// Publish the connected client. Called by `serve` on `initialize`.
83pub(crate) fn set_peer(peer: Peer<RoleServer>) {
84    let _ = PEER.0.send(Some(peer));
85}
86
87/// Route one answering frame to the run that is waiting for it.
88///
89/// Unknown ids are dropped silently: a run whose stream was abandoned
90/// deregisters itself, and its late frames are not an error the host
91/// should hear about.
92pub(crate) fn deliver(frame: CliResponse) {
93    let id = match &frame {
94        CliResponse::Ack { id }
95        | CliResponse::Item { id, .. }
96        | CliResponse::Error { id, .. }
97        | CliResponse::Done { id } => id.clone(),
98    };
99    if let Some(sink) = PENDING.get(&id) {
100        let _ = sink.send(frame);
101    }
102}
103
104/// Everything a command run can fail with.
105#[derive(Debug, thiserror::Error)]
106pub enum Error {
107    /// The notification could not be pushed to the client.
108    #[error("send the command request to the host")]
109    Send(#[source] rmcp::service::ServiceError),
110    /// A request or response item would not serialize.
111    #[error("encode the command request")]
112    Encode(#[source] serde_json::Error),
113    /// A response item did not match the type the caller asked for.
114    #[error("decode a command response item")]
115    Decode(#[source] serde_json::Error),
116    /// The CLI itself reported a failure for this item.
117    #[error("{0}")]
118    Cli(objectiveai_sdk::cli::Error),
119    /// The HOST reported a failure — the run never started, or the
120    /// stream broke on its side. Non-terminal on the wire: a run may
121    /// report errors and keep going.
122    #[error("the host could not run the command: {0}")]
123    Host(String),
124    /// The exchange ended before producing anything, and
125    /// [`CommandExecutor::execute_one`] needed one item.
126    #[error("the command produced no output")]
127    Empty,
128}
129
130/// An executor that runs commands through the host.
131///
132/// A handle with nothing in it: every run reaches the same
133/// process-global registry, so cloning is free and an instance taken
134/// before the server started works exactly as well as one taken after.
135#[derive(Debug, Clone, Copy, Default)]
136pub struct Executor;
137
138/// An executor for ObjectiveAI CLI commands, run by the host on this
139/// plugin's behalf.
140///
141/// Safe to call at any point, including before
142/// [`serve`][crate::serve::serve] — see the module docs.
143pub fn command_executor() -> Executor {
144    Executor
145}
146
147/// Deregisters a run when its stream is dropped, however it ends.
148///
149/// Without this an abandoned run would leak its slot, and — worse —
150/// the id would stay live, so a late frame would be delivered to a
151/// channel nobody reads.
152struct Registered(String);
153
154impl Drop for Registered {
155    fn drop(&mut self) {
156        PENDING.remove(&self.0);
157    }
158}
159
160impl objectiveai_sdk::cli::command::CommandExecutor for Executor {
161    type Error = Error;
162    type Stream<T>
163        = Pin<Box<dyn Stream<Item = Result<T, Error>> + Send>>
164    where
165        T: Send + 'static;
166
167    async fn execute<R, T>(
168        &self,
169        request: R,
170        _identity: Option<&Identity>,
171    ) -> Result<Self::Stream<T>, Error>
172    where
173        R: CommandRequest + Send + serde::Serialize,
174        T: CommandResponse + serde::Serialize + serde::de::DeserializeOwned + Send + 'static,
175    {
176        // `identity` is ignored, and cannot be otherwise: the HOST
177        // decides who this plugin is — it stamps the trio from the
178        // canonical image coordinates and refuses any claim off the
179        // wire. A plugin asserting its own identity here would be
180        // asserting nothing.
181        let request = serde_json::to_value(&request).map_err(Error::Encode)?;
182        let id = uuid::Uuid::new_v4().to_string();
183
184        // REGISTER FIRST. The host may answer the instant the
185        // notification lands, and a frame arriving before the slot
186        // exists would be dropped as unknown.
187        let (tx, rx) = mpsc::unbounded_channel();
188        PENDING.insert(id.clone(), tx);
189        let registered = Registered(id.clone());
190
191        // Wait for a client if there is not one yet — see the module
192        // docs. Cheap and immediate once connected.
193        let peer = {
194            let mut peer = PEER.1.clone();
195            let connected = peer
196                .wait_for(Option::is_some)
197                .await
198                .expect("the peer sender is a static and never drops");
199            connected.clone().expect("waited for Some")
200        };
201
202        peer.send_notification(ServerNotification::CustomNotification(
203            CustomNotification::new(
204                CLI_REQUEST_METHOD,
205                Some(serde_json::json!({ "id": id, "request": request })),
206            ),
207        ))
208        .await
209        .map_err(Error::Send)?;
210
211        Ok(Box::pin(stream(rx, registered)))
212    }
213
214    async fn execute_one<R, T>(
215        &self,
216        request: R,
217        identity: Option<&Identity>,
218    ) -> Result<T, Error>
219    where
220        R: CommandRequest + Send + serde::Serialize,
221        T: CommandResponse + serde::Serialize + serde::de::DeserializeOwned + Send + 'static,
222    {
223        let mut stream = self.execute::<R, T>(request, identity).await?;
224        stream.next().await.ok_or(Error::Empty)?
225    }
226}
227
228/// Turn the frame channel into the typed item stream a caller sees.
229///
230/// The exchange is `Ack (Item|Error)* Done`. `Ack` says a response is
231/// coming and carries nothing, so it is consumed silently; `Error` is
232/// yielded and the run CONTINUES, matching the wire; `Done` ends the
233/// stream. The channel closing also ends it, which is what a dropped
234/// connection looks like from here.
235fn stream<T>(
236    rx: mpsc::UnboundedReceiver<CliResponse>,
237    registered: Registered,
238) -> impl Stream<Item = Result<T, Error>> + Send
239where
240    T: serde::de::DeserializeOwned + Send + 'static,
241{
242    futures::stream::unfold(
243        (rx, Some(registered)),
244        |(mut rx, registered)| async move {
245            loop {
246                let frame = rx.recv().await?;
247                match frame {
248                    // Nothing to hand a caller; it exists so the SERVER
249                    // knows a slow run was picked up.
250                    CliResponse::Ack { .. } => continue,
251                    CliResponse::Item { item, .. } => {
252                        return Some((decode(&item), (rx, registered)));
253                    }
254                    CliResponse::Error { error, .. } => {
255                        return Some((Err(Error::Host(error)), (rx, registered)));
256                    }
257                    // Terminal. Dropping `registered` here deregisters
258                    // the run rather than waiting for the caller to
259                    // drop the stream.
260                    CliResponse::Done { .. } => return None,
261                }
262            }
263        },
264    )
265    // `unfold` holds the guard in its state, so it is dropped whenever
266    // the stream is — completed, cancelled or abandoned alike.
267    .map(|item| item)
268}
269
270/// One wire item, as the type the caller asked for.
271///
272/// THIS is where the payload is finally parsed — the first and only
273/// place that knows what it should be, because `T` is the leaf the
274/// caller named. The frame carried the producer's literal bytes to
275/// get here untouched.
276///
277/// It used to arrive as the untagged `ResponseItem` sum, which meant
278/// the item was parsed as whichever of the ~400 leaves matched it
279/// first and re-encoded here; anything that guess did not model was
280/// already gone (see [`objectiveai_sdk::mcp::CliResponse::Item`]).
281/// A CLI-reported failure rides the same shape, so it is tried
282/// first.
283fn decode<T>(item: &serde_json::value::RawValue) -> Result<T, Error>
284where
285    T: serde::de::DeserializeOwned,
286{
287    if let Ok(error) =
288        serde_json::from_str::<objectiveai_sdk::cli::Error>(item.get())
289    {
290        return Err(Error::Cli(error));
291    }
292    serde_json::from_str(item.get()).map_err(Error::Decode)
293}
294
295#[cfg(test)]
296mod tests {
297    use super::*;
298
299    /// The path the host derives by appending the SDK's suffix to the
300    /// MCP url — if these drift, the host POSTs into a 404 and every
301    /// command hangs.
302    #[test]
303    fn the_command_path_is_the_sdk_suffix() {
304        assert_eq!(COMMAND_PATH, "/objectiveai/command");
305    }
306
307    /// Delivery routes purely by id, and an unknown id is dropped
308    /// rather than panicking — a run whose caller walked away must not
309    /// be able to take the endpoint down.
310    #[tokio::test]
311    async fn frames_route_by_id_and_unknown_ids_are_dropped() {
312        let (tx, mut rx) = mpsc::unbounded_channel();
313        PENDING.insert("known".to_string(), tx);
314
315        deliver(CliResponse::Ack { id: "known".into() });
316        deliver(CliResponse::Ack { id: "nobody-is-waiting".into() });
317
318        assert!(matches!(rx.recv().await, Some(CliResponse::Ack { .. })));
319        assert!(rx.try_recv().is_err(), "the stray frame went nowhere");
320        PENDING.remove("known");
321    }
322
323    /// Dropping the stream deregisters the run, so a late frame has
324    /// nowhere to land and the map does not grow.
325    #[tokio::test]
326    async fn dropping_the_stream_deregisters_the_run() {
327        let (tx, rx) = mpsc::unbounded_channel();
328        PENDING.insert("abandoned".to_string(), tx);
329        let stream = stream::<serde_json::Value>(rx, Registered("abandoned".to_string()));
330
331        assert!(PENDING.contains_key("abandoned"));
332        drop(stream);
333        assert!(!PENDING.contains_key("abandoned"));
334    }
335
336    /// `Ack` is consumed, `Item` is yielded, `Done` ends it — the
337    /// whole exchange shape in one pass.
338    #[tokio::test]
339    async fn an_exchange_yields_only_its_items() {
340        let (tx, rx) = mpsc::unbounded_channel();
341        let id = "exchange";
342        PENDING.insert(id.to_string(), tx.clone());
343
344        tx.send(CliResponse::Ack { id: id.into() }).unwrap();
345        tx.send(CliResponse::Error {
346            id: id.into(),
347            error: "upstream said no".into(),
348        })
349        .unwrap();
350        tx.send(CliResponse::Done { id: id.into() }).unwrap();
351
352        let items: Vec<_> = stream::<serde_json::Value>(rx, Registered(id.to_string()))
353            .collect()
354            .await;
355        assert_eq!(items.len(), 1, "the ack and the done are not items");
356        assert!(matches!(items[0], Err(Error::Host(_))));
357    }
358}