How AO notifications moved from simple provider messages to semantic events routed across dashboard, desktop, Slack, Discord, Composio, Gmail, webhooks, and OpenClaw.
AO already had lifecycle events, but the notification layer was still too manual and too provider-specific. This branch turns notifications into a real platform: structured payloads, setup commands, routing policy, test tooling, dashboard history, desktop-native delivery, and rich provider rendering.
The core shift is simple: AO no longer just sends a string. It emits a semantic event. Every notifier can then render that event in a way that makes sense for its destination.
Notifications were useful, but not yet reliable as a system. Setup required too much YAML editing. Testing real providers was awkward. Slack, Discord, email, desktop, and local dashboard surfaces all needed different formats, but they were not sharing one consistent event model.
The result was predictable: every provider could drift, every setup path could fail differently, and users had no single way to verify whether AO would alert them at the right place.
| Area | Before | Now |
|---|---|---|
| Payloads | Mostly flat event data and provider-side interpretation. | Notification data schema v3 with semantic fields. |
| Setup | Manual YAML and provider-specific knowledge. | Interactive setup commands with validation, status, refresh, and routing. |
| Testing | Hard to test without triggering real lifecycle work. | ao notify test sends deterministic demo notifications. |
| Dashboard | No first-class notification center. | Bell UI with retained notifications, unread state, and links. |
| Desktop | Basic OS notifications and platform gaps. | AO Notifier app, fallback backends, grouping, badge support, and actions. |
The architecture centers on one normalized notification object. AO lifecycle code builds semantic data once. The routing layer chooses destinations by priority. Each notifier renders the same event according to its destination.
AO detects a session, PR, CI, review, merge, reaction, or escalation transition.
Core builds notification data v3 with stable, nested fields.
Priority maps to configured notifiers or explicit routing presets.
Slack, Discord, Gmail, desktop, dashboard, and others format the same event.
The notification links back to sessions, PRs, reviews, dashboards, or actions.
The v3 payload gives every provider the same vocabulary. Instead of guessing from strings, a notifier can inspect subject.pr, ci.status, review.decision, merge.ready, transition, and escalation.
{
"schemaVersion": 3,
"semanticType": "merge.ready",
"subject": {
"session": { "id": "demo-agent-29", "projectId": "demo" },
"pr": { "number": 1579, "url": "...", "branch": "feat/issue-1579" }
},
"transition": { "kind": "session_status", "from": "approved", "to": "mergeable" },
"ci": { "status": "passing" },
"review": { "decision": "approved" },
"merge": { "ready": true, "conflicts": false, "isBehind": false }
}This makes the providers cleaner. It also makes the notification payload easier to test because the event shape is explicit and versioned.
Setup now exists for dashboard, desktop, webhook, Slack, Discord, Composio, Composio Slack, Composio Discord webhook, Composio Discord bot, Composio Gmail, and OpenClaw.
These flows ask for the right inputs, explain where to get provider credentials, support refresh/status modes, and write the final YAML only after the flow has enough information.
Notifier routing moved from ad hoc list editing to explicit presets: urgent-only, urgent-action, and all.
That makes notification policy readable. Users can decide which destinations get high-signal alerts and which destinations receive the full stream.
ao notify test can send a real demo notification without spawning an agent. It supports templates, target selection, routes, actions, JSON output, dry runs, and a local sink.
This became the fast path for validating every notifier one by one.
The dashboard is now a notification destination, not just a place to inspect sessions. AO can write dashboard notifications to a config-scoped JSONL store. The web mux server reads that store and streams snapshots and appends to the browser over the existing WebSocket path.
dashboard-notifications.jsonl under the AO observability directory.The desktop path now has a native macOS helper app plus fallbacks. The AO Notifier app can request permission, send native notifications, group delivered notifications, maintain a badge count, expose delivered state, and handle URL or callback actions.
When the app is not installed, the plugin can fall back to terminal-notifier, then osascript on macOS. Linux still uses notify-send.
Native Slack now sends professional Block Kit messages with semantic colors, fields, status context, PR/review links, and action buttons.
Native Discord now sends embeds with provider-safe formatting, colors by priority, PR/CI/review/merge fields, retry behavior, and no broad mentions.
Composio now supports Slack, Discord webhook, Discord bot, and Gmail modes through setup flows and app-specific execution arguments.
Email notifications now render as HTML messages instead of raw HTML text, with clear headings, details, status blocks, and action links.
OpenClaw gets structured AO briefs, config-token discovery, retries, status probes, and health summaries without mutating the OpenClaw side.
The generic webhook notifier remains the plain integration point, now supported by setup, validation, headers, retries, and the test sink.
The branch is pushed and clean except for local untracked experiment files. The current implementation covers the full notifier system surface: payload creation, provider rendering, setup, manual tests, dashboard delivery, and desktop delivery.
The practical status is: the feature is built and provider smoke tests have been exercised manually, but the branch should still be rebased or merged with the current main branch before final CI.
| Track | Status | Notes |
|---|---|---|
| Feature branch | Implemented | feat/issue-1579 contains the notification system work. |
| Dashboard | Implemented | JSONL retention, mux streaming, bell UI, unread state, and semantic links. |
| Desktop | Implemented | AO Notifier app, fallback backends, badge grouping, icon update, and richer messages. |
| Provider rendering | Implemented | Slack, Discord, Composio, Gmail, OpenClaw, webhook, and desktop updated. |
| Final CI | Pending | Needs latest main integrated and stale integration expectations refreshed. |
notifyWithActions.ao notify test with templates for basic, agent stuck, needs input, CI failing, review changes requested, approved and green, merge ready, all complete, and PR closed.ao notify test.ao setup dashboard.ao setup desktop.ao setup webhook.ao setup slack.ao setup discord.