Skip to main content

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}