Skip to content

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

feat(embed): expose inbound debounce facade

oxoxDevf7c423e2134a
diff --git a/crates/openhuman-embed/src/inbound.rs b/crates/openhuman-embed/src/inbound.rs
new file mode 100644
index 0000000000..d6813f5db3
--- /dev/null
+++ b/crates/openhuman-embed/src/inbound.rs
@@ -0,0 +1,44 @@
+//! Per-conversation inbound debounce for hosts that run their own message loop.
+//!
+//! [`KeyedDebouncer`] is the state machine OpenHuman's channel dispatch uses:
+//! messages pushed under one key within the quiet window become one batch,
+//! a key never has two batches running, and items that arrive while a batch
+//! runs are collected into one follow-up. It owns no timer; the host passes
+//! the current [`tokio::time::Instant`] and sleeps until
+//! [`KeyedDebouncer::next_wakeup`].
+//!
+//! ```
+//! use openhuman_embed::inbound::{DebounceItem, InboundDebounceConfig, KeyedDebouncer, Push};
+//! use std::time::Duration;
+//! use tokio::time::Instant;
+//!
+//! struct Text(&'static str);
+//!
+//! impl DebounceItem for Text {
+//! fn chars(&self) -> usize { self.0.len() }
+//! fn carries_media(&self) -> bool { false }
+//! fn mergeable(&self) -> bool { !self.0.starts_with('/') }
+//! }
+//!
+//! let settings = InboundDebounceConfig::default().settings_for("whatsapp");
+//! let mut debouncer = KeyedDebouncer::new();
+//! let t0 = Instant::now();
+//! assert_eq!(debouncer.push("chat-1", Text("hi"), &settings, t0), Push::Opened);
+//! debouncer.push("chat-1", Text("are you there?"), &settings, t0 + Duration::from_millis(400));
+//!
+//! let due = debouncer.next_wakeup().expect("a quiet window is open");
+//! let ready = debouncer.poll_ready(due);
+//! assert_eq!(ready.len(), 1);
+//! assert_eq!(ready[0].1.len(), 2);
+//! debouncer.complete(&"chat-1");
+//! assert!(debouncer.is_empty());
+//! ```
+
+pub use openhuman_core::config::{InboundDebounceConfig, InboundDebounceOverride};
+pub use openhuman_core::inbound_debounce::{
+ DebounceItem, DebounceSettings, KeyedDebouncer, Push, MAX_TRACKED_KEYS,
+};
+
+#[cfg(test)]
+#[path = "inbound_tests.rs"]
+mod tests;
diff --git a/crates/openhuman-embed/src/inbound_tests.rs b/crates/openhuman-embed/src/inbound_tests.rs
new file mode 100644
index 0000000000..d72a8e47cb
--- /dev/null
+++ b/crates/openhuman-embed/src/inbound_tests.rs
@@ -0,0 +1,66 @@
+use super::*;
+use std::time::Duration;
+use tokio::time::Instant;
+
+struct Message {
+ text: &'static str,
+ media: bool,
+}
+
+impl DebounceItem for Message {
+ fn chars(&self) -> usize {
+ self.text.chars().count()
+ }
+ fn carries_media(&self) -> bool {
+ self.media
+ }
+ fn mergeable(&self) -> bool {
+ !self.text.trim().is_empty()
+ }
+}
+
+#[test]
+fn facade_drives_an_image_and_its_follow_up_into_one_batch() {
+ let settings = InboundDebounceConfig::default().settings_for("whatsapp");
+ let mut debouncer: KeyedDebouncer<String, Message> = KeyedDebouncer::new();
+ let t0 = Instant::now();
+ let key = "wa:+15550001".to_string();
+
+ let first = debouncer.push(
+ key.clone(),
+ Message {
+ text: "[IMAGE:photo]",
+ media: true,
+ },
+ &settings,
+ t0,
+ );
+ assert_eq!(first, Push::Opened);
+ debouncer.push(
+ key.clone(),
+ Message {
+ text: "what is this?",
+ media: false,
+ },
+ &settings,
+ t0 + Duration::from_secs(3),
+ );
+
+ assert!(debouncer.poll_ready(t0 + Duration::from_secs(4)).is_empty());
+ let ready = debouncer.poll_ready(t0 + Duration::from_secs(7));
+ assert_eq!(ready.len(), 1);
+ let texts: Vec<_> = ready[0].1.iter().map(|m| m.text).collect();
+ assert_eq!(texts, ["[IMAGE:photo]", "what is this?"]);
+ assert!(debouncer.is_running(&key));
+ debouncer.complete(&key);
+ assert!(debouncer.is_empty());
+}
+
+#[test]
+fn facade_exposes_disabled_settings_and_the_key_limit() {
+ let off = InboundDebounceConfig::disabled().settings_for("telegram");
+ assert_eq!(off, DebounceSettings::immediate());
+ assert_eq!(MAX_TRACKED_KEYS, 2048);
+ let over = InboundDebounceOverride::default();
+ assert!(over.enabled.is_none());
+}
diff --git a/crates/openhuman-embed/src/lib.rs b/crates/openhuman-embed/src/lib.rs
index f42d8958f6..55485bac3a 100644
--- a/crates/openhuman-embed/src/lib.rs
+++ b/crates/openhuman-embed/src/lib.rs
@@ -129,6 +129,7 @@ mod error;
pub mod fanout;
mod harness;
pub mod identity;
+pub mod inbound;
pub mod memory;
pub mod modules;
mod permission;
diff --git a/docs/gitbooks/en/developing/embed/api-index.json b/docs/gitbooks/en/developing/embed/api-index.json
index e90a697e57..a1fc595a20 100644
--- a/docs/gitbooks/en/developing/embed/api-index.json
+++ b/docs/gitbooks/en/developing/embed/api-index.json
@@ -162,6 +162,7 @@
"events",
"fanout",
"identity",
+ "inbound",
"memory",
"modules",
"observe",
diff --git a/docs/gitbooks/en/developing/embed/api-index.md b/docs/gitbooks/en/developing/embed/api-index.md
index 543f6a1820..8cbf38d923 100644
--- a/docs/gitbooks/en/developing/embed/api-index.md
+++ b/docs/gitbooks/en/developing/embed/api-index.md
@@ -165,6 +165,7 @@ Generate the complete local Rust API reference with `cargo doc -p openhuman-embe
- [`events`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`fanout`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`identity`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
+- [`inbound`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`memory`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`modules`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`observe`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
diff --git a/llms-full.txt b/llms-full.txt
index f1bac010d3..70feae7d0f 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -3036,6 +3036,7 @@ Generate the complete local Rust API reference with `cargo doc -p openhuman-embe
- [`events`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`fanout`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`identity`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
+- [`inbound`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`memory`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`modules`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)
- [`observe`](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs)