Skip to content

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

feat(config): add inbound_debounce schema and defaults

oxoxDev598eb96c8d9f
diff --git a/crates/openhuman-core/src/config/schema/README.md b/crates/openhuman-core/src/config/schema/README.md
index 112dc9ce26..da2f2274f4 100644
--- a/crates/openhuman-core/src/config/schema/README.md
+++ b/crates/openhuman-core/src/config/schema/README.md
@@ -31,6 +31,7 @@ is mounted as a submodule of [`load/dirs.rs`](./load/dirs.rs) via `#[path]`.
| `[hooks]` | [`hooks.rs`](./hooks.rs) | `HooksConfig` |
| `[hosting]` | [`hosting.rs`](./hosting.rs) | `HostingConfig` |
| `[learning]` | `learning.rs` | `LearningConfig`, `ReflectionSource` |
+| `[inbound_debounce]` (+ `by_channel.<name>`) | [`inbound_debounce.rs`](./inbound_debounce.rs) | `InboundDebounceConfig`, `InboundDebounceOverride`: per-conversation batching of inbound channel messages before a turn |
| `[local_ai]` | [`local_ai.rs`](./local_ai.rs) | `LocalAiConfig`, `LocalAiUsage` |
| `[modules]` | [`modules.rs`](./modules.rs) | `ModulesConfig`, `ModuleOverride`: controls only whether compiled-in modules load. The loadable *set* is fixed by `crate::modules::registry` |
| `[observability]` | [`observability.rs`](./observability.rs) | `ObservabilityConfig`, `AgentTracingConfig` |
diff --git a/crates/openhuman-core/src/config/schema/inbound_debounce.rs b/crates/openhuman-core/src/config/schema/inbound_debounce.rs
new file mode 100644
index 0000000000..93cabb0246
--- /dev/null
+++ b/crates/openhuman-core/src/config/schema/inbound_debounce.rs
@@ -0,0 +1,110 @@
+//! `[inbound_debounce]` — batching of inbound channel messages per
+//! conversation before an agent turn runs.
+//!
+//! Messages from one sender in one chat that arrive within the quiet window
+//! become one turn, and a conversation never runs two turns at once.
+//! `[inbound_debounce.by_channel.<name>]` overrides the windows for one
+//! channel; `enabled = false` turns merging off but keeps per-conversation
+//! ordering.
+//!
+//! | setting | override |
+//! | --- | --- |
+//! | `enabled` | `OPENHUMAN_INBOUND_DEBOUNCE_ENABLED` |
+//! | `debounce_ms` | `OPENHUMAN_INBOUND_DEBOUNCE_MS` |
+//! | `media_debounce_ms` | `OPENHUMAN_INBOUND_DEBOUNCE_MEDIA_MS` |
+//! | `max_wait_ms` | `OPENHUMAN_INBOUND_DEBOUNCE_MAX_WAIT_MS` |
+
+use crate::inbound_debounce::DebounceSettings;
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+use std::time::Duration;
+
+pub const DEFAULT_DEBOUNCE_MS: u64 = 1_500;
+pub const DEFAULT_MEDIA_DEBOUNCE_MS: u64 = 4_000;
+pub const DEFAULT_MAX_WAIT_MS: u64 = 10_000;
+pub const DEFAULT_MAX_BATCH_MESSAGES: usize = 12;
+pub const DEFAULT_MAX_BATCH_CHARS: usize = 50_000;
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
+#[serde(default)]
+pub struct InboundDebounceConfig {
+ /// Merge messages that arrive within the quiet window into one turn.
+ pub enabled: bool,
+ /// Quiet window after the latest text message, in milliseconds.
+ pub debounce_ms: u64,
+ /// Quiet window once the batch holds an image or file, in milliseconds.
+ pub media_debounce_ms: u64,
+ /// Longest a batch waits from its first message, in milliseconds. Raised
+ /// to at least the longer of the two windows.
+ pub max_wait_ms: u64,
+ /// Messages per batch; one more starts a new batch.
+ pub max_batch_messages: usize,
+ /// Characters per batch; a message that would pass it starts a new batch.
+ pub max_batch_chars: usize,
+ /// Per-channel overrides keyed by channel name (`telegram`, `discord`, ...).
+ pub by_channel: BTreeMap<String, InboundDebounceOverride>,
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
+#[serde(default)]
+pub struct InboundDebounceOverride {
+ pub enabled: Option<bool>,
+ pub debounce_ms: Option<u64>,
+ pub media_debounce_ms: Option<u64>,
+ pub max_wait_ms: Option<u64>,
+}
+
+impl Default for InboundDebounceConfig {
+ fn default() -> Self {
+ Self {
+ enabled: true,
+ debounce_ms: DEFAULT_DEBOUNCE_MS,
+ media_debounce_ms: DEFAULT_MEDIA_DEBOUNCE_MS,
+ max_wait_ms: DEFAULT_MAX_WAIT_MS,
+ max_batch_messages: DEFAULT_MAX_BATCH_MESSAGES,
+ max_batch_chars: DEFAULT_MAX_BATCH_CHARS,
+ by_channel: BTreeMap::new(),
+ }
+ }
+}
+
+impl InboundDebounceConfig {
+ /// Merging switched off everywhere: one turn per message, still in order.
+ pub fn disabled() -> Self {
+ Self {
+ enabled: false,
+ ..Self::default()
+ }
+ }
+
+ /// The settings for `channel`. A suffix after `:` (an account or
+ /// instance) is ignored when looking up the override.
+ pub fn settings_for(&self, channel: &str) -> DebounceSettings {
+ let name = channel.split(':').next().unwrap_or(channel);
+ let over = self.by_channel.get(name);
+ let enabled = over.and_then(|o| o.enabled).unwrap_or(self.enabled);
+ if !enabled {
+ return DebounceSettings::immediate();
+ }
+ let pick = |field: fn(&InboundDebounceOverride) -> Option<u64>, global: u64| {
+ Duration::from_millis(over.and_then(field).unwrap_or(global))
+ };
+ let debounce = pick(|o| o.debounce_ms, self.debounce_ms);
+ let media_debounce = pick(|o| o.media_debounce_ms, self.media_debounce_ms);
+ let max_wait = pick(|o| o.max_wait_ms, self.max_wait_ms)
+ .max(debounce)
+ .max(media_debounce);
+ DebounceSettings {
+ debounce,
+ media_debounce,
+ max_wait,
+ max_batch_messages: self.max_batch_messages.max(1),
+ max_batch_chars: self.max_batch_chars.max(1),
+ }
+ }
+}
+
+#[cfg(test)]
+#[path = "inbound_debounce_tests.rs"]
+mod tests;
diff --git a/crates/openhuman-core/src/config/schema/inbound_debounce_tests.rs b/crates/openhuman-core/src/config/schema/inbound_debounce_tests.rs
new file mode 100644
index 0000000000..80a4aa6673
--- /dev/null
+++ b/crates/openhuman-core/src/config/schema/inbound_debounce_tests.rs
@@ -0,0 +1,106 @@
+use super::*;
+
+#[test]
+fn defaults_match_the_documented_values() {
+ let c = InboundDebounceConfig::default();
+ assert!(c.enabled);
+ assert_eq!(c.debounce_ms, 1_500);
+ assert_eq!(c.media_debounce_ms, 4_000);
+ assert_eq!(c.max_wait_ms, 10_000);
+ assert_eq!(c.max_batch_messages, 12);
+ assert_eq!(c.max_batch_chars, 50_000);
+ assert!(c.by_channel.is_empty());
+
+ let s = c.settings_for("telegram");
+ assert_eq!(s.debounce, Duration::from_millis(1_500));
+ assert_eq!(s.media_debounce, Duration::from_millis(4_000));
+ assert_eq!(s.max_wait, Duration::from_millis(10_000));
+ assert_eq!(s.max_batch_messages, 12);
+ assert_eq!(s.max_batch_chars, 50_000);
+}
+
+#[test]
+fn channel_override_wins_over_global_and_ignores_account_suffix() {
+ let c: InboundDebounceConfig = toml::from_str(
+ r#"
+ debounce_ms = 1000
+ [by_channel.discord]
+ debounce_ms = 300
+ "#,
+ )
+ .unwrap();
+ assert_eq!(c.debounce_ms, 1000);
+ assert_eq!(c.media_debounce_ms, DEFAULT_MEDIA_DEBOUNCE_MS);
+ let discord = c.settings_for("discord:guild-1");
+ assert_eq!(discord.debounce, Duration::from_millis(300));
+ assert_eq!(discord.media_debounce, Duration::from_millis(4_000));
+ assert_eq!(
+ c.settings_for("slack").debounce,
+ Duration::from_millis(1000)
+ );
+}
+
+#[test]
+fn disabled_globally_or_per_channel_gives_immediate_settings() {
+ assert_eq!(
+ InboundDebounceConfig::disabled().settings_for("telegram"),
+ DebounceSettings::immediate()
+ );
+ let mut c = InboundDebounceConfig::default();
+ c.by_channel.insert(
+ "telegram".into(),
+ InboundDebounceOverride {
+ enabled: Some(false),
+ ..Default::default()
+ },
+ );
+ assert_eq!(c.settings_for("telegram"), DebounceSettings::immediate());
+ assert_ne!(c.settings_for("discord"), DebounceSettings::immediate());
+
+ let mut off = InboundDebounceConfig::disabled();
+ off.by_channel.insert(
+ "telegram".into(),
+ InboundDebounceOverride {
+ enabled: Some(true),
+ ..Default::default()
+ },
+ );
+ assert_eq!(
+ off.settings_for("telegram").debounce,
+ Duration::from_millis(DEFAULT_DEBOUNCE_MS)
+ );
+}
+
+#[test]
+fn max_wait_and_caps_are_clamped() {
+ let c = InboundDebounceConfig {
+ max_wait_ms: 10,
+ max_batch_messages: 0,
+ max_batch_chars: 0,
+ ..Default::default()
+ };
+ let s = c.settings_for("telegram");
+ assert_eq!(s.max_wait, Duration::from_millis(4_000));
+ assert_eq!(s.max_batch_messages, 1);
+ assert_eq!(s.max_batch_chars, 1);
+}
+
+#[test]
+fn toml_round_trip_keeps_every_field() {
+ let mut c = InboundDebounceConfig {
+ debounce_ms: 700,
+ ..Default::default()
+ };
+ c.by_channel.insert(
+ "whatsapp".into(),
+ InboundDebounceOverride {
+ enabled: Some(true),
+ debounce_ms: Some(2000),
+ media_debounce_ms: Some(5000),
+ max_wait_ms: Some(12_000),
+ },
+ );
+ let text = toml::to_string(&c).unwrap();
+ let back: InboundDebounceConfig = toml::from_str(&text).unwrap();
+ assert_eq!(back, c);
+}
diff --git a/crates/openhuman-core/src/config/schema/mod.rs b/crates/openhuman-core/src/config/schema/mod.rs
index ae1d8b3c12..14feb3eac4 100644
--- a/crates/openhuman-core/src/config/schema/mod.rs
+++ b/crates/openhuman-core/src/config/schema/mod.rs
@@ -34,6 +34,7 @@ pub use storage::StorageConfig;
pub mod profile_layout;
pub use profile_layout::{users_dir, ProfileLayout};
mod identity_cost;
+mod inbound_debounce;
pub(crate) mod load;
pub(crate) use load::config_from_toml_str;
pub(crate) use load::source::storage_schema::storage_schema as config_storage_schema;
@@ -97,6 +98,7 @@ pub use identity_cost::{
BudgetAction, BudgetPeriod, BudgetPolicy, BudgetScope, CostConfig, ModelPricing,
};
pub use inbound::InboundConfig;
+pub use inbound_debounce::{InboundDebounceConfig, InboundDebounceOverride};
pub use local_ai::{LocalAiConfig, LocalAiUsage};
pub use memes::MemesConfig;
pub use memory::{
diff --git a/crates/openhuman-core/src/config/schema/types/config.rs b/crates/openhuman-core/src/config/schema/types/config.rs
index 2fe0ee358c..678149760a 100644
--- a/crates/openhuman-core/src/config/schema/types/config.rs
+++ b/crates/openhuman-core/src/config/schema/types/config.rs
@@ -474,6 +474,9 @@ pub struct Config {
/// `[components] eventqueues`.
#[serde(default)]
pub inbound: InboundConfig,
+ /// Per-conversation batching of inbound channel messages (`[inbound_debounce]`).
+ #[serde(default)]
+ pub inbound_debounce: InboundDebounceConfig,
/// Per-dependency switches (`[components]`). Narrow-only; applied at the
/// next core start.
diff --git a/crates/openhuman-core/src/config/schema/types/config_clone.rs b/crates/openhuman-core/src/config/schema/types/config_clone.rs
index 040cf037bf..398eb5d73f 100644
--- a/crates/openhuman-core/src/config/schema/types/config_clone.rs
+++ b/crates/openhuman-core/src/config/schema/types/config_clone.rs
@@ -94,6 +94,7 @@ impl Clone for Config {
tokenjuice: self.tokenjuice.clone(),
memes: self.memes.clone(),
inbound: self.inbound.clone(),
+ inbound_debounce: self.inbound_debounce.clone(),
components: self.components.clone(),
hosting: self.hosting.clone(),
storage: self.storage.clone(),
diff --git a/crates/openhuman-core/src/config/schema/types/defaults.rs b/crates/openhuman-core/src/config/schema/types/defaults.rs
index cbdb34cb33..a06a66dbde 100644
--- a/crates/openhuman-core/src/config/schema/types/defaults.rs
+++ b/crates/openhuman-core/src/config/schema/types/defaults.rs
@@ -107,6 +107,7 @@ impl Default for Config {
tokenjuice: TokenjuiceConfig::default(),
memes: MemesConfig::default(),
inbound: InboundConfig::default(),
+ inbound_debounce: InboundDebounceConfig::default(),
components: ComponentsConfig::default(),
hosting: HostingConfig::default(),
storage: StorageConfig::default(),