Skip to content

armgit / avibe

Public Imported from GitHub
0

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.

26.2 KB
Raw Blame
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);
        }
    }
}