Publish harness and TUI open-source

initial sync from the monorepo

crates/common/xai-interjection-core/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+license = "Apache-2.0"
+name = "xai-interjection-core"
+version = "0.1.0"
+edition.workspace = true
+description = "Shared mid-turn interjection buffer and formatting for the client and server agent loops"
+
+[dependencies]
+serde = { workspace = true }
+
+[lints]
+workspace = true

crates/common/xai-interjection-core/src/buffer.rs

@@ -0,0 +1,75 @@
+use serde::{Deserialize, Serialize};
+
+use crate::events::EventQueue;
+use crate::format::format_interjection;
+
+/// A buffered mid-turn interjection awaiting the next safe drain point.
+/// `Attachment` is host-defined (inline images, asset IDs); core never reads it.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct PendingInterjection<Attachment> {
+    pub text: String,
+    pub attachments: Vec<Attachment>,
+}
+
+/// A drained entry, wrapped and ready to emit as a synthetic user message.
+#[derive(Debug, Clone, PartialEq)]
+pub struct FormattedInterjection<Attachment> {
+    pub text: String,
+    pub attachments: Vec<Attachment>,
+}
+
+/// A queue of pending interjections — just an [`EventQueue`] of
+/// [`PendingInterjection`]. Use [`drain_formatted`] to drain + frame them as
+/// synthetic user messages.
+pub type InterjectionBuffer<Attachment> = EventQueue<PendingInterjection<Attachment>>;
+
+/// Drain `buffer`, framing each entry as a synthetic user message (FIFO, one
+/// message per entry, never merged). `sanitize_text` runs on the raw text first
+/// (hosts strip artifacts like image placeholder paths; pass
+/// `std::convert::identity` if none).
+pub fn drain_formatted<Attachment>(
+    buffer: &InterjectionBuffer<Attachment>,
+    sanitize_text: impl Fn(String) -> String,
+) -> Vec<FormattedInterjection<Attachment>> {
+    buffer
+        .drain_all()
+        .into_iter()
+        .map(|entry| FormattedInterjection {
+            text: format_interjection(sanitize_text(entry.text)),
+            attachments: entry.attachments,
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn drain_formatted_sanitizes_wraps_and_preserves_order() {
+        let buf: InterjectionBuffer<()> = InterjectionBuffer::new();
+        buf.push(PendingInterjection {
+            text: "look at [SECRET] one".into(),
+            attachments: vec![],
+        });
+        buf.push(PendingInterjection {
+            text: "two".into(),
+            attachments: vec![],
+        });
+
+        let out = drain_formatted(&buf, |t| t.replace("[SECRET] ", ""));
+        assert!(buf.is_empty());
+        assert_eq!(out.len(), 2, "one message per entry, never merged");
+        assert!(
+            out[0]
+                .text
+                .contains("<user_query>\nlook at one\n</user_query>")
+        );
+        assert!(out[1].text.contains("<user_query>\ntwo\n</user_query>"));
+        assert!(
+            out[0]
+                .text
+                .starts_with("The user sent a message while you were working:")
+        );
+    }
+}

crates/common/xai-interjection-core/src/events.rs

@@ -0,0 +1,178 @@
+//! Shared event queue for the push path: producers enqueue out-of-band events;
+//! readers drain the ones relevant to them at hook points. Internally
+//! synchronized and `Arc`-shared (clones share one queue), mirroring
+//! [`crate::buffer::InterjectionBuffer`].
+
+use std::sync::{Arc, Mutex, MutexGuard};
+
+#[derive(Debug)]
+pub struct EventQueue<E> {
+    events: Arc<Mutex<Vec<E>>>,
+}
+
+impl<E> Clone for EventQueue<E> {
+    fn clone(&self) -> Self {
+        Self {
+            events: Arc::clone(&self.events),
+        }
+    }
+}
+
+impl<E> Default for EventQueue<E> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl<E> EventQueue<E> {
+    pub fn new() -> Self {
+        Self {
+            events: Arc::new(Mutex::new(Vec::new())),
+        }
+    }
+
+    /// Producer hook: record an event for later draining.
+    pub fn push(&self, event: E) {
+        self.lock().push(event);
+    }
+
+    /// Push, then drop the oldest events so at most `max` remain.
+    pub fn push_capped(&self, event: E, max: usize) {
+        let mut q = self.lock();
+        q.push(event);
+        if q.len() > max {
+            let excess = q.len() - max;
+            q.drain(..excess);
+        }
+    }
+
+    pub fn len(&self) -> usize {
+        self.lock().len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.lock().is_empty()
+    }
+
+    /// Remove and return events matching `take`, retaining the rest. FIFO order
+    /// is preserved in both the returned and retained sets.
+    pub fn drain_matching(&self, take: impl Fn(&E) -> bool) -> Vec<E> {
+        let mut q = self.lock();
+        let (matched, kept): (Vec<E>, Vec<E>) =
+            std::mem::take(&mut *q).into_iter().partition(|e| take(e));
+        *q = kept;
+        matched
+    }
+
+    /// Remove and return all events, leaving the queue empty (FIFO order).
+    pub fn drain_all(&self) -> Vec<E> {
+        std::mem::take(&mut *self.lock())
+    }
+
+    /// Discard all events.
+    pub fn clear(&self) {
+        self.lock().clear();
+    }
+
+    fn lock(&self) -> MutexGuard<'_, Vec<E>> {
+        self.events.lock().unwrap_or_else(|e| e.into_inner())
+    }
+}
+
+impl<E: Clone> EventQueue<E> {
+    /// Clone of the current events, for inspection without draining.
+    pub fn snapshot(&self) -> Vec<E> {
+        self.lock().clone()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn push_and_len() {
+        let q: EventQueue<u32> = EventQueue::new();
+        assert!(q.is_empty());
+        q.push(1);
+        q.push(2);
+        assert_eq!(q.len(), 2);
+    }
+
+    #[test]
+    fn clones_share_one_queue() {
+        let q: EventQueue<u32> = EventQueue::new();
+        let q2 = q.clone();
+        q.push(7);
+        assert_eq!(q2.len(), 1);
+    }
+
+    #[test]
+    fn push_capped_drops_oldest() {
+        let q: EventQueue<u32> = EventQueue::new();
+        for i in 0..5 {
+            q.push_capped(i, 3);
+        }
+        assert_eq!(q.drain_matching(|_| true), vec![2, 3, 4]);
+        assert!(q.is_empty());
+    }
+
+    #[test]
+    fn drain_matching_returns_matched_retains_rest_fifo() {
+        let q: EventQueue<u32> = EventQueue::new();
+        for i in 0..6 {
+            q.push(i);
+        }
+        let evens = q.drain_matching(|n| n % 2 == 0);
+        assert_eq!(evens, vec![0, 2, 4]);
+        assert_eq!(q.drain_matching(|_| true), vec![1, 3, 5]);
+    }
+
+    #[test]
+    fn push_capped_under_limit_keeps_all() {
+        let q: EventQueue<u32> = EventQueue::new();
+        q.push_capped(1, 5);
+        q.push_capped(2, 5);
+        assert_eq!(q.drain_matching(|_| true), vec![1, 2]);
+    }
+
+    #[test]
+    fn drain_matching_none_match_retains_all() {
+        let q: EventQueue<u32> = EventQueue::new();
+        q.push(1);
+        q.push(2);
+        assert!(q.drain_matching(|n| *n > 10).is_empty());
+        assert_eq!(q.len(), 2);
+    }
+
+    #[test]
+    fn drain_matching_on_empty_is_empty() {
+        let q: EventQueue<u32> = EventQueue::new();
+        assert!(q.drain_matching(|_| true).is_empty());
+    }
+
+    #[test]
+    fn drain_all_empties_in_fifo_order() {
+        let q: EventQueue<u32> = EventQueue::new();
+        q.push(1);
+        q.push(2);
+        assert_eq!(q.drain_all(), vec![1, 2]);
+        assert!(q.is_empty());
+    }
+
+    #[test]
+    fn clear_discards_all() {
+        let q: EventQueue<u32> = EventQueue::new();
+        q.push(1);
+        q.clear();
+        assert!(q.is_empty());
+    }
+
+    #[test]
+    fn snapshot_reads_without_draining() {
+        let q: EventQueue<u32> = EventQueue::new();
+        q.push(9);
+        assert_eq!(q.snapshot(), vec![9]);
+        assert_eq!(q.len(), 1);
+    }
+}

crates/common/xai-interjection-core/src/format.rs

@@ -0,0 +1,60 @@
+/// Truncation threshold, matching the shell's large-prompt limit.
+pub const LARGE_PROMPT_THRESHOLD: usize = 25_000;
+
+/// Wrap a user message in the canonical `<user_query>` envelope.
+pub fn user_query(user_message: &str) -> String {
+    format!(
+        r#"<user_query>
+{user_message}
+</user_query>"#
+    )
+}
+
+/// Wrap interjection text as a synthetic user message with a mid-turn note.
+/// No deferral instruction: the model decides how to weigh it against
+/// in-flight work. Output is byte-identical to the shell's historical format.
+pub fn format_interjection(text: String) -> String {
+    let truncated = if text.len() > LARGE_PROMPT_THRESHOLD {
+        let end = text
+            .char_indices()
+            .take_while(|(i, _)| *i < LARGE_PROMPT_THRESHOLD)
+            .last()
+            .map(|(i, c)| i + c.len_utf8())
+            .unwrap_or(text.len());
+        format!("{}... [truncated]", &text[..end])
+    } else {
+        text
+    };
+
+    format!(
+        "The user sent a message while you were working:\n{}",
+        user_query(&truncated)
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn wraps_in_user_query_with_midturn_note() {
+        let out = format_interjection("stop and fix the test first".into());
+        assert!(out.starts_with("The user sent a message while you were working:\n<user_query>\n"));
+        assert!(out.ends_with("\n</user_query>"));
+        assert!(out.contains("stop and fix the test first"));
+    }
+
+    #[test]
+    fn truncates_at_utf8_boundary() {
+        let s = "é".repeat(LARGE_PROMPT_THRESHOLD);
+        let out = format_interjection(s);
+        assert!(out.contains("... [truncated]"));
+        assert!(out.len() < LARGE_PROMPT_THRESHOLD + 200);
+    }
+
+    #[test]
+    fn short_text_untouched() {
+        let out = format_interjection("hi".into());
+        assert!(!out.contains("[truncated]"));
+    }
+}

crates/common/xai-interjection-core/src/lib.rs

@@ -0,0 +1,7 @@
+pub mod buffer;
+pub mod events;
+pub mod format;
+
+pub use buffer::{FormattedInterjection, InterjectionBuffer, PendingInterjection, drain_formatted};
+pub use events::EventQueue;
+pub use format::{LARGE_PROMPT_THRESHOLD, format_interjection, user_query};