Skip to content

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

feat(inbound): add support for external inbound events

Steven Enamakeldfba872fb40e
diff --git a/crates/openhuman-core/src/inbound/events.rs b/crates/openhuman-core/src/inbound/events.rs
index 2c8c225fdb..fd69226a8c 100644
--- a/crates/openhuman-core/src/inbound/events.rs
+++ b/crates/openhuman-core/src/inbound/events.rs
@@ -14,6 +14,10 @@
//! - kind `Trigger` (never ambient chatter), and the envelope itself in `raw`,
//! from which `Deliver` rebuilds it ([`envelope_of`]).
//!
+//! An event pushed from an external source (`inbound.offer`) is
+//! [`external`]: keyed by the caller's `key`, so a source's events debounce
+//! into batches its pinned agent reads back with [`external_of`].
+//!
//! A digest turn (the queues folded an overflow into one) becomes a single
//! external envelope listing its events ([`digest_envelope`]), so a flood
//! costs one triage, not one per event.
@@ -194,6 +198,83 @@ pub fn webhook(
)
}
+/// Raw kind of an event pushed from an external source (`inbound.offer`).
+const EXTERNAL: &str = "external";
+
+/// An external event as `raw` stores it.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+struct ExternalRaw {
+ kind: String,
+ text: String,
+ payload: Value,
+ received_at_ms: u64,
+}
+
+/// One external event as its pinned agent reads it.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ExternalItem {
+ /// The source's own event id.
+ pub id: String,
+ /// The event's text.
+ pub text: String,
+ /// The source's payload, as pushed.
+ pub payload: Value,
+ /// When the source received it, Unix epoch milliseconds.
+ pub received_at_ms: u64,
+}
+
+/// The inbound event of an event pushed from external source `source`
+/// (`inbound.offer`). Its `conversation_key` is `key` and its sender the
+/// source itself, so the queues debounce a source's events per key into one
+/// batch; `event_id` is the source's own id, so a redelivery is rejected.
+///
+/// # Errors
+///
+/// [`Unqueueable::Oversize`] for one too large to queue.
+pub fn external(
+ source: &str,
+ key: &str,
+ event_id: &str,
+ text: &str,
+ payload: Value,
+ received_at_ms: u64,
+) -> Result<InboundEvent, Unqueueable> {
+ let raw = serde_json::to_value(ExternalRaw {
+ kind: EXTERNAL.to_owned(),
+ text: text.to_owned(),
+ payload,
+ received_at_ms,
+ })
+ .map_err(|_| Unqueueable::Source)?;
+ let bytes = raw.to_string().len();
+ if bytes > MAX_RAW_BYTES {
+ return Err(Unqueueable::Oversize(bytes));
+ }
+ Ok(InboundEvent::new(
+ source,
+ event_id,
+ key,
+ Sender::new(source),
+ EventKind::Trigger,
+ received_at_ms,
+ )
+ .text(text.to_owned())
+ .raw(raw))
+}
+
+/// The external item an inbound event was offered as, or `None` for an event
+/// that was not pushed from an external source.
+#[must_use]
+pub fn external_of(event: &InboundEvent) -> Option<ExternalItem> {
+ let raw: ExternalRaw = serde_json::from_value(event.raw.clone()?).ok()?;
+ (raw.kind == EXTERNAL).then(|| ExternalItem {
+ id: event.event_id.clone(),
+ text: raw.text,
+ payload: raw.payload,
+ received_at_ms: raw.received_at_ms,
+ })
+}
+
/// The envelope an inbound event was queued from, or `None` for an event
/// that did not come from a trigger.
#[must_use]
diff --git a/crates/openhuman-core/src/inbound/settings.rs b/crates/openhuman-core/src/inbound/settings.rs
index cc5dd5a744..52bb4ee28f 100644
--- a/crates/openhuman-core/src/inbound/settings.rs
+++ b/crates/openhuman-core/src/inbound/settings.rs
@@ -16,6 +16,7 @@ use tinyeventqueues_bus::{Lane, PipelineConfig};
use tinystoragedrivers::queue::QueueManifest;
use tinystoragedrivers::QueueConfig;
+use crate::config::schema::InboundConfig;
use crate::config::Config;
use crate::modules::storage_grant_schemas::QueueGrant;
@@ -81,9 +82,53 @@ pub fn resolve(config: &Config) -> Result<Resolved, String> {
config.inbound.pipeline_path.as_deref(),
SHIPPED_PIPELINE_JSON,
)?;
+ let pipeline: Value =
+ serde_json::from_str(&pipeline).map_err(|error| format!("pipeline.json: {error}"))?;
+ let pipeline = with_sources(pipeline, &config.inbound).to_string();
resolve_texts(&queues, &pipeline, config.inbound.queue_url.as_deref())
}
+/// `pipeline` with one source policy per usable `[inbound.sources.*]` entry
+/// ahead of its own (the first match wins): acknowledged at ingest, weighted
+/// into the interactive lane, released at once rather than on a lane's
+/// cadence, and debounced with the source's own windows and batch cap.
+#[must_use]
+pub fn with_sources(mut pipeline: Value, inbound: &InboundConfig) -> Value {
+ let policies: Vec<Value> = inbound
+ .usable_sources()
+ .map(|(name, source)| {
+ json!({
+ "match": name,
+ "ack": "after_ingest",
+ "weight": SOURCE_WEIGHT,
+ "cadence": "instant",
+ "coalesce": {
+ "debounce_ms": source.debounce_ms,
+ "max_wait_ms": source.max_wait_ms,
+ "max_events": source.max_batch,
+ },
+ })
+ })
+ .collect();
+ if policies.is_empty() {
+ return pipeline;
+ }
+ let Some(object) = pipeline.as_object_mut() else {
+ return pipeline;
+ };
+ let mut sources = policies;
+ if let Some(Value::Array(own)) = object.remove("sources") {
+ sources.extend(own);
+ }
+ object.insert("sources".to_owned(), Value::Array(sources));
+ pipeline
+}
+
+/// Salience points an external source's events get: the base 25 plus this
+/// reaches the interactive lane (70), so a batch is never scheduled on the
+/// background lane's cadence or folded into the digest as noise.
+const SOURCE_WEIGHT: i32 = 50;
+
fn read_or(path: Option<&Path>, shipped: &str) -> Result<String, String> {
match path {
Some(path) => std::fs::read_to_string(path)
diff --git a/crates/openhuman-core/src/triage/mod.rs b/crates/openhuman-core/src/triage/mod.rs
index 6c9ce1bb7f..1df356d12f 100644
--- a/crates/openhuman-core/src/triage/mod.rs
+++ b/crates/openhuman-core/src/triage/mod.rs
@@ -46,6 +46,6 @@ pub use decision::{parse_triage_decision, ParseError, TriageAction, TriageDecisi
pub use envelope::{TriggerEnvelope, TriggerSource};
pub use escalation::apply_decision;
pub use evaluator::{run_triage, TriageOutcome, TriageResolutionPath, TriageRun};
-pub use origin::{local_trigger_origin, remote_trigger_origin};
+pub use origin::{external_inbound_origin, local_trigger_origin, remote_trigger_origin};
pub use routing::{build_local_provider_with_config, ResolvedProvider};
pub use runner::{RemoteTriage, TriageRunner};