Skip to main content

Notifications

The Notifications page is the full-history inbox for all system events generated by AI agents and the Beak AI Runtime. It is accessible from the sidebar and from the View all link in the notification bell dropdown. The page header shows the current unread count as "N unread" so users can gauge at a glance how much has accumulated since their last visit.

Notifications are generated for two primary event types: an agent raising a request that needs a human decision, and an approval request reaching a terminal outcome. Each notification links directly to the relevant context — either the approval detail pane or the originating chat thread — so users can act without navigating manually.

Page Header​

The header contains the page title Notifications, the live unread count, and the Mark all as read button. The Mark all as read button is disabled when the unread count is zero or while a bulk-read operation is in flight.

Notification List​

The notification list is rendered as a scrollable card. Each row is a NotificationItem and contains the following elements.

Notification Row​

  • Type icon — A circular icon badge coloured to reflect the event type and outcome. An approval request waiting for a decision uses the warning colour; an approval resolved as approved uses the success colour; rejected or cancelled outcomes use the error or muted colour respectively.
  • Title — The primary notification title in bold. Unread items also carry a small blue dot on the right edge of the title row.
  • Body excerpt — Up to two lines of the notification body text providing context about the event.
  • Timestamp — Relative time since the notification was created (for example 5m ago, 2h ago, 3d ago).

Clicking a Notification​

Clicking a row marks the notification as read (if it was unread) and navigates to the relevant resource.

  • Notifications of type needs_approval or approval_resolved deep-link to the Approvals page with the specific request pre-selected, so the user lands directly on the detail pane.
  • All other notification types (such as agent run completions) navigate to the originating chat thread when a thread ID is available.

Read and Unread States​

Unread rows have a highlighted background. Once read — either by clicking the row or using Mark all as read — the background returns to neutral. Individual rows can be marked read by clicking them; there is no separate per-row "mark read" button outside of clicking the item.

Pagination​

When the total notification count exceeds twenty items, pagination controls appear below the list. The controls show the current page as "Page N of N" and provide Previous and Next buttons. Both buttons disable automatically when the user is at the first or last page respectively. Each page loads twenty notifications.

Best Practices​

  • Act on needs_approval notifications promptly — Approval requests expire after a configured window; an expired request blocks the agent from completing the action that triggered it.
  • Use Mark all as read after a triage session — Clearing the unread count keeps the bell badge accurate and makes it easier to spot genuinely new events on the next visit.
  • Click through to the Approvals page for decisions — Clicking an approval notification lands you directly on the detail pane where the Approve and Reject buttons are available; you do not need to navigate manually.
  • Review the notification history after a busy period — The paginated history provides a lightweight audit trail of which agents raised requests and what outcomes were recorded.