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}