The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
import { atom } from 'nanostores'
import { translateNow } from '@/i18n'
import { isOutOfSyncRpcParams } from '@/lib/gateway-rpc'
import { isTimeoutError } from '@/lib/with-timeout'
import { type ErrorToastCategory, recordFriction } from '@/store/desktop-metrics'
import { requestBackendRestart, requestRoute } from '@/store/recovery-requests'
export type NotificationKind = 'error' | 'warning' | 'info' | 'success'
export interface NotificationAction {
label: string
onClick: () => void
}
export type NotificationPlacement = 'default' | 'bottom-right'
export interface AppNotification {
id: string
kind: NotificationKind
/** When set, renders this codicon instead of the default kind icon. */
icon?: string
/** When set, tints the icon and message with this CSS color (severity ramp). */
accentColor?: string
/** Secondary detail line rendered below the message, muted (e.g. "$220.00 cap"). */
meta?: string
title?: string
message: string
detail?: string
action?: NotificationAction
/** Second, quieter button beside `action` (e.g. "Disable" next to "Sign in"). */
secondaryAction?: NotificationAction
onDismiss?: () => void
createdAt: number
placement?: NotificationPlacement
/** Survives clearNotifications: a standing offer, not feedback on the last turn. */
persistent?: boolean
}
export interface NotificationInput {
id?: string
kind?: NotificationKind
icon?: string
accentColor?: string
meta?: string
title?: string
message: string
detail?: string
action?: NotificationAction
secondaryAction?: NotificationAction
onDismiss?: () => void
durationMs?: number
placement?: NotificationPlacement
persistent?: boolean
}
let notificationCounter = 0
const timers = new Map<string, number>()
export const $notifications = atom<AppNotification[]>([])
function defaultDuration(kind: NotificationKind) {
if (kind === 'error' || kind === 'warning') {
return 0
}
return 5_000
}
// Only interruptions worth a top-center toast: errors, warnings, and anything
// with an action button the user needs to notice and click (restart gateway,
// update available, sign-in prompts). Everything else — the bulk of routine
// "saved"/"enabled"/"archived" confirmations across settings, MCP, cron,
// profiles, messaging — is ambient feedback and defaults to a quiet
// bottom-right toast instead. Callers can still force `placement: 'default'`
// for a specific case.
function defaultPlacement(kind: NotificationKind, action?: NotificationAction): NotificationPlacement {
if (kind === 'error' || kind === 'warning' || action) {
return 'default'
}
return 'bottom-right'
}
function cleanErrorText(value: string) {
return value.replace(/^Error:\s*/, '').trim()
}
/** True when an error string is a disk-full / ENOSPC / SQLITE_FULL failure. */
export function isDiskFullErrorMessage(message: string): boolean {
return (
/no space left on device/i.test(message) ||
/not enough space/i.test(message) ||
/database or disk is full/i.test(message) ||
/\bENOSPC\b/i.test(message) ||
/disk full/i.test(message) ||
/full disk/i.test(message)
)
}
/** Settings deep links the summariser can attach to a toast. */
const KEYS_ROUTE = (envKey: string) => `/settings?tab=keys&key=${encodeURIComponent(envKey)}`
const GATEWAY_SETTINGS_ROUTE = '/settings?tab=gateway'
const MAINTENANCE_ROUTE = '/command-center?section=maintenance'
/** One-click recoveries reused by several rules. */
export const RECOVERY_ACTIONS = {
openUpdates: (): NotificationAction => ({
label: translateNow('notifications.updateHermes'),
onClick: () => void import('@/store/updates').then(({ openUpdatesWindow }) => openUpdatesWindow())
}),
restartHermes: (): NotificationAction => ({
label: translateNow('notifications.actions.restartHermes'),
onClick: requestBackendRestart
}),
openKeys: (envKey: string): NotificationAction => ({
label: translateNow('notifications.actions.openKeys'),
onClick: () => requestRoute(KEYS_ROUTE(envKey))
}),
openGateways: (): NotificationAction => ({
label: translateNow('notifications.actions.openGateways'),
onClick: () => requestRoute(GATEWAY_SETTINGS_ROUTE)
}),
openMaintenance: (): NotificationAction => ({
label: translateNow('notifications.actions.openMaintenance'),
onClick: () => requestRoute(MAINTENANCE_ROUTE)
})
}
/** Structured storage failure codes the backend puts in RPC/HTTP error data
* (`hermes_state_errors.classify_persistence_error`). */
const STORAGE_CODE_RE = /['"]code['"]\s*:\s*['"](storage_[a-z_]+|disk_full)['"]/i
interface ErrorSummaryRule {
/** The toast's error category for friction telemetry (a closed code-defined set, never the text). */
category: ErrorToastCategory
test: (msg: string) => boolean
summarize: (msg: string) => string
/** Recovery button attached to the toast when this rule matches. */
action?: (msg: string) => NotificationAction
}
const ERROR_SUMMARIES: ErrorSummaryRule[] = [
{
// Disk full / ENOSPC — session DB write, backend crash, or any path that
// bubbles "no space left" / SQLITE_FULL through notifyError. Match before
// generic length truncation so the user gets a clear "free space" toast
// instead of a silent send or a raw errno dump.
category: 'disk_full',
test: isDiskFullErrorMessage,
summarize: () => translateNow('notifications.errors.diskFull'),
action: () => RECOVERY_ACTIONS.openMaintenance()
},
{
// Any other classified storage failure (locked, corrupt, read-only …):
// the Maintenance panel runs the doctor that names the fix.
category: 'storage_failure',
test: msg => STORAGE_CODE_RE.test(msg),
summarize: () => translateNow('notifications.errors.storageFailure'),
action: () => RECOVERY_ACTIONS.openMaintenance()
},
{
category: 'gateway_auth_failed',
test: msg => /['"]code['"]\s*:\s*['"]gateway_auth_failed['"]/i.test(msg),
summarize: () => translateNow('notifications.errors.gatewayAuthFailed'),
action: () => RECOVERY_ACTIONS.openGateways()
},
{
category: 'api_key_rejected',
test: msg => /incorrect api key provided/i.test(msg) || /['"]code['"]\s*:\s*['"]invalid_api_key['"]/i.test(msg),
summarize: () => translateNow('notifications.errors.openaiRejectedApiKey'),
action: () => RECOVERY_ACTIONS.openKeys('OPENAI_API_KEY')
},
{
category: 'api_key_missing',
test: msg => /neither voice_tools_openai_key nor openai_api_key is set/i.test(msg),
summarize: () => translateNow('notifications.errors.openaiTtsNeedsKey'),
action: () => RECOVERY_ACTIONS.openKeys('OPENAI_API_KEY')
},
{
category: 'api_key_missing',
test: msg => /ELEVENLABS_API_KEY not set/i.test(msg),
summarize: () => translateNow('notifications.errors.elevenLabsNeedsKey'),
action: () => RECOVERY_ACTIONS.openKeys('ELEVENLABS_API_KEY')
},
{
category: 'api_key_rejected',
test: msg => /ElevenLabs STT API error \(HTTP 401\)/i.test(msg),
summarize: () => translateNow('notifications.errors.elevenLabsRejectedKey'),
action: () => RECOVERY_ACTIONS.openKeys('ELEVENLABS_API_KEY')
},
{
category: 'method_not_allowed',
test: msg => /method not allowed/i.test(msg),
summarize: () => translateNow('notifications.errors.methodNotAllowed'),
action: () => RECOVERY_ACTIONS.restartHermes()
},
{
category: 'microphone_permission',
test: msg => /microphone permission/i.test(msg),
summarize: () => translateNow('notifications.errors.microphonePermission')
},
{
category: 'rpc_out_of_sync',
test: msg => isOutOfSyncRpcParams(msg),
summarize: () => translateNow('notifications.errors.rpcOutOfSync'),
action: () => RECOVERY_ACTIONS.openUpdates()
},
{
category: 'restart_required',
test: msg => /Restart required:/i.test(msg),
summarize: () => translateNow('notifications.errors.codeSkewRestartRequired'),
action: () => RECOVERY_ACTIONS.restartHermes()
}
]
function summarizeErrorMessage(message: string, fallback: string) {
const rule = ERROR_SUMMARIES.find(r => r.test(message))
if (rule) {
return { action: rule.action?.(message), category: rule.category, message: rule.summarize(message) }
}
return {
action: undefined,
category: 'unclassified' as const,
message: message.length > 180 ? fallback : message || fallback
}
}
// The owner's refusal of an edit, restore or regenerate whose target is not a live user turn
// (hermes_state_mutations._rewind): invalid_params on target_message_id. Its detail starts with
// `compacted:` only when compaction summarized the turn; a turn another window already undid, an
// assistant row or an unknown id is stale for another reason. Every other invalid_params keeps the
// generic toast.
function staleRewindRefusal(error: unknown): 'compacted' | 'stale' | null {
const data = error && typeof error === 'object' ? (error as { data?: unknown }).data : undefined
if (!data || typeof data !== 'object') {
return null
}
const { detail, field, reason } = data as { detail?: unknown; field?: unknown; reason?: unknown }
if (reason !== 'invalid_params' || field !== 'target_message_id') {
return null
}
return typeof detail === 'string' && detail.startsWith('compacted:') ? 'compacted' : 'stale'
}
// The owner refuses every model pick and turn on a chat whose launch API key changed or was removed
// (gateway/session_policy_credentials.py): `data.reason` on an RPC error, or the bare code a deferred
// pick's refusal event carries.
function isLaunchCredentialsRefusal(error: unknown): boolean {
const data = error && typeof error === 'object' ? (error as { data?: { reason?: unknown } }).data : undefined
if (data && typeof data === 'object' && data.reason === 'launch_credentials_unavailable') {
return true
}
return error instanceof Error && error.message.trim() === 'launch_credentials_unavailable'
}
// Exported so flows that surface errors inline (e.g. ConfirmDialog's onConfirm
// rethrow) can reuse the same IPC-unwrapping + summarizing as notifyError.
export function readableError(
error: unknown,
fallback: string
): { message: string; detail?: string; action?: NotificationAction; category: ErrorToastCategory } {
const staleRewind = staleRewindRefusal(error)
if (staleRewind) {
const key = staleRewind === 'compacted' ? 'compactedTurnUnavailable' : 'staleTurnUnavailable'
return { message: translateNow(`promptNotices.${key}`), category: 'other' }
}
if (isLaunchCredentialsRefusal(error)) {
// Same sentence and button as the chat's error card: a model pick, retry or option change on
// this chat repeats the refusal until the user starts a new one.
return {
message: translateNow('assistant.thread.errorCodes.launch_credentials_unavailable.body'),
action: {
label: translateNow('assistant.thread.errorStartNewSession'),
onClick: () => void import('@/store/profile').then(({ requestFreshSession }) => requestFreshSession())
},
category: 'other'
}
}
const raw = error instanceof Error ? error.message : typeof error === 'string' ? error : fallback
const unwrapped = raw.match(/Error invoking remote method '[^']+': Error: (.+)$/)?.[1] ?? raw
const cleaned = cleanErrorText(unwrapped)
const detail = cleaned.match(/"detail"\s*:\s*"([^"]+)"/)?.[1] ?? cleaned
const summary = summarizeErrorMessage(detail, fallback)
return {
message: summary.message,
detail: detail === summary.message ? undefined : detail,
action: summary.action,
category: summary.category
}
}
export function notify(input: NotificationInput): string {
return showNotification(input, input.kind === 'error' ? 'other' : null)
}
function showNotification(input: NotificationInput, errorCategory: ErrorToastCategory | null): string {
const kind = input.kind ?? 'info'
if (errorCategory) {
recordFriction('error_toast', errorCategory)
}
const id = input.id ?? `${Date.now()}-${notificationCounter++}`
const notification: AppNotification = {
id,
kind,
icon: input.icon,
accentColor: input.accentColor,
meta: input.meta,
title: input.title,
message: input.message,
detail: input.detail,
action: input.action,
secondaryAction: input.secondaryAction,
onDismiss: input.onDismiss,
createdAt: Date.now(),
placement: input.placement ?? defaultPlacement(kind, input.action),
persistent: input.persistent
}
window.clearTimeout(timers.get(id))
timers.delete(id)
// Visual depth is capped by CardStack, not by discarding queued notifications.
$notifications.set([notification, ...$notifications.get().filter(item => item.id !== id)])
const duration = input.durationMs ?? defaultDuration(kind)
if (duration > 0) {
timers.set(
id,
window.setTimeout(() => dismissNotification(id), duration)
)
}
return id
}
// Toast copy can omit the stack or shorten the message. Keep both in desktop.log.
function logErrorToDesktopLog(error: unknown, fallback: string): void {
try {
const label: string = new URLSearchParams(window.location.search).get('win') ?? 'main'
const raw: string =
error instanceof Error ? (error.stack ?? error.message) : typeof error === 'string' ? error : fallback
window.hermesDesktop?.logLine?.(`[renderer error:${label}] ${fallback}: ${raw}`)
} catch {
// A missing or closed IPC bridge must not prevent the error toast.
}
}
export function notifyError(
error: unknown,
fallback: string,
options: { action?: NotificationAction; id?: string } = {}
): string {
const readable = readableError(error, fallback)
logErrorToDesktopLog(error, fallback)
const category: ErrorToastCategory =
readable.category === 'unclassified' && isTimeoutError(error) ? 'timeout' : readable.category
return showNotification(
{
action: options.action ?? readable.action,
// A caller that can fire again for the same cause names its toast, so the repeat replaces it.
id: options.id,
kind: 'error',
title: fallback,
message: readable.message,
detail: readable.detail
},
category
)
}
export function dismissNotification(id: string) {
window.clearTimeout(timers.get(id))
timers.delete(id)
const dismissed = $notifications.get().find(item => item.id === id)
$notifications.set($notifications.get().filter(item => item.id !== id))
dismissed?.onDismiss?.()
}
export function clearNotifications() {
const all = $notifications.get()
const cleared = all.filter(item => !item.persistent)
$notifications.set(all.filter(item => item.persistent))
for (const item of cleared) {
window.clearTimeout(timers.get(item.id))
timers.delete(item.id)
item.onDismiss?.()
}
}