Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
import { NOTIFICATION_ALERT_SOUND_SRC } from '@constants/notifications'
import type {
PendingWorkflowApproval,
WorkflowApprovalDecisionResult,
WorkflowNotificationStreamEvent,
WorkflowRunCompletedNotification,
} from '../../../../src/types'
import type {
AppNotification,
DesktopNotificationPayload,
DesktopNotificationPermission,
Tone,
} from '../../uiTypes'
import type { ApprovalDecisionTarget } from './approvalDecision'
import type { PushNotificationInput, SetStatusFn } from './types'
type WorkflowApprovalDecisionCallbackInput = {
approval: PendingWorkflowApproval
decision: 'approve' | 'deny'
result: WorkflowApprovalDecisionResult
}
type WorkflowRunCompletedStreamEvent = {
type: 'workflow.run.completed'
id: string
cursor: string
observedAt: string
workflowRun: WorkflowRunCompletedNotification
}
interface UseNotificationsControllerParams {
isAuthenticated: boolean
notificationSoundVolume: number
canDeliverChatResponseNotification: (
channel: 'inApp' | 'desktop',
context: { activeChatVisible: boolean }
) => boolean
showDesktopNotification: (
payload: DesktopNotificationPayload
) => Promise<DesktopNotificationPermission>
onWorkflowApprovalDecision?: (
input: WorkflowApprovalDecisionCallbackInput
) => Promise<void> | void
/** §4.7.4: the central approval decider — the in-app bell funnels through it so
* the chat FSM badge converges when deciding from the notification panel. */
decideApproval: (target: ApprovalDecisionTarget) => Promise<void>
pushToast: (msg: string, tone: Tone) => void
setStatus: SetStatusFn
}
function isWorkflowRunCompletedStreamEvent(
event: unknown
): event is WorkflowRunCompletedStreamEvent {
const record = event && typeof event === 'object' ? (event as Record<string, unknown>) : null
const workflowRun =
record?.workflowRun && typeof record.workflowRun === 'object'
? (record.workflowRun as Record<string, unknown>)
: null
const target =
workflowRun?.target && typeof workflowRun.target === 'object'
? (workflowRun.target as Record<string, unknown>)
: null
return Boolean(
record?.type === 'workflow.run.completed' &&
typeof record.id === 'string' &&
typeof record.cursor === 'string' &&
typeof record.observedAt === 'string' &&
workflowRun &&
typeof workflowRun.workflowRunId === 'string' &&
typeof workflowRun.approvalRequestId === 'string' &&
typeof workflowRun.recipeNamespace === 'string' &&
typeof workflowRun.recipeName === 'string' &&
['Succeeded', 'Failed', 'Canceled'].includes(String(workflowRun.phase || '')) &&
typeof workflowRun.completedAt === 'string' &&
target
)
}
function workflowCompletionText(
workflowRun: WorkflowRunCompletedStreamEvent['workflowRun']
): string {
if (workflowRun.phase === 'Succeeded') {
return 'Workflow ' + workflowRun.recipeName + ' completed. Results are ready.'
}
return (
'Workflow ' +
workflowRun.recipeName +
' finished with status ' +
workflowRun.phase +
'. Check available results.'
)
}
function workflowCompletionTimestamp(
workflowRun: WorkflowRunCompletedStreamEvent['workflowRun']
): number {
const parsed = new Date(workflowRun.completedAt).getTime()
return Number.isFinite(parsed) ? parsed : Date.now()
}
function activeApprovals(items: PendingWorkflowApproval[]): PendingWorkflowApproval[] {
const now = Date.now()
const seenApprovalIds = new Set<string>()
return items.filter(approval => {
if (new Date(approval.expiresAt).getTime() <= now) return false
if (seenApprovalIds.has(approval.id)) return false
seenApprovalIds.add(approval.id)
return true
})
}
function upsertApproval(
current: PendingWorkflowApproval[],
approval: PendingWorkflowApproval
): PendingWorkflowApproval[] {
if (new Date(approval.expiresAt).getTime() <= Date.now()) return current
const existingIndex = current.findIndex(item => item.id === approval.id)
if (existingIndex >= 0) {
const next = [...current]
next[existingIndex] = approval
return activeApprovals(next)
}
return activeApprovals([approval, ...current])
}
function isSdkNotificationStreamEvent(
event: WorkflowNotificationStreamEvent
): event is Extract<WorkflowNotificationStreamEvent, { type: 'sdk.notification' }> {
return event.type === 'sdk.notification'
}
export function useNotificationsController({
isAuthenticated,
notificationSoundVolume,
canDeliverChatResponseNotification,
showDesktopNotification,
onWorkflowApprovalDecision,
decideApproval,
pushToast,
setStatus,
}: UseNotificationsControllerParams) {
const [notifications, setNotifications] = useState<AppNotification[]>([])
const [notificationActionById, setNotificationActionById] = useState<
Record<string, 'approving' | 'denying' | undefined>
>({})
const [pendingApprovals, setPendingApprovals] = useState<PendingWorkflowApproval[]>([])
const [pendingApprovalsLoading, setPendingApprovalsLoading] = useState(false)
const [pendingApprovalActionId, setPendingApprovalActionId] = useState<string | null>(null)
const notificationSoundRef = useRef<HTMLAudioElement | null>(null)
const seenNotificationIdsRef = useRef<Set<string>>(new Set())
const notificationSoundInitializedRef = useRef(false)
const lastNotificationStreamErrorRef = useRef<string | null>(null)
const unreadNotificationCount = useMemo(
() => notifications.reduce((count, notification) => count + (notification.read ? 0 : 1), 0),
[notifications]
)
const playNotificationSound = useCallback(
(volume = notificationSoundVolume) => {
if (typeof Audio === 'undefined') return
if (volume <= 0) return
const audio = notificationSoundRef.current ?? new Audio(NOTIFICATION_ALERT_SOUND_SRC)
notificationSoundRef.current = audio
audio.volume = volume / 100
audio.currentTime = 0
void audio.play().catch(error => {
console.warn('[useNotificationsController] notification sound playback failed', error)
})
},
[notificationSoundVolume]
)
useEffect(() => {
const nextSeenNotificationIds = new Set(notifications.map(notification => notification.id))
if (!notificationSoundInitializedRef.current) {
notificationSoundInitializedRef.current = true
seenNotificationIdsRef.current = nextSeenNotificationIds
return
}
const latestNotification = notifications[0]
if (!latestNotification) {
seenNotificationIdsRef.current = nextSeenNotificationIds
return
}
const seenNotificationIds = seenNotificationIdsRef.current
const latestIsNew = !seenNotificationIds.has(latestNotification.id)
seenNotificationIdsRef.current = nextSeenNotificationIds
if (latestIsNew) {
playNotificationSound()
}
}, [notifications, playNotificationSound])
const pushNotification = useCallback((input: PushNotificationInput) => {
const text = input.text.trim()
if (!text) return
setNotifications(previous => {
if (input.dedupeKey) {
const existingIndex = previous.findIndex(
notification => notification.dedupeKey === input.dedupeKey
)
if (existingIndex >= 0) {
const existing = previous[existingIndex]
if (!existing) return previous
const merged: AppNotification = {
...existing,
text,
chatId: input.chatId ?? existing.chatId,
teamId: input.teamId ?? existing.teamId,
teamName: input.teamName ?? existing.teamName,
timestamp: input.timestamp ?? existing.timestamp,
approval: input.approval || existing.approval,
approvalState: existing.approvalState,
workflow: input.workflow || existing.workflow,
sdk: input.sdk || existing.sdk,
}
const next = [...previous]
next[existingIndex] = merged
return next
}
}
const next: AppNotification = {
id: crypto.randomUUID(),
kind: input.kind,
agentName: input.agentName,
chatId: input.chatId,
teamId: input.teamId,
teamName: input.teamName,
text,
timestamp: input.timestamp ?? Date.now(),
read: false,
approval: input.approval,
approvalState: input.approvalState,
workflow: input.workflow,
sdk: input.sdk,
dedupeKey: input.dedupeKey,
}
return [next, ...previous].slice(0, 80)
})
}, [])
const markNotificationsRead = useCallback(() => {
setNotifications(previous =>
previous.some(notification => !notification.read)
? previous.map(notification =>
notification.read ? notification : { ...notification, read: true }
)
: previous
)
}, [])
const markNotificationRead = useCallback((notificationId: string) => {
setNotifications(previous =>
previous.map(entry =>
entry.id === notificationId && !entry.read ? { ...entry, read: true } : entry
)
)
}, [])
const clearNotifications = useCallback(() => {
setNotifications([])
setNotificationActionById({})
}, [])
const removeNotification = useCallback((notificationId: string) => {
if (!notificationId) return
setNotifications(previous =>
previous.filter(notification => notification.id !== notificationId)
)
setNotificationActionById(previous => {
if (!(notificationId in previous)) return previous
const next = { ...previous }
delete next[notificationId]
return next
})
}, [])
const resolveApprovalNotification = useCallback(
({
agentName,
taskId,
requestId,
state,
}: {
agentName: string
taskId: string
requestId: string
state: 'approved' | 'denied'
}) => {
setNotifications(previous =>
previous.map(notification => {
const approval = notification.approval
const matchesApproval =
notification.kind === 'approval_required' &&
notification.agentName === agentName &&
approval?.taskId === taskId &&
approval.requestId === requestId
return matchesApproval
? { ...notification, read: true, approvalState: state }
: notification
})
)
},
[]
)
// Surface (b), §4.7.4: the bell funnels through the central decider (optimistic
// FSM dispatch + RPC + resolve/toast/revert). The panel keeps its LOCAL spinner
// (setNotificationActionById); the resolved/denied visual state now derives from
// the central `resolveApprovalNotification` (matched by agentName/taskId/requestId)
// rather than a separate `setNotificationApprovalState`.
const decideFromBell = useCallback(
async (notification: AppNotification, decision: 'approve' | 'deny') => {
if (!notification.approval) return
if (notification.approvalState) return
setNotificationActionById(previous => ({
...previous,
[notification.id]: decision === 'approve' ? 'approving' : 'denying',
}))
try {
await decideApproval({
agentRef: notification.agentName,
chatId: notification.chatId ?? '',
teamId: notification.teamId,
taskId: notification.approval.taskId,
requestId: notification.approval.requestId,
decision,
source: 'inapp_bell',
})
} finally {
setNotificationActionById(previous => {
const next = { ...previous }
delete next[notification.id]
return next
})
}
},
[decideApproval]
)
const handleApproveNotification = useCallback(
(notification: AppNotification) => decideFromBell(notification, 'approve'),
[decideFromBell]
)
const handleDenyNotification = useCallback(
(notification: AppNotification) => decideFromBell(notification, 'deny'),
[decideFromBell]
)
const handleRefreshPendingApprovals = useCallback(
async (options: { silent?: boolean } = {}) => {
const { silent = false } = options
if (!isAuthenticated) {
setPendingApprovals([])
setPendingApprovalsLoading(false)
return
}
const showLoadingState = !silent || pendingApprovals.length === 0
if (showLoadingState) {
setPendingApprovalsLoading(true)
}
try {
const items = await window.clerum.approvals.listPending(20)
setPendingApprovals(activeApprovals(Array.isArray(items) ? items : []))
} catch (error) {
if (!silent) {
setStatus(
`Failed loading pending approvals: ${error instanceof Error ? error.message : String(error)}`,
'error'
)
}
} finally {
if (showLoadingState) {
setPendingApprovalsLoading(false)
}
}
},
[isAuthenticated, pendingApprovals.length, setStatus]
)
useEffect(() => {
if (!isAuthenticated) {
setPendingApprovals([])
setPendingApprovalsLoading(false)
lastNotificationStreamErrorRef.current = null
return
}
let disposed = false
let unsubscribe: (() => Promise<void>) | null = null
setPendingApprovalsLoading(true)
const handleStreamEvent = (event: WorkflowNotificationStreamEvent) => {
if (disposed) return
if (event.type === 'open') {
lastNotificationStreamErrorRef.current = null
return
}
if (event.type === 'notification.snapshot') {
const snapshotTeamIds = new Set(
event.items.map(item => String(item.target.teamId || '')).filter(Boolean)
)
setPendingApprovals(current => {
const retained = snapshotTeamIds.size
? current.filter(item => !snapshotTeamIds.has(String(item.target.teamId || '')))
: []
return activeApprovals([...event.items, ...retained])
})
setPendingApprovalsLoading(false)
lastNotificationStreamErrorRef.current = null
return
}
if (event.type === 'approval.requested') {
setPendingApprovals(current => upsertApproval(current, event.approval))
setPendingApprovalsLoading(false)
lastNotificationStreamErrorRef.current = null
return
}
if (event.type === 'approval.updated') {
setPendingApprovals(current =>
current.filter(approval => approval.id !== event.approvalRequestId)
)
return
}
if (isSdkNotificationStreamEvent(event)) {
const { notification } = event
const text = notification.body.trim() || notification.title.trim()
const deliveryContext = { activeChatVisible: false }
const deliverInApp = canDeliverChatResponseNotification('inApp', deliveryContext)
const deliverOnDesktop = canDeliverChatResponseNotification('desktop', deliveryContext)
if (deliverInApp) {
pushNotification({
kind: 'sdk_notification',
agentName: notification.recipeName,
text,
timestamp: Date.now(),
dedupeKey: `plugin_workload_sdk.notification:${notification.notificationId}`,
sdk: {
deliveryId: event.id,
notificationId: notification.notificationId,
recipeNamespace: notification.recipeNamespace,
recipeName: notification.recipeName,
callerRef: notification.callerRef,
eventType: notification.eventType,
title: notification.title,
body: notification.body,
},
})
}
// Confirm desktop receipt to the server first, independent of the local
// OS-notification decision below: the delivery is acknowledged because
// the desktop received it. In-app and native channel preferences only
// control local presentation. Keeping the ack ahead of (and decoupled
// from) showDesktopNotification ensures a display gate or native failure
// can never suppress the receipt acknowledgement.
void window.clerum.notifications.ack(event.id).catch(error => {
console.warn('[useNotificationsController] sdk notification ack failed', error)
})
if (deliverOnDesktop) {
void showDesktopNotification({
title: notification.title || notification.recipeName,
body: notification.body || text,
tag: `sdk-notification:${notification.notificationId}`,
silent: true,
}).then(permission => {
if (!deliverInApp && permission === 'granted') {
playNotificationSound()
}
})
}
lastNotificationStreamErrorRef.current = null
return
}
if (isWorkflowRunCompletedStreamEvent(event)) {
const { workflowRun } = event
pushNotification({
kind: 'workflow_completed',
agentName: 'Workflows',
text: workflowCompletionText(workflowRun),
timestamp: workflowCompletionTimestamp(workflowRun),
teamId: workflowRun.target.teamId ?? undefined,
teamName: workflowRun.target.teamName ?? undefined,
dedupeKey:
'workflow.run.completed:' + workflowRun.workflowRunId + ':' + workflowRun.phase,
workflow: {
namespace: workflowRun.recipeNamespace,
name: workflowRun.recipeName,
runId: workflowRun.workflowRunId,
approvalRequestId: workflowRun.approvalRequestId,
phase: workflowRun.phase,
completedAt: workflowRun.completedAt,
},
})
setPendingApprovals(current =>
current.filter(approval => approval.id !== workflowRun.approvalRequestId)
)
lastNotificationStreamErrorRef.current = null
return
}
if (event.type === 'stream.closing') {
setStatus('Notification stream is reconnecting.', 'info', undefined, {
global: false,
toast: false,
})
return
}
if (event.type === 'error') {
const message = `Notification stream degraded: ${event.message}`
if (lastNotificationStreamErrorRef.current !== message) {
lastNotificationStreamErrorRef.current = message
setStatus(message, 'error', undefined, { global: false, toast: true })
}
}
}
window.clerum.notifications
.subscribe(handleStreamEvent)
.then(stop => {
if (disposed) {
void stop()
return
}
unsubscribe = stop
})
.catch(error => {
if (disposed) return
setPendingApprovalsLoading(false)
const message = `Notification stream unavailable: ${
error instanceof Error ? error.message : String(error)
}`
lastNotificationStreamErrorRef.current = message
setStatus(message, 'error', undefined, { global: false, toast: true })
})
return () => {
disposed = true
setPendingApprovalsLoading(false)
if (unsubscribe) void unsubscribe()
}
}, [
canDeliverChatResponseNotification,
isAuthenticated,
playNotificationSound,
pushNotification,
setStatus,
showDesktopNotification,
])
const handleDecidePendingApproval = useCallback(
async (approvalId: string, decision: 'approve' | 'deny') => {
const approval = pendingApprovals.find(item => item.id === approvalId) ?? null
try {
setPendingApprovalActionId(approvalId)
const result = await window.clerum.approvals.decide(approvalId, decision, undefined, {
teamId: approval?.target.teamId,
})
setPendingApprovals(current => current.filter(item => item.id !== approvalId))
if (approval) {
void Promise.resolve(onWorkflowApprovalDecision?.({ approval, decision, result })).catch(
error => {
console.warn(
'[useNotificationsController] workflow approval decision refresh failed',
error
)
}
)
}
setStatus(
decision === 'approve' && result.run
? 'Approval accepted. Workflow run queued.'
: decision === 'approve'
? 'Approval accepted.'
: 'Approval denied.',
'success',
undefined,
{ global: false, toast: true }
)
void handleRefreshPendingApprovals({ silent: true })
} catch (error) {
setStatus(
`Approval action failed: ${error instanceof Error ? error.message : String(error)}`,
'error'
)
} finally {
setPendingApprovalActionId(null)
}
},
[handleRefreshPendingApprovals, onWorkflowApprovalDecision, pendingApprovals, setStatus]
)
const resetNotifications = useCallback(() => {
setNotifications([])
setNotificationActionById({})
setPendingApprovals([])
setPendingApprovalsLoading(false)
setPendingApprovalActionId(null)
}, [])
return {
notifications,
notificationActionById,
pendingApprovals,
pendingApprovalsLoading,
pendingApprovalActionId,
unreadNotificationCount,
setPendingApprovals,
pushNotification,
markNotificationsRead,
markNotificationRead,
clearNotifications,
removeNotification,
resolveApprovalNotification,
handleApproveNotification,
handleDenyNotification,
handleRefreshPendingApprovals,
handleDecidePendingApproval,
playNotificationSound,
resetNotifications,
}
}