The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
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.rsnew file mode 100644index 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.rsnew file mode 100644index 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.rsindex 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;