Skip to content

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

feat(inbound): run pinned sources' turns on their configured agent

Steven Enamakel66dd88b91b3a
diff --git a/crates/openhuman-core/src/inbound/deliver.rs b/crates/openhuman-core/src/inbound/deliver.rs
index 453ccce8a7..b4fda9695b 100644
--- a/crates/openhuman-core/src/inbound/deliver.rs
+++ b/crates/openhuman-core/src/inbound/deliver.rs
@@ -30,6 +30,10 @@
//! borderline event and maps the action to a salience class; the decision is
//! kept (for ten minutes) for the event's delivery so it is not triaged twice.
//!
+//! A turn of a source configured under `[inbound.sources.*]` skips triage
+//! altogether: it runs on the source's pinned agent ([`super::pinned`]), and
+//! `ClassifySalience` answers `actionable` for its events without triaging.
+//!
//! One decision per turn: the triage timeout stays under the module's
//! callback deadline (`[inbound] triage_timeout_ms`, at most 25 s), and a
//! turn that was already accepted is accepted again without triage, so a
@@ -45,6 +49,9 @@ use tinyeventqueues_bus::{
};
use super::events::{digest_envelope, envelope_of};
+use super::pinned::{AgentChatPinned, Delivered, Pinned};
+use super::results::Results;
+use crate::config::schema::{InboundConfig, InboundSourceConfig};
use crate::core::bus::BUS;
use crate::core::events::DomainEvent;
use crate::core::runtime::DispatchCtx;
@@ -145,6 +152,10 @@ pub struct Deliverer {
budget: Duration,
classified: Mutex<Classified>,
accepted: Mutex<Accepted>,
+ /// `[inbound]`: given, or read on first use, for its pinned sources.
+ inbound: tokio::sync::OnceCell<Arc<InboundConfig>>,
+ /// What runs pinned sources' turns: given, or built on first use.
+ pinned: tokio::sync::OnceCell<Option<Pinned>>,
}
impl std::fmt::Debug for Deliverer {
@@ -190,9 +201,26 @@ impl Deliverer {
budget: DELIVERY_BUDGET,
classified: Mutex::new(Classified::default()),
accepted: Mutex::new(Accepted::default()),
+ inbound: tokio::sync::OnceCell::new(),
+ pinned: tokio::sync::OnceCell::new(),
}
}
+ /// Read pinned sources from `inbound` instead of the configuration.
+ #[must_use]
+ pub fn with_inbound(mut self, inbound: InboundConfig) -> Self {
+ self.inbound = tokio::sync::OnceCell::new_with(Some(Arc::new(inbound)));
+ self
+ }
+
+ /// Run pinned sources' turns with `pinned` instead of the production
+ /// agent and workspace results store.
+ #[must_use]
+ pub fn with_pinned(mut self, pinned: Pinned) -> Self {
+ self.pinned = tokio::sync::OnceCell::new_with(Some(Some(pinned)));
+ self
+ }
+
/// Use `now_ms` for the clock (tests).
#[must_use]
pub fn with_clock(mut self, now_ms: fn() -> i64) -> Self {
@@ -233,6 +261,85 @@ impl Deliverer {
.await
}
+ /// `[inbound]`, read from the configuration on first use when not given.
+ async fn inbound(&self) -> Arc<InboundConfig> {
+ Arc::clone(
+ self.inbound
+ .get_or_init(|| async {
+ match self.ctx.load_config().await {
+ Ok(config) => Arc::new(config.inbound),
+ Err(error) => {
+ tracing::debug!(error = %error, "[inbound] config unavailable; no pinned sources");
+ Arc::new(InboundConfig::default())
+ }
+ }
+ })
+ .await,
+ )
+ }
+
+ /// The pinned source every event of `turn` comes from, with its
+ /// configuration, when there is one.
+ async fn pinned_source(&self, events: &[InboundEvent]) -> Option<(String, InboundSourceConfig)> {
+ let first = events.first()?;
+ if !events.iter().all(|event| event.source == first.source) {
+ return None;
+ }
+ let inbound = self.inbound().await;
+ let source = inbound.source(&first.source).ok()?.clone();
+ Some((first.source.clone(), source))
+ }
+
+ /// What runs pinned turns: given, or the production agent over the
+ /// workspace's results store.
+ async fn pinned(&self) -> Option<Pinned> {
+ self.pinned
+ .get_or_init(|| async {
+ let config = match self.ctx.load_config().await {
+ Ok(config) => config,
+ Err(error) => {
+ tracing::warn!(error = %error, "[inbound] config unavailable; pinned turns cannot run");
+ return None;
+ }
+ };
+ match Results::open(&config) {
+ Ok(results) => Some(Pinned::new(Arc::new(AgentChatPinned), results)),
+ Err(error) => {
+ tracing::warn!(error = %error, "[inbound] results store unavailable; pinned turns cannot run");
+ None
+ }
+ }
+ })
+ .await
+ .clone()
+ }
+
+ /// Deliver a turn of pinned source `name`.
+ async fn deliver_pinned(
+ &self,
+ turn: &Turn,
+ name: &str,
+ source: &InboundSourceConfig,
+ within: Duration,
+ ) -> DeliverStatus {
+ let Some(pinned) = self.pinned().await else {
+ return self.retry(turn, None, "pinned turns cannot run here");
+ };
+ match pinned.deliver(&self.ctx, turn, name, source, within).await {
+ Delivered::Done | Delivered::Running => {
+ self.accepted().remember(&turn.turn_id);
+ DeliverStatus::Accepted
+ }
+ Delivered::Failed(error) => {
+ tracing::warn!(turn = %turn.turn_id, source = %name, attempt = turn.attempt, error = %error, "[inbound] pinned agent failed");
+ if self.exhausted(turn) {
+ pinned.fail(&turn.turn_id, &error);
+ }
+ self.retry(turn, None, "pinned agent failed")
+ }
+ }
+ }
+
fn classified(&self) -> std::sync::MutexGuard<'_, Classified> {
self.classified
.lock()
@@ -256,6 +363,10 @@ impl Deliverer {
request: ClassifySalienceRequest,
) -> Result<ClassifySalienceResponse, String> {
let event = request.event;
+ if self.pinned_source(std::slice::from_ref(&event)).await.is_some() {
+ // A pinned source's events always reach its agent: no triage.
+ return Ok(ClassifySalienceResponse::new(SalienceClass::Actionable));
+ }
let envelope = envelope_of(&event).ok_or("not an inbound trigger")?;
let timeout = self.timeout().await;
match tokio::time::timeout(timeout, self.runner.run(&self.ctx, &envelope)).await {
@@ -293,6 +404,11 @@ impl Deliverer {
);
return DeliverResponse::new(DeliverStatus::Accepted);
}
+ if let Some((name, source)) = self.pinned_source(&turn.events).await {
+ let remaining = self.budget.saturating_sub(started.elapsed());
+ let status = self.deliver_pinned(&turn, &name, &source, remaining).await;
+ return DeliverResponse::new(status);
+ }
let (envelope, first) = match self.envelope(&turn) {
Ok(found) => found,
Err(detail) => {
@@ -442,12 +558,17 @@ impl Deliverer {
/// Ask the queues to deliver `turn` again; when this was its last attempt
/// the queues dead-letter it instead, so say so.
fn retry(&self, turn: &Turn, after_ms: Option<u64>, why: &str) -> DeliverStatus {
- if (self.max_attempts)(turn.lane).is_some_and(|max| turn.attempt >= max) {
+ if self.exhausted(turn) {
self.dead(turn, &format!("{why}; attempts exhausted"));
}
DeliverStatus::Retry { after_ms }
}
+ /// Whether `turn` is on its lane's last attempt.
+ fn exhausted(&self, turn: &Turn) -> bool {
+ (self.max_attempts)(turn.lane).is_some_and(|max| turn.attempt >= max)
+ }
+
fn dead(&self, turn: &Turn, detail: &str) {
for event in &turn.events {
BUS.publish(DomainEvent::InboundDeadLettered {
diff --git a/crates/openhuman-core/src/inbound/mod.rs b/crates/openhuman-core/src/inbound/mod.rs
index 1552e983de..779808c7be 100644
--- a/crates/openhuman-core/src/inbound/mod.rs
+++ b/crates/openhuman-core/src/inbound/mod.rs
@@ -9,14 +9,23 @@
//! triage then, and a deferred triage is retried at the time it asked for
//! instead of being dropped.
//!
+//! External sources (`[inbound.sources.<name>]`, e.g. an X bot's mentions)
+//! push their events over `inbound.offer`. The queues debounce them per key
+//! into batches, each batch runs as one turn of the source's pinned agent
+//! with no triage, and the agent's final text is stored for the pusher to
+//! read (`inbound.results`) and acknowledge (`inbound.result_ack`).
+//! `InboundTurnCompleted` only wakes a subscriber; the RPC returns the text.
+//!
//! | piece | role |
//! | --- | --- |
//! | [`settings`] | `[inbound]` resolved: the queues and pipeline the module runs, the queue backend, whether routing is on |
-//! | [`events`] | a trigger envelope as an `InboundEvent`, and back |
+//! | [`events`] | a trigger envelope, or an external source's event, as an `InboundEvent`, and back |
//! | [`route`] | the hand-off; the caller's direct path runs when the queues do not take an event |
//! | [`deliver`] | `Deliver` and `ClassifySalience`: triage, ack semantics, retry and dead-letter events |
//! | [`host`] | the served `ai.tinyhumans.tinyeventqueues.Host` callbacks |
-//! | [`ops`], `schemas` | `inbound.stats`, `inbound.dead`, `inbound.redrive` |
+//! | [`pinned`] | a configured external source's batch run on its pinned agent, without triage |
+//! | [`results`] | what pinned turns produced, read over RPC and acknowledged |
+//! | [`ops`], `schemas` | `inbound.stats`, `inbound.dead`, `inbound.redrive`; `inbound.offer`, `inbound.results`, `inbound.result_ack` |
//!
//! The module client is `crate::modules::event_queues`; its registry record,
//! storage grant (the module's `teq.*` collections from its contract schema,
@@ -27,6 +36,8 @@ pub mod deliver;
pub mod events;
pub mod host;
pub mod ops;
+pub mod pinned;
+pub mod results;
pub mod route;
mod schemas;
pub mod settings;
@@ -40,4 +51,4 @@ pub use schemas::{
all_registered_controllers as all_inbound_registered_controllers,
};
pub(crate) use settings::queue_grant;
-pub use settings::{active, module_config};
+pub use settings::{active, module_config, with_sources};
diff --git a/crates/openhuman-core/src/inbound/pinned.rs b/crates/openhuman-core/src/inbound/pinned.rs
index dfb2a6581f..cdda30d68b 100644
--- a/crates/openhuman-core/src/inbound/pinned.rs
+++ b/crates/openhuman-core/src/inbound/pinned.rs
@@ -36,6 +36,9 @@ use crate::core::events::DomainEvent;
use crate::core::runtime::DispatchCtx;
use crate::triage::external_inbound_origin;
+/// How much of a failure is stored and published.
+const MAX_DETAIL_CHARS: usize = 1_000;
+
/// The placeholder a configured prompt takes the batch in.
const EVENTS_PLACEHOLDER: &str = "{{events}}";
@@ -294,7 +297,7 @@ impl Pinned {
/// Store `turn_id` as failed with `detail` and publish
/// `InboundTurnFailed`.
pub fn fail(&self, turn_id: &str, detail: &str) {
- let detail = crate::core::observability::scrub_detail(detail);
+ let detail: String = detail.chars().take(MAX_DETAIL_CHARS).collect();
match self.results.finish(turn_id, Err(detail.clone()), now_ms()) {
Ok(Some(stored)) => {
tracing::warn!(turn = %turn_id, detail = %detail, "[inbound] pinned turn failed");