Skip to main content

objectiveai_sdk/cli/command/command_executor/
plugin.rs

1use std::pin::Pin;
2use std::sync::Arc;
3use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
4
5use dashmap::DashMap;
6use futures::{Stream, StreamExt};
7use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
8use tokio::sync::{Mutex, mpsc};
9
10use crate::identity::Identity;
11use crate::cli::command::{
12    CommandExecutor, CommandRequest,
13    CommandResponse as CommandResponseTrait,
14};
15use crate::cli::plugins::{Command, CommandType, Output};
16
17/// Demultiplex many in-flight `CommandRequest` calls over a plugin's
18/// stdin/stdout. Each `execute` mints a fresh id, emits a
19/// `Output::Command(Command { id, command })` line on the plugin's stdout,
20/// and returns a stream that yields whatever the overlord writes back
21/// to the plugin's stdin under the same id.
22///
23/// Only one instance per process — the constructor consumes the global
24/// `tokio::io::stdin()` / `stdout()` handles. The struct is [`Clone`]
25/// so callers that need a second handle can share without an outer
26/// `Arc`: every field is already behind `Arc`, including `counter`, so
27/// clones share the id sequence and pending map.
28#[derive(Clone)]
29pub struct PluginExecutor {
30    stdout: Arc<Mutex<tokio::io::Stdout>>,
31    counter: Arc<AtomicU64>,
32    pending: Arc<DashMap<String, mpsc::UnboundedSender<serde_json::Value>>>,
33    /// `true` while the listener task is still reading stdin. Flipped
34    /// to `false` immediately before the listener drops its pending
35    /// senders, so `execute()` can re-check after registering its own
36    /// sender and bail with `Error::Closed` instead of installing a
37    /// channel nothing will ever drain.
38    listener_alive: Arc<AtomicBool>,
39}
40
41impl Default for PluginExecutor {
42    fn default() -> Self {
43        Self::new()
44    }
45}
46
47impl PluginExecutor {
48    /// Capture the plugin's stdin/stdout and spawn the demuxer task.
49    pub fn new() -> Self {
50        let pending: Arc<DashMap<String, mpsc::UnboundedSender<serde_json::Value>>> =
51            Arc::new(DashMap::new());
52        let listener_alive = Arc::new(AtomicBool::new(true));
53        Self::spawn_listener(
54            tokio::io::stdin(),
55            pending.clone(),
56            listener_alive.clone(),
57        );
58        Self {
59            stdout: Arc::new(Mutex::new(tokio::io::stdout())),
60            counter: Arc::new(AtomicU64::new(0)),
61            pending,
62            listener_alive,
63        }
64    }
65
66    fn spawn_listener(
67        stdin: tokio::io::Stdin,
68        pending: Arc<DashMap<String, mpsc::UnboundedSender<serde_json::Value>>>,
69        listener_alive: Arc<AtomicBool>,
70    ) {
71        tokio::spawn(async move {
72            let mut lines = BufReader::new(stdin).lines();
73            while let Ok(Some(line)) = lines.next_line().await {
74                let env = match serde_json::from_str::<CommandResponse>(&line) {
75                    Ok(e) => e,
76                    Err(_) => continue,
77                };
78                match env {
79                    CommandResponse::Value { id, value } => {
80                        // Host-form stream terminator:
81                        // `{id, value:{type:"command_complete",…}}`. Swallow
82                        // it — end this id's stream, never forward it on.
83                        if value.get("type").and_then(serde_json::Value::as_str)
84                            == Some("command_complete")
85                        {
86                            pending.remove(&id);
87                        } else if let Some(sender) = pending.get(&id) {
88                            if sender.send(value).is_err() {
89                                drop(sender);
90                                pending.remove(&id);
91                            }
92                        }
93                    }
94                    CommandResponse::Done { id, .. } => {
95                        pending.remove(&id);
96                    }
97                }
98            }
99            // stdin EOF or read error. Flip the liveness flag BEFORE
100            // dropping any senders — `execute()` does an insert-then-
101            // re-check, and this ordering guarantees a concurrent
102            // `execute()` either sees the flag and removes its own
103            // entry, or completes its insert before `clear()` runs and
104            // gets drained by it.
105            listener_alive.store(false, Ordering::Release);
106            pending.clear();
107        });
108    }
109}
110
111/// One line the overlord writes to a plugin's stdin in response to a
112/// previously-emitted `Output::Command`.
113///
114/// Wire shape:
115/// - Value: `{"id":"42","value":<JSON>}`
116/// - Done:  `{"id":"42","done":true}`
117///
118/// Two end-of-stream markers are recognized for an id, after which the
119/// request's stream ends: the `Done` form above, and the host's
120/// `command_complete` form — a `Value` whose JSON is
121/// `{"type":"command_complete","exit_code":N}` (handled in the listener,
122/// swallowed, never surfaced to the consumer).
123#[derive(serde::Deserialize, Debug, Clone)]
124#[serde(untagged)]
125enum CommandResponse {
126    /// Listed first so the untagged decoder tries it before `Value` —
127    /// the `done` discriminator field is what tells the variants apart.
128    Done {
129        id: String,
130        #[allow(dead_code)]
131        done: bool,
132    },
133    Value {
134        id: String,
135        value: serde_json::Value,
136    },
137}
138
139#[derive(Debug, thiserror::Error)]
140pub enum Error {
141    /// Stdin closed (clean EOF or read error). The listener task has
142    /// exited and no new requests can be served.
143    #[error("plugin executor stdin closed")]
144    Closed,
145    #[error("plugin executor io: {0}")]
146    Io(std::io::Error),
147    #[error("plugin executor decode line: {0}")]
148    Json(serde_json::Error),
149    #[error("{0}")]
150    Cli(crate::cli::Error),
151    /// `execute_one` was called but the stream produced no items.
152    #[error("plugin executor stream produced no items")]
153    Empty,
154}
155
156/// Per-value untagged decode. `Err` first so `cli::Error`'s `type:"error"`
157/// constant short-circuits non-error wire shapes; `Ok(T)` is the
158/// fallthrough. Mirrors the helper in `binary.rs`.
159#[derive(serde::Deserialize)]
160#[serde(untagged)]
161enum Line<T> {
162    Err(crate::cli::Error),
163    Ok(T),
164}
165
166impl<T> From<Line<T>> for Result<T, Error> {
167    fn from(line: Line<T>) -> Self {
168        match line {
169            Line::Err(e) => Err(Error::Cli(e)),
170            Line::Ok(t) => Ok(t),
171        }
172    }
173}
174
175impl CommandExecutor for PluginExecutor {
176    type Error = Error;
177    type Stream<T>
178        = Pin<Box<dyn Stream<Item = Result<T, Error>> + Send>>
179    where
180        T: Send + 'static;
181
182    async fn execute<R, T>(
183        &self,
184        request: R,
185        // Plugin runs in-process — no subprocess to stamp env on. The
186        // bag is accepted for trait-signature symmetry with the
187        // binary executor and intentionally ignored.
188        _identity: Option<&Identity>,
189    ) -> Result<Self::Stream<T>, Error>
190    where
191        R: CommandRequest + Send + serde::Serialize,
192        T: CommandResponseTrait + serde::Serialize + serde::de::DeserializeOwned + Send + 'static,
193    {
194        let id = self.counter.fetch_add(1, Ordering::Relaxed).to_string();
195        let (tx, rx) = mpsc::unbounded_channel::<serde_json::Value>();
196        self.pending.insert(id.clone(), tx);
197
198        // Re-check liveness AFTER insert. The listener stores `false`
199        // before it calls `pending.clear()`, so any of these happens:
200        //   - We see `true`: listener is still running; if it dies
201        //     later, its `clear()` will drop our sender and the stream
202        //     will end naturally.
203        //   - We see `false` and our entry got cleared: remove() is a
204        //     no-op, sender is already dropped.
205        //   - We see `false` and our entry survived (we inserted after
206        //     `clear()` ran): remove() drops the sender ourselves.
207        // In every `false` path we bail with `Closed`.
208        if !self.listener_alive.load(Ordering::Acquire) {
209            self.pending.remove(&id);
210            return Err(Error::Closed);
211        }
212
213        // Carry the typed request as JSON via the cli's `--request` flag;
214        // the host re-enters `run` with this argv. (request -> argv lowering
215        // no longer exists.)
216        let argv = vec![
217            "--request".to_string(),
218            serde_json::to_string(&request).map_err(Error::Json)?,
219        ];
220        let envelope = Output::Command(Command {
221            r#type: CommandType::Command,
222            id: id.clone(),
223            // Carry argv structured — joining into a single string
224            // would lose argument boundaries for any value containing
225            // whitespace (e.g. `--simple "a b c"`), which the host
226            // could not recover.
227            command: argv,
228        });
229        let line = serde_json::to_string(&envelope).expect("Output serializes");
230
231        {
232            let mut stdout = self.stdout.lock().await;
233            if let Err(e) = stdout.write_all(line.as_bytes()).await {
234                self.pending.remove(&id);
235                return Err(Error::Io(e));
236            }
237            if let Err(e) = stdout.write_all(b"\n").await {
238                self.pending.remove(&id);
239                return Err(Error::Io(e));
240            }
241            if let Err(e) = stdout.flush().await {
242                self.pending.remove(&id);
243                return Err(Error::Io(e));
244            }
245        }
246
247        let pending = self.pending.clone();
248        let stream = futures::stream::unfold(
249            (rx, id, pending),
250            |(mut rx, id, pending)| async move {
251                match rx.recv().await {
252                    Some(value) => {
253                        let item = match serde_json::from_value::<Line<T>>(value) {
254                            Ok(line) => line.into(),
255                            Err(e) => Err(Error::Json(e)),
256                        };
257                        Some((item, (rx, id, pending)))
258                    }
259                    None => {
260                        pending.remove(&id);
261                        None
262                    }
263                }
264            },
265        );
266
267        Ok(Box::pin(stream))
268    }
269
270    async fn execute_one<R, T>(
271        &self,
272        request: R,
273        identity: Option<&Identity>,
274    ) -> Result<T, Error>
275    where
276        R: CommandRequest + Send + serde::Serialize,
277        T: CommandResponseTrait + serde::Serialize + serde::de::DeserializeOwned + Send + 'static,
278    {
279        let mut stream = self.execute::<R, T>(request, identity).await?;
280        stream.next().await.ok_or(Error::Empty)?
281    }
282}