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}