Skip to content

Session alerts

Every new alert belongs to a canonical session. Open alerts raise that session in the list: Urgent first, Normal next, Low last, then sessions without open attention. Recency is preserved within each priority. Snoozed and resolved alerts do not raise a session, and another person's private attention is never used to sort the reader's list.

GET /api/alerts accepts state, priority, session, mine and source. The source value matches the alert's kind, such as session, approval, clarification, connection or a standing rule's kind. Reads remain confined to the current tenant and session audience. POST /api/sessions/{id}/alerts creates attention; PATCH /api/alerts/{id} resolves, snoozes or reopens it.

Agents need an explicit alert_create or alert_resolve tool grant and the initiating person's standing alert-write permission. Creation accepts the current session ID, priority, title, optional body, action, resolve_when and at most 20 recipients. Recipients must already read the session. Naming someone never shares a private session. Titles are limited to 500 bytes, details to 10,000 bytes and resolution guidance to 500 bytes. A free-form resolution condition is guidance, not an executable condition or a grant.

Question and approval alerts resolve only after their authoritative answer is recorded. A canceled, expired or failed run does not count as an answer, and reading a session never resolves its alerts. Manually raised alerts require an explicit resolution, even when the run that raised them completes.

Personal notifications settings accept urgent, normal and low, each with immediate, digest or off. Suggested settings are Immediate, Digest and Off respectively. Unset settings stay Off; email still requires separate opt-in and a configured authorized recipient. Quiet hours and current access are rechecked before delivery. Canonical priority settings replace the legacy kind setting for session alerts. Older non-session transport rows keep their kind setting during migration. Internal inbox rows provide compatibility transport only; reading one does not change canonical attention. Interrupted transport projection is repaired from the durable alert on a later poll.

Confirmed connection authentication failures create one open reconnect alert per person and provider, in that person's private Builder session. The notice contains a fixed service label and reconnect action, never a provider error, endpoint, token or signing reference. Concurrent processes reuse the alert; a provider-confirmed reauthorization resolves the matching alert, and a later failure can raise new attention. A missing connection or transient network failure does not create reconnect attention.