Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

feat(inbound): add keyed debounce state machine

oxoxDev77337d98f39f
diff --git a/crates/openhuman-core/src/inbound_debounce/mod.rs b/crates/openhuman-core/src/inbound_debounce/mod.rs
new file mode 100644
index 0000000000..eed3cb3a8b
--- /dev/null
+++ b/crates/openhuman-core/src/inbound_debounce/mod.rs
@@ -0,0 +1,327 @@
+//! Keyed inbound debounce: collects bursts of messages per conversation key
+//! into batches and lets at most one batch per key run at a time.
+//!
+//! The state machine is synchronous and owns no timer. Callers pass the
+//! current [`Instant`] into every call, arm their own wakeup from
+//! [`KeyedDebouncer::next_wakeup`], and report a finished batch with
+//! [`KeyedDebouncer::complete`]. See `README.md` for the full behaviour.
+
+use std::collections::{HashMap, VecDeque};
+use std::hash::Hash;
+use std::time::Duration;
+use tokio::time::Instant;
+
+/// Keys that may be buffering at once; a new key past this limit skips the
+/// quiet window but is still serialized.
+pub const MAX_TRACKED_KEYS: usize = 2048;
+
+/// What the debouncer needs to know about a buffered item.
+pub trait DebounceItem {
+ /// Size counted against [`DebounceSettings::max_batch_chars`].
+ fn chars(&self) -> usize;
+ /// Whether the item carries media, which stretches the quiet window to
+ /// [`DebounceSettings::media_debounce`].
+ fn carries_media(&self) -> bool;
+ /// Whether the item may share a batch with others. A non-mergeable item
+ /// seals the pending batch and runs as a batch of its own, in order.
+ fn mergeable(&self) -> bool;
+}
+
+/// Windows and caps applied to one push.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct DebounceSettings {
+ pub debounce: Duration,
+ pub media_debounce: Duration,
+ pub max_wait: Duration,
+ pub max_batch_messages: usize,
+ pub max_batch_chars: usize,
+}
+
+impl DebounceSettings {
+ /// No quiet window: every item is its own batch, still serialized per key.
+ pub const fn immediate() -> Self {
+ Self {
+ debounce: Duration::ZERO,
+ media_debounce: Duration::ZERO,
+ max_wait: Duration::ZERO,
+ max_batch_messages: 1,
+ max_batch_chars: usize::MAX,
+ }
+ }
+
+ fn window(&self, media: bool) -> Duration {
+ if media {
+ self.media_debounce.max(self.debounce)
+ } else {
+ self.debounce
+ }
+ }
+
+ fn effective_max_wait(&self) -> Duration {
+ self.max_wait.max(self.debounce).max(self.media_debounce)
+ }
+
+ fn message_cap(&self) -> usize {
+ self.max_batch_messages.max(1)
+ }
+
+ fn char_cap(&self) -> usize {
+ self.max_batch_chars.max(1)
+ }
+}
+
+/// Outcome of [`KeyedDebouncer::push`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Push {
+ /// A batch for this key can run now; call [`KeyedDebouncer::poll_ready`].
+ Ready,
+ /// The item started a new quiet window for an idle or running key.
+ Opened,
+ /// The item joined a pending batch or queued behind a running one.
+ Buffered,
+}
+
+struct OpenBatch<T> {
+ items: Vec<T>,
+ chars: usize,
+ media: bool,
+ quiet_at: Instant,
+ deadline: Instant,
+}
+
+struct SealedBatch<T> {
+ order: u64,
+ ready_at: Instant,
+ items: Vec<T>,
+}
+
+struct Lane<T> {
+ running: bool,
+ open: Option<OpenBatch<T>>,
+ sealed: VecDeque<SealedBatch<T>>,
+}
+
+impl<T> Default for Lane<T> {
+ fn default() -> Self {
+ Self {
+ running: false,
+ open: None,
+ sealed: VecDeque::new(),
+ }
+ }
+}
+
+impl<T> Lane<T> {
+ fn is_idle(&self) -> bool {
+ !self.running && self.open.is_none() && self.sealed.is_empty()
+ }
+}
+
+struct Counters {
+ next_order: u64,
+ buffering: usize,
+}
+
+impl Counters {
+ fn seal_open<T>(&mut self, lane: &mut Lane<T>, now: Instant) {
+ if let Some(open) = lane.open.take() {
+ self.buffering -= 1;
+ self.seal(lane, open.items, now);
+ }
+ }
+
+ fn seal<T>(&mut self, lane: &mut Lane<T>, items: Vec<T>, now: Instant) {
+ lane.sealed.push_back(SealedBatch {
+ order: self.next_order,
+ ready_at: now,
+ items,
+ });
+ self.next_order += 1;
+ }
+}
+
+/// Per-key debounce and serialization state.
+pub struct KeyedDebouncer<K, T> {
+ lanes: HashMap<K, Lane<T>>,
+ counters: Counters,
+ max_tracked: usize,
+}
+
+impl<K: Eq + Hash + Clone, T: DebounceItem> Default for KeyedDebouncer<K, T> {
+ fn default() -> Self {
+ Self::new()
+ }
+}
+
+impl<K: Eq + Hash + Clone, T: DebounceItem> KeyedDebouncer<K, T> {
+ pub fn new() -> Self {
+ Self::with_max_tracked(MAX_TRACKED_KEYS)
+ }
+
+ pub fn with_max_tracked(max_tracked: usize) -> Self {
+ Self {
+ lanes: HashMap::new(),
+ counters: Counters {
+ next_order: 0,
+ buffering: 0,
+ },
+ max_tracked,
+ }
+ }
+
+ /// Buffer `item` under `key`.
+ pub fn push(&mut self, key: K, item: T, settings: &DebounceSettings, now: Instant) -> Push {
+ let at_capacity = self.counters.buffering >= self.max_tracked;
+ let counters = &mut self.counters;
+ let lane = self.lanes.entry(key).or_default();
+ let mut opened = false;
+
+ if !item.mergeable() {
+ counters.seal_open(lane, now);
+ counters.seal(lane, vec![item], now);
+ } else {
+ let item_chars = item.chars();
+ let would_overflow = lane.open.as_ref().is_some_and(|open| {
+ open.items.len() + 1 > settings.message_cap()
+ || open.chars.saturating_add(item_chars) > settings.char_cap()
+ });
+ if would_overflow {
+ counters.seal_open(lane, now);
+ }
+ if lane.open.is_none() && at_capacity {
+ tracing::debug!(
+ tracked = counters.buffering,
+ "[inbound_debounce] tracked-key limit reached; item skips the quiet window"
+ );
+ counters.seal(lane, vec![item], now);
+ } else {
+ let open = lane.open.get_or_insert_with(|| {
+ opened = true;
+ counters.buffering += 1;
+ OpenBatch {
+ items: Vec::new(),
+ chars: 0,
+ media: false,
+ quiet_at: now,
+ deadline: now + settings.effective_max_wait(),
+ }
+ });
+ open.media |= item.carries_media();
+ open.chars = open.chars.saturating_add(item_chars);
+ open.items.push(item);
+ let window = settings.window(open.media);
+ open.quiet_at = (now + window).min(open.deadline);
+ if window.is_zero() {
+ counters.seal_open(lane, now);
+ }
+ }
+ }
+
+ if !lane.running && !lane.sealed.is_empty() {
+ Push::Ready
+ } else if opened {
+ Push::Opened
+ } else {
+ Push::Buffered
+ }
+ }
+
+ /// The earliest instant at which [`Self::poll_ready`] can yield a batch,
+ /// ignoring keys whose batch is still running.
+ pub fn next_wakeup(&self) -> Option<Instant> {
+ self.lanes
+ .values()
+ .filter(|lane| !lane.running)
+ .filter_map(|lane| {
+ lane.sealed
+ .front()
+ .map(|batch| batch.ready_at)
+ .or_else(|| lane.open.as_ref().map(|open| open.quiet_at))
+ })
+ .min()
+ }
+
+ /// Take every batch that may run at `now`, oldest first, and mark its key
+ /// running until [`Self::complete`].
+ pub fn poll_ready(&mut self, now: Instant) -> Vec<(K, Vec<T>)> {
+ let mut ready = Vec::new();
+ for (key, lane) in self.lanes.iter_mut() {
+ if lane.running {
+ continue;
+ }
+ if lane.open.as_ref().is_some_and(|open| open.quiet_at <= now) {
+ self.counters.seal_open(lane, now);
+ }
+ if let Some(batch) = lane.sealed.pop_front() {
+ lane.running = true;
+ ready.push((batch.order, key.clone(), batch.items));
+ }
+ }
+ ready.sort_by_key(|(order, _, _)| *order);
+ ready
+ .into_iter()
+ .map(|(_, key, items)| (key, items))
+ .collect()
+ }
+
+ /// Release `key` after its batch finished. Items buffered meanwhile wait
+ /// for the rest of their quiet window, or run at the next poll if it has
+ /// passed.
+ pub fn complete(&mut self, key: &K) {
+ if let Some(lane) = self.lanes.get_mut(key) {
+ lane.running = false;
+ if lane.is_idle() {
+ self.lanes.remove(key);
+ }
+ }
+ }
+
+ /// Close every quiet window now. Keys still running keep their batches
+ /// queued until they complete.
+ pub fn flush_all(&mut self, now: Instant) {
+ for lane in self.lanes.values_mut() {
+ self.counters.seal_open(lane, now);
+ }
+ }
+
+ /// Remove and return every buffered batch, oldest first, including those
+ /// queued behind a running key.
+ pub fn drain_all(&mut self) -> Vec<(K, Vec<T>)> {
+ let mut drained = Vec::new();
+ for (key, lane) in self.lanes.drain() {
+ for batch in lane.sealed {
+ drained.push((batch.order, key.clone(), batch.items));
+ }
+ if let Some(open) = lane.open {
+ let order = self.counters.next_order;
+ self.counters.next_order += 1;
+ drained.push((order, key, open.items));
+ }
+ }
+ self.counters.buffering = 0;
+ drained.sort_by_key(|(order, _, _)| *order);
+ drained
+ .into_iter()
+ .map(|(_, key, items)| (key, items))
+ .collect()
+ }
+
+ /// Keys with an open quiet window.
+ pub fn tracked(&self) -> usize {
+ self.counters.buffering
+ }
+
+ /// Whether `key` has a batch running.
+ pub fn is_running(&self, key: &K) -> bool {
+ self.lanes.get(key).is_some_and(|lane| lane.running)
+ }
+
+ /// Whether no key has anything buffered or running.
+ pub fn is_empty(&self) -> bool {
+ self.lanes.is_empty()
+ }
+}
+
+#[cfg(test)]
+#[path = "mod_tests.rs"]
+mod tests;
diff --git a/crates/openhuman-core/src/inbound_debounce/mod_tests.rs b/crates/openhuman-core/src/inbound_debounce/mod_tests.rs
new file mode 100644
index 0000000000..bfb5f4aec7
--- /dev/null
+++ b/crates/openhuman-core/src/inbound_debounce/mod_tests.rs
@@ -0,0 +1,310 @@
+use super::*;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+struct Item {
+ text: &'static str,
+ media: bool,
+ mergeable: bool,
+}
+
+fn text(text: &'static str) -> Item {
+ Item {
+ text,
+ media: false,
+ mergeable: true,
+ }
+}
+
+fn media(text: &'static str) -> Item {
+ Item {
+ text,
+ media: true,
+ mergeable: true,
+ }
+}
+
+fn solo(text: &'static str) -> Item {
+ Item {
+ text,
+ media: false,
+ mergeable: false,
+ }
+}
+
+impl DebounceItem for Item {
+ fn chars(&self) -> usize {
+ self.text.chars().count()
+ }
+ fn carries_media(&self) -> bool {
+ self.media
+ }
+ fn mergeable(&self) -> bool {
+ self.mergeable
+ }
+}
+
+fn settings() -> DebounceSettings {
+ DebounceSettings {
+ debounce: Duration::from_millis(1500),
+ media_debounce: Duration::from_millis(4000),
+ max_wait: Duration::from_millis(10_000),
+ max_batch_messages: 12,
+ max_batch_chars: 50_000,
+ }
+}
+
+fn ms(base: Instant, offset: u64) -> Instant {
+ base + Duration::from_millis(offset)
+}
+
+fn texts(batch: &[Item]) -> Vec<&'static str> {
+ batch.iter().map(|item| item.text).collect()
+}
+
+type Debouncer = KeyedDebouncer<&'static str, Item>;
+
+#[test]
+fn quiet_window_resets_on_every_push_and_flushes_once() {
+ let t0 = Instant::now();
+ let mut d = Debouncer::new();
+ assert_eq!(d.push("k", text("a"), &settings(), t0), Push::Opened);
+ assert_eq!(
+ d.push("k", text("b"), &settings(), ms(t0, 1000)),
+ Push::Buffered
+ );
+ assert_eq!(d.next_wakeup(), Some(ms(t0, 2500)));
+ assert!(d.poll_ready(ms(t0, 2499)).is_empty());
+ let ready = d.poll_ready(ms(t0, 2500));
+ assert_eq!(ready.len(), 1);
+ assert_eq!(ready[0].0, "k");
+ assert_eq!(texts(&ready[0].1), ["a", "b"]);
+ assert_eq!(d.tracked(), 0);
+}
+
+#[test]
+fn max_wait_caps_a_burst_that_never_goes_quiet() {
+ let t0 = Instant::now();
+ let mut d = Debouncer::new();
+ for step in 0..12u64 {
+ d.push("k", text("x"), &settings(), ms(t0, step * 900));
+ }
+ assert_eq!(d.next_wakeup(), Some(ms(t0, 10_000)));
+ assert!(d.poll_ready(ms(t0, 9_999)).is_empty());
+ assert_eq!(d.poll_ready(ms(t0, 10_000))[0].1.len(), 12);
+}
+
+#[test]
+fn media_stretches_the_window_without_passing_the_deadline() {
+ let t0 = Instant::now();
+ let mut d = Debouncer::new();
+ d.push("k", media("photo"), &settings(), t0);
+ assert_eq!(d.next_wakeup(), Some(ms(t0, 4000)));
+ d.push("k", text("caption follow-up"), &settings(), ms(t0, 3000));
+ assert_eq!(d.next_wakeup(), Some(ms(t0, 7000)));
+ d.push("k", text("more"), &settings(), ms(t0, 8000));
+ assert_eq!(d.next_wakeup(), Some(ms(t0, 10_000)));
+ let ready = d.poll_ready(ms(t0, 10_000));
+ assert_eq!(texts(&ready[0].1), ["photo", "caption follow-up", "more"]);
+}
+
+#[test]
+fn max_wait_is_raised_to_the_longest_window() {
+ let t0 = Instant::now();
+ let mut d = Debouncer::new();
+ let short = DebounceSettings {
+ max_wait: Duration::from_millis(100),
+ ..settings()
+ };
+ d.push("k", media("photo"), &short, t0);
+ assert_eq!(d.next_wakeup(), Some(ms(t0, 4000)));
+}
+
+#[test]
+fn zero_window_is_ready_immediately_and_never_merges() {
+ let t0 = Instant::now();
+ let mut d = Debouncer::new();
+ let none = DebounceSettings::immediate();
+ assert_eq!(d.push("k", text("a"), &none, t0), Push::Ready);
+ assert_eq!(d.push("k", text("b"), &none, t0), Push::Ready);
+ let first = d.poll_ready(t0);
+ assert_eq!(first.len(), 1);
+ assert_eq!(texts(&first[0].1), ["a"]);
+ assert!(d.poll_ready(t0).is_empty(), "key stays serialized");
+ d.complete(&"k");
+ assert_eq!(texts(&d.poll_ready(t0)[0].1), ["b"]);
+ d.complete(&"k");
+ assert!(d.is_empty());
+}
+
+#[test]
+fn non_mergeable_item_seals_pending_batch_and_runs_behind_it() {
+ let t0 = Instant::now();
+ let mut d = Debouncer::new();
+ d.push("k", text("a"), &settings(), t0);
+ assert_eq!(
+ d.push("k", solo("/cmd"), &settings(), ms(t0, 10)),
+ Push::Ready
+ );
+ assert_eq!(d.next_wakeup(), Some(ms(t0, 10)));
+ let first = d.poll_ready(ms(t0, 10));
+ assert_eq!(texts(&first[0].1), ["a"]);
+ d.complete(&"k");
+ assert_eq!(texts(&d.poll_ready(ms(t0, 10))[0].1), ["/cmd"]);
+}
+
+#[test]
+fn message_cap_seals_and_starts_a_new_batch() {
+ let t0 = Instant::now();
+ let mut d = Debouncer::new();
+ let capped = DebounceSettings {
+ max_batch_messages: 2,
+ ..settings()
+ };
+ d.push("k", text("a"), &capped, t0);
+ d.push("k", text("b"), &capped, t0);
+ assert_eq!(d.push("k", text("c"), &capped, t0), Push::Ready);
+ assert_eq!(texts(&d.poll_ready(t0)[0].1), ["a", "b"]);
+ d.complete(&"k");
+ assert!(d.poll_ready(t0).is_empty());
+ assert_eq!(texts(&d.poll_ready(ms(t0, 1500))[0].1), ["c"]);
+}
+
+#[test]
+fn char_cap_seals_before_the_overflowing_item() {
+ let t0 = Instant::now();
+ let mut d = Debouncer::new();
+ let capped = DebounceSettings {
+ max_batch_chars: 5,
+ ..settings()
+ };
+ d.push("k", text("abc"), &capped, t0);
+ assert_eq!(d.push("k", text("def"), &capped, t0), Push::Ready);
+ assert_eq!(texts(&d.poll_ready(t0)[0].1), ["abc"]);
+}
+
+#[test]
+fn items_pushed_while_running_are_collected_into_one_follow_up() {
+ let t0 = Instant::now();
+ let mut d = Debouncer::new();
+ d.push("k", text("first"), &settings(), t0);
+ assert_eq!(d.poll_ready(ms(t0, 1500)).len(), 1);
+ assert!(d.is_running(&"k"));
+ assert_eq!(
+ d.push("k", text("b"), &settings(), ms(t0, 2000)),
+ Push::Opened
+ );
+ d.push("k", text("c"), &settings(), ms(t0, 2100));
+ assert_eq!(d.next_wakeup(), None, "running keys do not arm a wakeup");
+ assert!(d.poll_ready(ms(t0, 9000)).is_empty());
+ d.complete(&"k");
+ let follow_up = d.poll_ready(ms(t0, 9000));
+ assert_eq!(texts(&follow_up[0].1), ["b", "c"]);
+}
+
+#[test]
+fn complete_keeps_waiting_while_the_user_is_still_typing() {
+ let t0 = Instant::now();
+ let mut d = Debouncer::new();
+ d.push("k", text("first"), &settings(), t0);
+ d.poll_ready(ms(t0, 1500));
+ d.push("k", text("b"), &settings(), ms(t0, 2000));
+ d.complete(&"k");
+ assert!(d.poll_ready(ms(t0, 2100)).is_empty());
+ assert_eq!(d.next_wakeup(), Some(ms(t0, 3500)));
+ assert_eq!(texts(&d.poll_ready(ms(t0, 3500))[0].1), ["b"]);
+}
+
+#[test]
+fn complete_with_nothing_pending_forgets_the_key() {
+ let t0 = Instant::now();
+ let mut d = Debouncer::new();
+ d.push("k", text("a"), &settings(), t0);
+ d.poll_ready(ms(t0, 1500));
+ assert!(!d.is_empty());
+ d.complete(&"k");
+ assert!(d.is_empty());
+ d.complete(&"unknown");
+}
+
+#[test]
+fn overflow_past_tracked_limit_skips_window_but_stays_serialized() {
+ let t0 = Instant::now();
+ let mut d = Debouncer::with_max_tracked(1);
+ assert_eq!(d.push("a", text("1"), &settings(), t0), Push::Opened);
+ assert_eq!(d.tracked(), 1);
+ assert_eq!(d.push("b", text("2"), &settings(), t0), Push::Ready);
+ assert_eq!(d.push("b", text("3"), &settings(), t0), Push::Ready);
+ assert_eq!(d.tracked(), 1);
+ let ready = d.poll_ready(t0);
+ assert_eq!(ready.len(), 1);
+ assert_eq!(ready[0].0, "b");
+ assert_eq!(texts(&ready[0].1), ["2"]);
+ assert!(d.poll_ready(t0).is_empty());
+ d.complete(&"b");
+ assert_eq!(texts(&d.poll_ready(t0)[0].1), ["3"]);
+}
+
+#[test]
+fn keys_are_independent_and_wakeup_is_the_minimum() {
+ let t0 = Instant::now();
+ let mut d = Debouncer::new();
+ d.push("a", text("1"), &settings(), t0);
+ d.push("b", media("2"), &settings(), ms(t0, 100));
+ assert_eq!(d.next_wakeup(), Some(ms(t0, 1500)));
+ let ready = d.poll_ready(ms(t0, 1500));
+ assert_eq!(ready.len(), 1);
+ assert_eq!(ready[0].0, "a");
+ assert_eq!(d.next_wakeup(), Some(ms(t0, 4100)));
+ assert_eq!(d.poll_ready(ms(t0, 4100))[0].0, "b");
+}
+
+#[test]
+fn ready_batches_come_out_oldest_first() {
+ let t0 = Instant::now();
+ let mut d = Debouncer::new();
+ for key in ["c", "a", "b"] {
+ d.push(key, solo("x"), &settings(), t0);
+ }
+ let keys: Vec<_> = d.poll_ready(t0).into_iter().map(|(k, _)| k).collect();
+ assert_eq!(keys, ["c", "a", "b"]);
+}
+
+#[test]
+fn flush_all_closes_windows_but_respects_running_keys() {
+ let t0 = Instant::now();
+ let mut d = Debouncer::new();
+ d.push("a", text("1"), &settings(), t0);
+ d.poll_ready(ms(t0, 1500));
+ d.push("a", text("2"), &settings(), ms(t0, 1600));
+ d.push("b", text("3"), &settings(), ms(t0, 1600));
+ d.flush_all(ms(t0, 1600));
+ assert_eq!(d.tracked(), 0);
+ let ready = d.poll_ready(ms(t0, 1600));
+ assert_eq!(ready.len(), 1);
+ assert_eq!(ready[0].0, "b");
+ d.complete(&"a");
+ assert_eq!(texts(&d.poll_ready(ms(t0, 1600))[0].1), ["2"]);
+}
+
+#[test]
+fn drain_all_returns_everything_in_order() {
+ let t0 = Instant::now();
+ let mut d = Debouncer::new();
+ d.push("a", text("1"), &settings(), t0);
+ d.push("a", solo("2"), &settings(), t0);
+ d.push("a", text("3"), &settings(), t0);
+ let drained = d.drain_all();
+ let flat: Vec<_> = drained.iter().map(|(_, b)| texts(b)).collect();
+ assert_eq!(flat, [vec!["1"], vec!["2"], vec!["3"]]);
+ assert!(d.is_empty());
+ assert_eq!(d.tracked(), 0);
+}
+
+#[test]
+fn immediate_settings_and_default_constructor() {
+ let none = DebounceSettings::immediate();
+ assert!(none.debounce.is_zero());
+ let d: Debouncer = KeyedDebouncer::default();
+ assert!(d.is_empty());
+ assert_eq!(d.next_wakeup(), None);
+}
diff --git a/crates/openhuman-core/src/lib.rs b/crates/openhuman-core/src/lib.rs
index bc13b8bb93..46f08c30eb 100644
--- a/crates/openhuman-core/src/lib.rs
+++ b/crates/openhuman-core/src/lib.rs
@@ -70,6 +70,7 @@ pub mod hooks;
pub mod hosting;
#[cfg(feature = "inbound-queues")]
pub mod inbound;
+pub mod inbound_debounce;
pub mod inference;
pub mod integrations;
pub mod mcp;