Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
use std::collections::VecDeque;
use std::sync::{Arc, Mutex};
use std::time::Duration;
use async_trait::async_trait;
use chrono::DateTime;
use serde::Deserialize;
use tokio::sync::{Notify, RwLock, Semaphore};
use tokio::task::JoinSet;
use tokio::time::Instant;
use url::Url;
use crate::LoopbackOrigin;
pub const RETAINED_KEYS: usize = 512;
pub const RETENTION: Duration = Duration::from_secs(24 * 60 * 60);
const MAX_EVENT_BYTES: usize = 64 * 1024;
const MAX_DETAIL_BYTES: usize = 256 * 1024;
const REQUEST_TIMEOUT: Duration = Duration::from_secs(5);
const STREAM_IDLE_TIMEOUT: Duration = Duration::from_secs(45);
const MAX_DETAIL_LOOKUPS: usize = 16;
const MAX_PENDING_LOOKUPS: usize = 64;
/// Shortest gap between two unread reads. Events arriving inside it collapse
/// into one read after it, so a busy stream costs at most one read per gap.
pub const UNREAD_REFRESH_INTERVAL: Duration = Duration::from_secs(1);
#[derive(Debug, PartialEq, Eq)]
pub struct SseFrame {
pub event: String,
pub data: String,
}
#[derive(Default)]
pub struct SseDecoder {
line: Vec<u8>,
event: String,
data: String,
skip_lf: bool,
started: bool,
bytes: usize,
discarded: bool,
line_has_bytes: bool,
}
impl SseDecoder {
pub fn new() -> Self {
Self::default()
}
pub fn push(&mut self, chunk: &[u8]) -> Vec<SseFrame> {
let mut frames = Vec::new();
for byte in chunk {
if self.skip_lf && *byte == b'\n' {
self.skip_lf = false;
continue;
}
self.skip_lf = *byte == b'\r';
if matches!(byte, b'\r' | b'\n') {
self.finish_line(&mut frames);
} else {
self.line_has_bytes = true;
if self.bytes < MAX_EVENT_BYTES {
self.line.push(*byte);
self.bytes += 1;
} else {
self.discarded = true;
}
}
}
frames
}
fn finish_line(&mut self, frames: &mut Vec<SseFrame>) {
if !std::mem::replace(&mut self.line_has_bytes, false) {
if !self.discarded && !self.data.is_empty() {
self.data.pop();
frames.push(SseFrame {
event: std::mem::take(&mut self.event),
data: std::mem::take(&mut self.data),
});
}
self.event.clear();
self.data.clear();
self.bytes = 0;
self.discarded = false;
return;
}
let line = std::mem::take(&mut self.line);
let Ok(line) = std::str::from_utf8(&line) else {
self.discarded = true;
return;
};
let line = if !std::mem::replace(&mut self.started, true) {
line.strip_prefix('\u{feff}').unwrap_or(line)
} else {
line
};
if self.discarded || line.starts_with(':') {
return;
}
let (field, value) = line.split_once(':').unwrap_or((line, ""));
let value = value.strip_prefix(' ').unwrap_or(value);
match field {
"event" => self.event = value.to_owned(),
"data" => {
self.data.push_str(value);
self.data.push('\n');
}
_ => {}
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum NotificationIntent {
ApprovalRequested,
RunSucceeded,
RunFailed,
RunCanceled,
}
#[derive(Clone, Copy, Debug)]
pub struct NotificationGate {
pub enabled: bool,
pub focused: bool,
pub visible: bool,
}
impl NotificationGate {
pub fn allows(self) -> bool {
self.enabled && !(self.focused && self.visible)
}
}
/// Account preferences are independent of the shell's device/focus gate.
#[derive(Clone, Copy, Debug, Deserialize, PartialEq, Eq)]
pub struct NotificationPreferences {
pub enabled: bool,
pub bots: bool,
pub sessions: bool,
}
impl Default for NotificationPreferences {
fn default() -> Self {
Self {
enabled: true,
bots: true,
sessions: true,
}
}
}
impl NotificationPreferences {
fn allows_run(self, category: Option<&str>) -> bool {
self.enabled
&& match category {
Some("bot") => self.bots,
Some("session") => self.sessions,
// Old servers, failed details, and overload have no trustworthy
// category. Generic copy must not bypass a quiet category.
_ => self.bots && self.sessions,
}
}
}
struct RunPreferences {
current: Arc<RwLock<NotificationPreferences>>,
at_receipt: NotificationPreferences,
}
pub trait NotificationSink: Send + Sync {
fn gate(&self) -> NotificationGate;
/// `source` names where a run happened ("Project · Session"), already
/// sanitized by [`RunDetail::source`]; `None` keeps the generic copy.
fn deliver(&self, intent: NotificationIntent, source: Option<String>);
/// The Runtime's badge total (loud-category unread), for the app icon.
/// It is state rather than an interruption: no device/focus gate applies.
fn show_unread(&self, total: u64);
/// A remote desktop update event is only a nudge. The shell must re-read
/// and validate its request file; the SSE payload never reaches this API.
fn desktop_update_requested(&self) {}
}
#[derive(Default)]
struct RetainedKeys(VecDeque<(String, Instant)>);
impl RetainedKeys {
fn insert(&mut self, key: &str, now: Instant) -> bool {
self.0.retain(|(_, inserted)| now.duration_since(*inserted) < RETENTION);
if let Some(index) = self.0.iter().position(|(retained, _)| retained == key) {
let retained = self.0.remove(index).expect("the retained key exists");
self.0.push_back(retained);
return false;
}
if self.0.len() == RETAINED_KEYS {
self.0.pop_front();
}
self.0.push_back((key.to_owned(), now));
true
}
fn remove(&mut self, key: &str) {
self.0.retain(|(retained, _)| retained != key);
}
}
#[derive(Default)]
pub struct NotificationFilter {
approvals: RetainedKeys,
runs: RetainedKeys,
}
#[derive(Deserialize)]
struct Envelope {
#[serde(rename = "type")]
event: String,
data: serde_json::Value,
}
#[derive(Deserialize)]
struct Approval {
request_id: String,
request_status: String,
}
#[derive(Clone, Default, Deserialize)]
pub struct RunTimestamps {
pub started_at: Option<String>,
pub completed_at: Option<String>,
pub updated_at: Option<String>,
}
impl RunTimestamps {
fn completion(&self) -> Option<&str> {
self.completed_at.as_deref().or(self.updated_at.as_deref())
}
fn missing(&self) -> bool {
self.started_at.is_none() || self.completion().is_none()
}
fn is_long_running(&self) -> bool {
let duration = self
.started_at
.as_deref()
.zip(self.completion())
.and_then(|(start, end)| {
let start = DateTime::parse_from_rfc3339(start).ok()?;
let end = DateTime::parse_from_rfc3339(end).ok()?;
Some(end.signed_duration_since(start))
});
duration.is_some_and(|duration| duration >= chrono::Duration::seconds(30))
}
fn fill_missing(&mut self, other: Self) {
if self.started_at.is_none() {
self.started_at = other.started_at;
}
if self.completion().is_none() {
self.completed_at = other.completed_at;
self.updated_at = other.updated_at;
}
}
}
/// The run detail the shell reads back after a terminal event: the stamps
/// that decide whether it is background work, plus the labels that say where
/// it ran. Every label is Runtime text on its way to an OS surface, so it only
/// leaves through [`RunDetail::source`].
#[derive(Clone, Default, Deserialize)]
pub struct RunDetail {
#[serde(flatten)]
pub stamps: RunTimestamps,
pub session_project_name: Option<String>,
pub session_label: Option<String>,
pub definition_name: Option<String>,
pub notification_category: Option<String>,
}
const SOURCE_PART_CHARS: usize = 48;
/// Invisible formatting a single-line title has no use for: bidi marks,
/// embeddings, overrides and isolates (which let a label render its own text
/// backwards), zero-width space, word joiner, BOM, and the private-use area.
/// ZWNJ, ZWJ and variation selectors stay: they spell real words and emoji and
/// cannot reorder text. Same set as `core/citations.py::_CONTROL_RE`.
fn is_invisible_format(character: char) -> bool {
matches!(
character,
'\u{061c}'
| '\u{200b}'
| '\u{200e}'
| '\u{200f}'
| '\u{202a}'..='\u{202e}'
| '\u{2060}'
| '\u{2066}'..='\u{2069}'
| '\u{feff}'
| '\u{e000}'..='\u{f8ff}'
)
}
fn clean_label(value: Option<&str>) -> Option<String> {
let words = value?
.chars()
.filter(|character| !is_invisible_format(*character))
.map(|character| {
if character.is_control() || matches!(character, '\u{2028}' | '\u{2029}') {
' '
} else {
character
}
})
.collect::<String>();
let collapsed = words.split_whitespace().collect::<Vec<_>>().join(" ");
if collapsed.is_empty() {
return None;
}
if collapsed.chars().count() <= SOURCE_PART_CHARS {
return Some(collapsed);
}
let mut truncated = collapsed.chars().take(SOURCE_PART_CHARS - 1).collect::<String>();
truncated.truncate(truncated.trim_end().len());
truncated.push('…');
Some(truncated)
}
impl RunDetail {
/// "Project · Session" for a Workbench session, the channel for an IM
/// session, and the task or watch name when no session resolved. Control
/// characters and invisible bidi/zero-width formatting are removed,
/// whitespace collapsed, and each part bounded.
pub fn source(&self) -> Option<String> {
let project = clean_label(self.session_project_name.as_deref());
let place = clean_label(self.session_label.as_deref()).or_else(|| clean_label(self.definition_name.as_deref()));
match (project, place) {
(Some(project), Some(place)) if project != place => Some(format!("{project} · {place}")),
(project, place) => place.or(project),
}
}
}
#[derive(Deserialize)]
struct RunEvent {
run_id: String,
status: String,
run_type: Option<String>,
#[serde(flatten)]
stamps: RunTimestamps,
}
enum Candidate {
Approval,
Run {
run_id: String,
stamps: RunTimestamps,
intent: NotificationIntent,
/// Already background work by type or by the event's own stamps; the
/// detail read only supplies the source label.
background: bool,
},
}
impl NotificationFilter {
fn consider(&mut self, frame: SseFrame, now: Instant) -> Option<Candidate> {
if !matches!(frame.event.as_str(), "vaults.updated" | "runs.updated") {
return None;
}
let envelope: Envelope = serde_json::from_str(&frame.data).ok()?;
if envelope.event != frame.event {
return None;
}
if frame.event == "vaults.updated" {
let approval: Approval = serde_json::from_value(envelope.data).ok()?;
if approval.request_id.is_empty() {
return None;
}
if approval.request_status != "pending" {
self.approvals.remove(&approval.request_id);
return None;
}
return self
.approvals
.insert(&approval.request_id, now)
.then_some(Candidate::Approval);
}
let run: RunEvent = serde_json::from_value(envelope.data).ok()?;
if run.run_id.is_empty() {
return None;
}
let intent = match run.status.as_str() {
"succeeded" => NotificationIntent::RunSucceeded,
"failed" => NotificationIntent::RunFailed,
"canceled" => NotificationIntent::RunCanceled,
_ => return None,
};
if !self.runs.insert(&run.run_id, now) {
return None;
}
let background = matches!(run.run_type.as_deref(), Some("scheduled" | "watch")) || run.stamps.is_long_running();
(background || run.stamps.missing()).then_some(Candidate::Run {
run_id: run.run_id,
stamps: run.stamps,
intent,
background,
})
}
}
#[async_trait]
pub trait EventStream: Send {
async fn next_chunk(&mut self) -> Result<Option<Vec<u8>>, StreamError>;
}
#[derive(Debug)]
pub struct StreamError;
#[async_trait]
pub trait NotificationTransport: Send + Sync {
async fn connect(&self) -> Result<Box<dyn EventStream>, StreamError>;
async fn run_detail(&self, run_id: &str) -> Option<RunDetail>;
async fn unread_total(&self) -> Option<u64>;
async fn preferences(&self) -> Option<NotificationPreferences>;
}
pub struct HttpNotificationTransport {
client: reqwest::Client,
origin: LoopbackOrigin,
}
impl HttpNotificationTransport {
pub fn new(origin: LoopbackOrigin) -> Result<Self, reqwest::Error> {
Ok(Self {
client: reqwest::Client::builder()
.connect_timeout(REQUEST_TIMEOUT)
.redirect(reqwest::redirect::Policy::none())
.no_proxy()
.build()?,
origin,
})
}
fn url(&self, path: &str) -> Url {
Url::parse(&format!("{}{path}", self.origin.as_str())).expect("the Runtime origin is validated")
}
}
struct HttpEventStream(reqwest::Response);
#[async_trait]
impl EventStream for HttpEventStream {
async fn next_chunk(&mut self) -> Result<Option<Vec<u8>>, StreamError> {
self.0
.chunk()
.await
.map(|chunk| chunk.map(|chunk| chunk.to_vec()))
.map_err(|_| StreamError)
}
}
#[async_trait]
impl NotificationTransport for HttpNotificationTransport {
async fn connect(&self) -> Result<Box<dyn EventStream>, StreamError> {
let response = tokio::time::timeout(
REQUEST_TIMEOUT,
self.client
.get(self.url("/api/events"))
.header("Accept", "text/event-stream")
.send(),
)
.await
.map_err(|_| StreamError)?
.map_err(|_| StreamError)?;
let content_type = response
.headers()
.get(reqwest::header::CONTENT_TYPE)
.and_then(|value| value.to_str().ok());
if response.status() != reqwest::StatusCode::OK
|| !content_type.is_some_and(|value| {
value
.split(';')
.next()
.is_some_and(|mime| mime.trim() == "text/event-stream")
})
{
return Err(StreamError);
}
Ok(Box::new(HttpEventStream(response)))
}
async fn run_detail(&self, run_id: &str) -> Option<RunDetail> {
if matches!(run_id, "" | "." | "..") {
return None;
}
let mut url = self.url("/api/harness/runs/");
url.path_segments_mut().ok()?.pop_if_empty().push(run_id);
let response = self.client.get(url).timeout(REQUEST_TIMEOUT).send().await.ok()?;
if !response.status().is_success() {
return None;
}
let bytes = bounded_detail_body(response).await?;
let detail: serde_json::Value = serde_json::from_slice(&bytes).ok()?;
if !detail.get("ok")?.as_bool()? || detail.get("run")?.get("id")?.as_str()? != run_id {
return None;
}
serde_json::from_value(detail.get("run")?.clone()).ok()
}
/// The same whole-account total the Workbench Inbox badges, counted by the
/// Runtime: the shell never derives a count of its own.
async fn unread_total(&self) -> Option<u64> {
let mut url = self.url("/api/inbox");
url.query_pairs_mut()
.append_pair("platform", "avibe")
.append_pair("limit", "1");
let response = self.client.get(url).timeout(REQUEST_TIMEOUT).send().await.ok()?;
if !response.status().is_success() {
return None;
}
let bytes = bounded_detail_body(response).await?;
let inbox: serde_json::Value = serde_json::from_slice(&bytes).ok()?;
// Fall back only when absent, not when malformed: an explicit zero
// must never turn into the raw (possibly quiet-category) unread count.
inbox.get("badge_total").or_else(|| inbox.get("unread_total"))?.as_u64()
}
async fn preferences(&self) -> Option<NotificationPreferences> {
let response = self
.client
.get(self.url("/api/notifications/preferences"))
.timeout(REQUEST_TIMEOUT)
.send()
.await
.ok()?;
if !response.status().is_success() {
return None;
}
let bytes = bounded_detail_body(response).await?;
let document: serde_json::Value = serde_json::from_slice(&bytes).ok()?;
if !document.get("ok")?.as_bool()? {
return None;
}
serde_json::from_value(document.get("preferences")?.clone()).ok()
}
}
async fn bounded_detail_body(mut response: reqwest::Response) -> Option<Vec<u8>> {
if response
.content_length()
.is_some_and(|size| size > MAX_DETAIL_BYTES as u64)
{
return None;
}
let mut body = Vec::new();
while let Some(chunk) = response.chunk().await.ok()? {
if chunk.len() > MAX_DETAIL_BYTES.saturating_sub(body.len()) {
return None;
}
body.extend_from_slice(&chunk);
}
Some(body)
}
#[derive(Default)]
pub struct ReconnectBackoff {
failures: u32,
}
impl ReconnectBackoff {
pub fn next_delay(&mut self) -> Duration {
let delay = Duration::from_secs(1u64 << self.failures.min(5)).min(Duration::from_secs(30));
self.failures = self.failures.saturating_add(1);
delay
}
pub fn reset(&mut self) {
self.failures = 0;
}
}
pub async fn run_notifications(
transport: Arc<dyn NotificationTransport>,
filter: Arc<Mutex<NotificationFilter>>,
sink: Arc<dyn NotificationSink>,
) {
let mut backoff = ReconnectBackoff::default();
let preferences = Arc::new(RwLock::new(NotificationPreferences::default()));
// Any frame may follow an unread change, and listing the event types that
// can would miss the next one added, so every connection and every frame
// (the 15-second heartbeat included) asks for a fresh total. The reader
// owns the rate. Dropping the set with this future stops it.
let unread_changed = Arc::new(Notify::new());
let mut unread = JoinSet::new();
unread.spawn(follow_unread(transport.clone(), sink.clone(), unread_changed.clone()));
// Detail reads run beside the stream, never inside it: a slow read must
// not hold back the next chunk (and the approval it may carry). Dropping
// the set with this future aborts whatever is still in flight.
let mut lookups = JoinSet::new();
let slots = Arc::new(Semaphore::new(MAX_DETAIL_LOOKUPS));
loop {
let connected_at = Instant::now();
if let Ok(mut stream) = transport.connect().await {
unread_changed.notify_one();
refresh_preferences(&transport, &preferences).await;
let mut decoder = SseDecoder::new();
while let Ok(Ok(Some(chunk))) = tokio::time::timeout(STREAM_IDLE_TIMEOUT, stream.next_chunk()).await {
if Instant::now().duration_since(connected_at) >= STREAM_IDLE_TIMEOUT {
backoff.reset();
}
while lookups.try_join_next().is_some() {}
// Suppression is not a queue: frames still reach the filter so
// its de-duplication stays current, then are dropped.
for frame in decoder.push(&chunk) {
unread_changed.notify_one();
if frame.event == "notifications.preferences.updated" {
// Only a nudge: never trust preferences from the SSE payload.
refresh_preferences(&transport, &preferences).await;
continue;
}
let at_receipt = *preferences.read().await;
let allowed_at_receipt = sink.gate().allows() && at_receipt.enabled;
if frame.event == "desktop.update.requested" {
sink.desktop_update_requested();
continue;
}
let candidate = filter
.lock()
.ok()
.and_then(|mut filter| filter.consider(frame, Instant::now()))
.filter(|_| allowed_at_receipt);
match candidate {
None => {}
Some(Candidate::Approval) => {
if sink.gate().allows() {
sink.deliver(NotificationIntent::ApprovalRequested, None);
}
}
Some(Candidate::Run {
run_id,
stamps,
intent,
background,
}) => {
while lookups.try_join_next().is_some() {}
if lookups.len() >= MAX_PENDING_LOOKUPS {
// Overloaded: the backlog is bounded. Work the
// event already qualifies notifies now with
// generic copy; a run only its read could
// qualify fails closed.
if background && at_receipt.allows_run(None) && sink.gate().allows() {
sink.deliver(intent, None);
}
continue;
}
let (transport, sink, slots) = (transport.clone(), sink.clone(), slots.clone());
let preferences = RunPreferences {
current: preferences.clone(),
at_receipt,
};
lookups.spawn(async move {
// Queue behind the request limit rather than
// drop: a run without stamps is only decided
// by its read.
let Ok(_slot) = slots.acquire_owned().await else {
return;
};
notify_run(transport, sink, run_id, stamps, intent, background, preferences).await;
});
}
}
}
}
}
tokio::time::sleep(backoff.next_delay()).await;
}
}
/// Refresh before consuming further frames. The bounded write lock also holds
/// in-flight run deliveries until the new preference snapshot is known. On a
/// failed/old-server read, keep the last valid value (initially all on).
async fn refresh_preferences(
transport: &Arc<dyn NotificationTransport>,
preferences: &RwLock<NotificationPreferences>,
) {
let mut current = preferences.write().await;
if let Ok(Some(fresh)) = tokio::time::timeout(REQUEST_TIMEOUT, transport.preferences()).await {
*current = fresh;
}
}
/// Reads the total after each signal, then waits out the refresh interval.
/// `Notify` keeps at most one stored signal, so any number of events during a
/// read or a wait become exactly one more read. A failed read keeps the badge
/// already shown until the next frame — at the latest the next heartbeat.
async fn follow_unread(
transport: Arc<dyn NotificationTransport>,
sink: Arc<dyn NotificationSink>,
changed: Arc<Notify>,
) {
loop {
changed.notified().await;
if let Some(total) = transport.unread_total().await {
sink.show_unread(total);
}
tokio::time::sleep(UNREAD_REFRESH_INTERVAL).await;
}
}
/// One bounded read per terminal run: it names the source and, when the event
/// lacked stamps, decides whether the run was background work at all.
async fn notify_run(
transport: Arc<dyn NotificationTransport>,
sink: Arc<dyn NotificationSink>,
run_id: String,
mut stamps: RunTimestamps,
intent: NotificationIntent,
background: bool,
preferences: RunPreferences,
) {
let detail = tokio::time::timeout(REQUEST_TIMEOUT, transport.run_detail(&run_id))
.await
.ok()
.flatten();
let source = detail.as_ref().and_then(RunDetail::source);
let category = detail
.as_ref()
.and_then(|detail| detail.notification_category.as_deref());
let current = preferences.current.read().await;
if !preferences.at_receipt.allows_run(category) || !current.allows_run(category) {
return;
}
if let Some(detail) = detail {
stamps.fill_missing(detail.stamps);
}
if (background || stamps.is_long_running()) && sink.gate().allows() {
sink.deliver(intent, source);
}
}
#[cfg(test)]
mod tests {
use super::*;
#[tokio::test(start_paused = true)]
async fn both_retained_sets_are_bounded_by_size_and_age_even_without_transition_events() {
for keys in [
&mut NotificationFilter::default().approvals,
&mut NotificationFilter::default().runs,
] {
let created = Instant::now();
for index in 0..RETAINED_KEYS * 3 {
assert!(keys.insert(&index.to_string(), created));
assert!(keys.0.len() <= RETAINED_KEYS);
}
assert_eq!(keys.0.len(), RETAINED_KEYS);
assert!(keys.insert("0", created));
assert!(!keys.insert("0", created));
tokio::time::advance(RETENTION).await;
assert!(keys.insert("0", Instant::now()));
assert_eq!(keys.0.len(), 1);
}
}
}