mnemo_engine/embed_cmd.rs
1//! [`EmbedCmd`] — spawn a child process once, speak a line-delimited
2//! JSON protocol to it, reuse it for every subsequent embed (Phase 3,
3//! PR 10b + 10b.2).
4//!
5//! Motivation: a Python embedder loading `sentence-transformers` can
6//! take seconds just to import, so the obvious design — spawn one
7//! child per embed — makes MCP unusably slow. Instead the child runs
8//! once per [`crate::Mnemo`] handle, reads a line of JSON per request
9//! from stdin, writes a line of JSON per response to stdout, and keeps
10//! running until the handle is dropped (closing stdin, which the
11//! child uses as its exit signal).
12//!
13//! ### Protocol
14//! - **Input (one per line):** a JSON-encoded string. Newlines inside
15//! the string are escaped as `\n` by JSON, so framing is unambiguous.
16//! - **With a query convention** (12.3 step 4, v0.15: `--embed-query
17//! <convention>`, [`EmbedderIdentity::query_convention`] not empty), each
18//! input line is instead a JSON object saying which side the text is:
19//! `{"kind":"query","text":"…"}` for a recall, `{"kind":"document","text":"…"}`
20//! for everything stored. One child serves both sides for the handle's
21//! whole life, so the side travels with each request. Without a
22//! convention the protocol is unchanged.
23//! - **Output (one per line):** a JSON array of floats, in the same
24//! order as the inputs.
25//! - The child **must `flush()` stdout after each line** or the next
26//! [`EmbedCmd::embed`] call will time out (default 60s, configurable
27//! via [`EmbedCmd::with_timeout`] and the `--embed-timeout` CLI
28//! flag).
29//! - **Stdout is reserved for replies only.** Any line written to
30//! stdout outside a reply (startup banners, log messages, warnings)
31//! is treated as a protocol violation — EmbedCmd restarts the child
32//! and surfaces a clear error. Log to **stderr** instead; stderr is
33//! inherited to the parent and is safe to use.
34//! - Dimensionality is enforced per-vector; wrong-width or malformed
35//! replies cause the child to be killed and respawned on the next
36//! call, so no mismatched vector is ever returned.
37//!
38//! ### Reference embedder (Python + sentence-transformers)
39//! ```python
40//! import sys, json
41//! from sentence_transformers import SentenceTransformer
42//! m = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")
43//! for line in sys.stdin:
44//! text = json.loads(line) # one string
45//! v = m.encode([text], normalize_embeddings=True)[0].tolist()
46//! print(json.dumps(v), flush=True) # one JSON array
47//! # Any logs: print("…", file=sys.stderr, flush=True)
48//! ```
49//! Then start the engine with:
50//! `mnemo serve --mcp agent.mnemo --embed-cmd "python3 embedder.py" --embed-name "sentence-transformers/all-MiniLM-L6-v2"`
51//!
52//! ### Correctness guarantees (PR 10b.2)
53//! - **Real timeouts.** A background thread owns the child's stdout
54//! and drains lines into a channel; [`EmbedCmd::embed`] reads via
55//! `recv_timeout`, so a silent-but-alive child trips the timeout
56//! deterministically. The reader thread also keeps stdout drained
57//! while we write stdin, which prevents the large-batch deadlock a
58//! write-all-then-read-all design would have.
59//! - **Never a mismatched vector.** Any protocol error (write failure,
60//! timeout, EOF, malformed JSON, wrong width, zero vector, or
61//! unsolicited stdout output before a request) kills the child, drops
62//! the reader thread, and marks the adapter for restart. The next
63//! [`EmbedCmd::embed`] call spawns a fresh child + reader thread
64//! with the same argv/env/timeout before writing anything, and logs
65//! one line to stderr saying it restarted and why. The alternative
66//! — reading leftover output as a new reply — would silently
67//! corrupt recall quality, which is strictly worse than any error.
68
69use std::io::{BufRead, BufReader, Write};
70use std::process::{Child, ChildStdin, Command, Stdio};
71use std::sync::mpsc::{self, Receiver, RecvTimeoutError, TryRecvError};
72use std::sync::Mutex;
73use std::thread::JoinHandle;
74use std::time::{Duration, Instant};
75
76use crate::embed::{Embedder, EmbedderIdentity};
77use crate::error::{MnemoError, Result};
78
79/// Default per-request timeout. Set generously because a cold-start
80/// `sentence-transformers` call can genuinely take a few seconds the
81/// first time; configurable via [`EmbedCmd::with_timeout`] (Rust API)
82/// or the `--embed-timeout` CLI flag.
83pub const DEFAULT_EMBED_TIMEOUT: Duration = Duration::from_secs(60);
84
85/// What the reader thread sends over the channel. One `Line` per
86/// stdout line the child wrote, then exactly one terminal `Eof` or
87/// `Err(_)` and the thread exits.
88enum ReaderMsg {
89 Line(String),
90 Eof,
91 Err(String),
92}
93
94/// Persistent-child-process adapter for a user-supplied embedder
95/// command. See the module docs for the protocol.
96pub struct EmbedCmd {
97 identity: EmbedderIdentity,
98 /// Running-child state lives inside a `Mutex` so [`Embedder`] can
99 /// be `Sync` (the engine holds the embedder as `Arc<dyn Embedder>`
100 /// and the trait's `embed(&self, …)` is called via `&self`). The
101 /// lock is only held for the duration of one batch, which the
102 /// `&mut Mnemo` serialization already enforces at the call site.
103 state: Mutex<Option<ChildState>>,
104 timeout: Duration,
105 /// Pretty command string for error messages — the raw argv as
106 /// parsed, joined back for display. Not used for execution.
107 cmd_display: String,
108 /// Argv the next spawn will use. Captured from `cmd` at
109 /// construction so a respawn after error reuses identical args.
110 argv: Vec<String>,
111}
112
113/// All the handles belonging to one running child + its reader thread.
114struct ChildState {
115 child: Child,
116 stdin: ChildStdin,
117 /// Receives each stdout line (or the terminal `Eof`/`Err`) from
118 /// the reader thread. Dropping the sender inside the thread lets
119 /// `recv_timeout` detect EOF after the terminal message.
120 stdout_rx: Receiver<ReaderMsg>,
121 /// Reader thread handle, kept for `Drop`. Joining is best-effort —
122 /// the thread exits once the child's stdout closes, which happens
123 /// when we kill the child in [`EmbedCmd::teardown`].
124 reader: Option<JoinHandle<()>>,
125}
126
127impl EmbedCmd {
128 /// Spawn `cmd` (a shell-style command string: `"python3 embedder.py"`
129 /// or `"my-tool --model=foo"`) and prepare it to accept embed
130 /// requests. The command is split by whitespace and single/double
131 /// quotes — see [`shlex_split`] — and the program is launched
132 /// directly, **not** through a shell. On Windows this means
133 /// forward-slash paths work; on Unix it means no `~` expansion
134 /// and no environment-variable substitution.
135 ///
136 /// `identity` is the [`EmbedderIdentity`] this adapter will report;
137 /// it is matched against the database's manifest by
138 /// [`crate::Mnemo::set_embedder`]. Pick values that describe what
139 /// the child process actually computes — mismatched identities
140 /// would corrupt recall silently.
141 pub fn new(cmd: &str, identity: EmbedderIdentity) -> Result<Self> {
142 let argv = shlex_split(cmd).ok_or_else(|| {
143 MnemoError::Invalid(format!(
144 "could not parse embed-cmd (unbalanced quote?): {cmd:?}"
145 ))
146 })?;
147 if argv.is_empty() {
148 return Err(MnemoError::Invalid(
149 "embed-cmd is empty — pass a program path".into(),
150 ));
151 }
152 let state = spawn_child(&argv)?;
153 Ok(Self {
154 identity,
155 state: Mutex::new(Some(state)),
156 timeout: DEFAULT_EMBED_TIMEOUT,
157 cmd_display: cmd.to_string(),
158 argv,
159 })
160 }
161
162 /// Replace the per-request timeout. See [`DEFAULT_EMBED_TIMEOUT`].
163 pub fn with_timeout(mut self, timeout: Duration) -> Self {
164 self.timeout = timeout;
165 self
166 }
167}
168
169impl Drop for EmbedCmd {
170 fn drop(&mut self) {
171 if let Ok(mut slot) = self.state.lock() {
172 if let Some(st) = slot.take() {
173 teardown(st);
174 }
175 }
176 }
177}
178
179/// Kill the child, best-effort reap, drop the stdin / receiver, and
180/// join the reader thread. Used both on `Drop` and whenever a protocol
181/// error marks the adapter for restart.
182fn teardown(mut st: ChildState) {
183 let _ = st.stdin.flush();
184 // Dropping stdin by moving it out ends the child's own read loop
185 // on EOF for well-behaved embedders.
186 drop(st.stdin);
187 // Give the child a brief moment to exit on its own.
188 let _ = st.child.try_wait();
189 // Then kill and reap. `wait()` is required to avoid a zombie.
190 let _ = st.child.kill();
191 let _ = st.child.wait();
192 // Dropping the receiver unblocks the reader thread's send on the
193 // next line (channel closed → send errors → thread exits). Joining
194 // is best-effort: if the thread was blocked in `read_line` and the
195 // child-killed stdout close didn't wake it fast enough, we don't
196 // want to hold Drop indefinitely.
197 drop(st.stdout_rx);
198 if let Some(j) = st.reader.take() {
199 // Discard the join result — any panic in the reader thread is
200 // already behind us; we can't propagate it from Drop anyway.
201 let _ = j.join();
202 }
203}
204
205/// Spawn one child + reader thread. Returns a fresh [`ChildState`].
206fn spawn_child(argv: &[String]) -> Result<ChildState> {
207 let (program, args) = argv.split_first().expect("argv non-empty by caller");
208 // The child gets the text to embed, never the brain's secret.
209 let mut command = Command::new(program);
210 for var in crate::keys::SECRET_ENV_VARS {
211 command.env_remove(var);
212 }
213 let mut child = command
214 .args(args)
215 .stdin(Stdio::piped())
216 .stdout(Stdio::piped())
217 .stderr(Stdio::inherit())
218 .spawn()
219 .map_err(|e| {
220 MnemoError::Invalid(format!(
221 "could not spawn embed-cmd {program:?}: {e} \
222 (program must be on PATH and executable)"
223 ))
224 })?;
225 let stdin = child.stdin.take().expect("stdin was piped above");
226 let stdout = BufReader::new(child.stdout.take().expect("stdout was piped above"));
227 let (tx, rx) = mpsc::channel::<ReaderMsg>();
228 let reader = std::thread::Builder::new()
229 .name("mnemo-embed-cmd-reader".into())
230 .spawn(move || {
231 let mut rdr = stdout;
232 let mut buf = String::new();
233 loop {
234 buf.clear();
235 match rdr.read_line(&mut buf) {
236 Ok(0) => {
237 let _ = tx.send(ReaderMsg::Eof);
238 break;
239 }
240 Ok(_) => {
241 if tx.send(ReaderMsg::Line(buf.clone())).is_err() {
242 // Receiver dropped — nothing to do but exit.
243 break;
244 }
245 }
246 Err(e) => {
247 let _ = tx.send(ReaderMsg::Err(e.to_string()));
248 break;
249 }
250 }
251 }
252 })
253 .map_err(|e| {
254 MnemoError::Invalid(format!("could not start embed-cmd reader thread: {e}"))
255 })?;
256 Ok(ChildState {
257 child,
258 stdin,
259 stdout_rx: rx,
260 reader: Some(reader),
261 })
262}
263
264impl EmbedCmd {
265 /// Ensure a running child is available, respawning if necessary.
266 /// On respawn, logs one stderr line explaining why.
267 fn ensure_child<'a>(
268 &self,
269 slot: &'a mut Option<ChildState>,
270 reason_if_respawn: &str,
271 ) -> Result<&'a mut ChildState> {
272 if slot.is_none() {
273 eprintln!(
274 "mnemo embed-cmd: restarting {} ({})",
275 self.cmd_display, reason_if_respawn
276 );
277 *slot = Some(spawn_child(&self.argv)?);
278 }
279 Ok(slot.as_mut().expect("just filled"))
280 }
281
282 /// Fail the current request with `msg`, kill the child, mark for
283 /// restart. The next `embed()` call spawns a fresh child.
284 fn fail_and_restart(&self, slot: &mut Option<ChildState>, msg: String) -> MnemoError {
285 if let Some(st) = slot.take() {
286 teardown(st);
287 }
288 MnemoError::Invalid(msg)
289 }
290}
291
292/// Which side of the protocol a request is (12.3 step 4).
293#[derive(Clone, Copy)]
294enum Side {
295 Document,
296 Query,
297}
298
299impl Embedder for EmbedCmd {
300 fn identity(&self) -> EmbedderIdentity {
301 self.identity.clone()
302 }
303
304 fn embed(&self, texts: &[&str]) -> Result<Vec<Vec<f32>>> {
305 self.run(texts, Side::Document)
306 }
307
308 fn embed_query(&self, texts: &[&str]) -> Result<Vec<Vec<f32>>> {
309 self.run(texts, Side::Query)
310 }
311}
312
313impl EmbedCmd {
314 /// One request line: a JSON string, or, with a query convention, an
315 /// object naming the side.
316 fn request_line(&self, text: &str, side: Side) -> Result<String> {
317 let r = if self.identity.query_convention.is_empty() {
318 serde_json::to_string(text)
319 } else {
320 let kind = match side {
321 Side::Document => "document",
322 Side::Query => "query",
323 };
324 serde_json::to_string(&serde_json::json!({ "kind": kind, "text": text }))
325 };
326 r.map_err(|e| MnemoError::Invalid(format!("could not encode embed-cmd input: {e}")))
327 }
328
329 fn run(&self, texts: &[&str], side: Side) -> Result<Vec<Vec<f32>>> {
330 if texts.is_empty() {
331 return Ok(Vec::new());
332 }
333 let mut slot = self.state.lock().map_err(|_| {
334 MnemoError::Invalid("embed-cmd state poisoned by an earlier panic".into())
335 })?;
336
337 // Respawn if the previous call tore the child down.
338 self.ensure_child(&mut slot, "previous request errored")?;
339
340 // Before writing, probe the channel. Any message waiting here
341 // is unsolicited (the previous call either read all its replies
342 // or restarted); treat it as a protocol violation. One probe
343 // is enough — the first stale message already means the pipe
344 // state is wrong, and we're going to kill + respawn anyway.
345 {
346 let st = slot.as_mut().expect("ensure_child above");
347 match st.stdout_rx.try_recv() {
348 Ok(ReaderMsg::Line(line)) => {
349 return Err(self.fail_and_restart(
350 &mut slot,
351 format!(
352 "embed-cmd {} wrote to stdout outside a reply (line: {:?}). \
353 Stdout is reserved for replies only; log to stderr instead. \
354 The child has been killed; the next call will respawn.",
355 self.cmd_display,
356 line.trim_end()
357 ),
358 ));
359 }
360 Ok(ReaderMsg::Eof) => {
361 return Err(self.fail_and_restart(
362 &mut slot,
363 format!(
364 "embed-cmd {} closed stdout before this request. \
365 The next call will respawn.",
366 self.cmd_display
367 ),
368 ));
369 }
370 Ok(ReaderMsg::Err(e)) => {
371 return Err(self.fail_and_restart(
372 &mut slot,
373 format!(
374 "embed-cmd {} stdout read error before this request: {e}. \
375 The next call will respawn.",
376 self.cmd_display
377 ),
378 ));
379 }
380 Err(TryRecvError::Empty) => {}
381 Err(TryRecvError::Disconnected) => {
382 // Reader thread gone; respawn next call.
383 return Err(self.fail_and_restart(
384 &mut slot,
385 format!(
386 "embed-cmd {} reader thread died. The next call will respawn.",
387 self.cmd_display
388 ),
389 ));
390 }
391 }
392 }
393
394 // Also probe for a dead child (OS-level reap).
395 {
396 let st = slot.as_mut().expect("ensure_child above");
397 if let Some(status) = st.child.try_wait().map_err(|e| {
398 MnemoError::Invalid(format!(
399 "could not probe embed-cmd {}: {e}",
400 self.cmd_display
401 ))
402 })? {
403 return Err(self.fail_and_restart(
404 &mut slot,
405 format!(
406 "embed-cmd {} exited before this request: {status}. \
407 The next call will respawn.",
408 self.cmd_display
409 ),
410 ));
411 }
412 }
413
414 // Write all inputs. The reader thread drains stdout in parallel
415 // so we don't deadlock on a large batch where the child's
416 // stdout fills before our stdin writes finish.
417 {
418 let st = slot.as_mut().expect("ensure_child above");
419 for t in texts {
420 let line = self.request_line(t, side)?;
421 if let Err(e) = writeln!(st.stdin, "{line}") {
422 return Err(self.fail_and_restart(
423 &mut slot,
424 format!(
425 "could not write to embed-cmd {}: {e}. The next call will respawn.",
426 self.cmd_display
427 ),
428 ));
429 }
430 }
431 if let Err(e) = st.stdin.flush() {
432 return Err(self.fail_and_restart(
433 &mut slot,
434 format!(
435 "could not flush embed-cmd {}: {e}. The next call will respawn.",
436 self.cmd_display
437 ),
438 ));
439 }
440 }
441
442 // Read exactly `texts.len()` reply lines, honoring the timeout.
443 // Any failure (timeout, EOF mid-batch, malformed JSON, wrong
444 // width, zero vector) kills the child so stale leftover output
445 // can't be mis-attributed to a later call.
446 let deadline = Instant::now() + self.timeout;
447 let mut out = Vec::with_capacity(texts.len());
448 for i in 0..texts.len() {
449 let remaining = deadline
450 .checked_duration_since(Instant::now())
451 .unwrap_or(Duration::ZERO);
452 let msg = {
453 let st = slot.as_mut().expect("ensure_child above");
454 st.stdout_rx.recv_timeout(remaining)
455 };
456 let line = match msg {
457 Ok(ReaderMsg::Line(l)) => l,
458 Ok(ReaderMsg::Eof) => {
459 return Err(self.fail_and_restart(
460 &mut slot,
461 format!(
462 "embed-cmd {} closed stdout while waiting for reply {}/{}. \
463 The next call will respawn.",
464 self.cmd_display,
465 i + 1,
466 texts.len()
467 ),
468 ));
469 }
470 Ok(ReaderMsg::Err(e)) => {
471 return Err(self.fail_and_restart(
472 &mut slot,
473 format!(
474 "embed-cmd {} stdout read error on reply {}/{}: {e}. \
475 The next call will respawn.",
476 self.cmd_display,
477 i + 1,
478 texts.len()
479 ),
480 ));
481 }
482 Err(RecvTimeoutError::Timeout) => {
483 return Err(self.fail_and_restart(
484 &mut slot,
485 format!(
486 "embed-cmd {} timed out after {:?} waiting for reply {}/{}. \
487 The next call will respawn.",
488 self.cmd_display,
489 self.timeout,
490 i + 1,
491 texts.len()
492 ),
493 ));
494 }
495 Err(RecvTimeoutError::Disconnected) => {
496 return Err(self.fail_and_restart(
497 &mut slot,
498 format!(
499 "embed-cmd {} reader thread exited mid-request. \
500 The next call will respawn.",
501 self.cmd_display
502 ),
503 ));
504 }
505 };
506 let v: Vec<f32> = match serde_json::from_str(line.trim()) {
507 Ok(v) => v,
508 Err(e) => {
509 return Err(self.fail_and_restart(
510 &mut slot,
511 format!(
512 "embed-cmd {} returned malformed JSON on reply {}/{}: {e} (line: {:?}). \
513 The next call will respawn.",
514 self.cmd_display,
515 i + 1,
516 texts.len(),
517 line.trim_end()
518 ),
519 ));
520 }
521 };
522 if v.len() != self.identity.dimensions {
523 return Err(self.fail_and_restart(
524 &mut slot,
525 format!(
526 "embed-cmd {} returned {} dims on reply {}/{} but identity says {}. \
527 The next call will respawn.",
528 self.cmd_display,
529 v.len(),
530 i + 1,
531 texts.len(),
532 self.identity.dimensions
533 ),
534 ));
535 }
536 // FIX-1 R-001.6: the module doc (Correctness guarantees)
537 // already promises "any protocol error (… zero vector …)
538 // kills the child", but the check was missing before this
539 // PR — a buggy embedder returning `[0, 0, 0, …]` or
540 // `[NaN, …]` on one text would silently poison recall
541 // (Mnemo::remember refuses all-zero itself, but a cache
542 // write via `cache_get_semantic` or a `recall --text` call
543 // happily consumed the result). Reject both shapes
544 // through the same `fail_and_restart` path as a wrong
545 // width so the child is killed, the reader thread drops,
546 // and the next call spawns a fresh child.
547 if v.iter().all(|&x| x == 0.0) {
548 return Err(self.fail_and_restart(
549 &mut slot,
550 format!(
551 "embed-cmd {} returned an all-zero vector on reply {}/{} \
552 (an all-zero vector cannot be scored by cosine or dot-product \
553 similarity; the module docs promise this is a protocol error). \
554 The next call will respawn.",
555 self.cmd_display,
556 i + 1,
557 texts.len()
558 ),
559 ));
560 }
561 if v.iter().any(|x| !x.is_finite()) {
562 return Err(self.fail_and_restart(
563 &mut slot,
564 format!(
565 "embed-cmd {} returned a non-finite value (NaN or ±∞) on \
566 reply {}/{}. The next call will respawn.",
567 self.cmd_display,
568 i + 1,
569 texts.len()
570 ),
571 ));
572 }
573 out.push(v);
574 }
575 Ok(out)
576 }
577}
578
579/// Minimal shell-style tokenizer: splits on whitespace, honors
580/// single and double quotes, no backslash-escaping, no shell
581/// expansions. Returns `None` on an unbalanced quote.
582///
583/// Enough for the embedder-cmd use case where users pass something
584/// like `python3 embedder.py --model foo` or
585/// `"C:\Program Files\myembed.exe" --model foo`.
586pub(crate) fn shlex_split(input: &str) -> Option<Vec<String>> {
587 let mut out: Vec<String> = Vec::new();
588 let mut cur = String::new();
589 let mut in_single = false;
590 let mut in_double = false;
591 let mut had_content = false;
592 for c in input.chars() {
593 match c {
594 '\'' if !in_double => {
595 in_single = !in_single;
596 had_content = true;
597 }
598 '"' if !in_single => {
599 in_double = !in_double;
600 had_content = true;
601 }
602 c if c.is_whitespace() && !in_single && !in_double => {
603 if had_content {
604 out.push(std::mem::take(&mut cur));
605 had_content = false;
606 }
607 }
608 c => {
609 cur.push(c);
610 had_content = true;
611 }
612 }
613 }
614 if in_single || in_double {
615 return None;
616 }
617 if had_content {
618 out.push(cur);
619 }
620 Some(out)
621}
622
623#[cfg(test)]
624mod tests {
625 use super::*;
626
627 #[test]
628 fn shlex_handles_bare_quoted_mixed() {
629 assert_eq!(shlex_split("a b c").unwrap(), vec!["a", "b", "c"]);
630 assert_eq!(
631 shlex_split("python3 'my script.py' --model foo").unwrap(),
632 vec!["python3", "my script.py", "--model", "foo"]
633 );
634 assert_eq!(
635 shlex_split(r#""C:\Program Files\x.exe" --flag"#).unwrap(),
636 vec![r"C:\Program Files\x.exe", "--flag"]
637 );
638 }
639
640 #[test]
641 fn shlex_rejects_unbalanced() {
642 assert!(shlex_split("python 'oops").is_none());
643 assert!(shlex_split("python \"oops").is_none());
644 }
645
646 #[test]
647 fn shlex_handles_empty() {
648 assert_eq!(shlex_split("").unwrap(), Vec::<String>::new());
649 assert_eq!(shlex_split(" ").unwrap(), Vec::<String>::new());
650 }
651}