Skip to content

The agent that grows with you

14.1 KB
Raw Blame
import { atom } from 'nanostores'

import { translateNow } from '@/i18n'
import { type HermesOpenTarget, resolveHermesOpenPath } from '@/lib/hermes-open-target'
import { persistString, storedString } from '@/lib/storage'

import { recordFeatureToggle } from './desktop-metrics'
import { $gateway } from './gateway'
import { $hapticsMuted } from './haptics'
import { withinNativeNotifyBaseline } from './notify-baseline'
import {
  answerApproval,
  clearApprovalRequest,
  replayPendingApproval,
  sessionApprovalRequest,
  sessionApprovalRequests
} from './prompts'
import { isSessionGone, isSessionGoneForBackgroundPolling, markSessionGone } from './runtime-gone'
import { $activeSessionId, ownerLookupSessionRows, sessionMatchesStoredId } from './session'
import { storedSessionIdForRuntimeId } from './session-states'

export type { HermesOpenTarget }

// Native OS notifications (Electron `Notification`), separate from the in-app
// toast feed in `notifications.ts`. Each kind toggles independently.
export type NativeNotificationKind =
  'approval' | 'backgroundDone' | 'credits' | 'input' | 'plugin' | 'turnDone' | 'turnError'

export const NATIVE_NOTIFICATION_KINDS: readonly NativeNotificationKind[] = [
  'approval',
  'input',
  'turnDone',
  'turnError',
  'backgroundDone',
  'credits',
  'plugin'
]

// Blocking prompts — surface even while focused if they're for another session.
const ATTENTION_KINDS = new Set<NativeNotificationKind>(['approval', 'input'])

export interface NativeNotificationPrefs {
  enabled: boolean
  kinds: Record<NativeNotificationKind, boolean>
}

const STORAGE_KEY = 'hermes:native-notifications'

const DEFAULT_PREFS: NativeNotificationPrefs = {
  enabled: true,
  kinds: {
    approval: true,
    backgroundDone: true,
    credits: true,
    input: true,
    plugin: true,
    turnDone: true,
    turnError: true
  }
}

function readPrefs(): NativeNotificationPrefs {
  const raw = storedString(STORAGE_KEY)

  if (!raw) {
    return DEFAULT_PREFS
  }

  try {
    const parsed = JSON.parse(raw) as Partial<NativeNotificationPrefs>
    const kinds = { ...DEFAULT_PREFS.kinds }

    for (const kind of NATIVE_NOTIFICATION_KINDS) {
      const value = parsed.kinds?.[kind]

      if (typeof value === 'boolean') {
        kinds[kind] = value
      }
    }

    return {
      enabled: typeof parsed.enabled === 'boolean' ? parsed.enabled : DEFAULT_PREFS.enabled,
      kinds
    }
  } catch {
    return DEFAULT_PREFS
  }
}

export const $nativeNotifyPrefs = atom<NativeNotificationPrefs>(readPrefs())

function writePrefs(next: NativeNotificationPrefs) {
  $nativeNotifyPrefs.set(next)
  persistString(STORAGE_KEY, JSON.stringify(next))
}

export function setNativeNotifyEnabled(enabled: boolean) {
  recordFeatureToggle('native_notifications', $nativeNotifyPrefs.get().enabled, enabled)
  writePrefs({ ...$nativeNotifyPrefs.get(), enabled })
}

export function setNativeNotifyKind(kind: NativeNotificationKind, on: boolean) {
  const prev = $nativeNotifyPrefs.get()
  recordFeatureToggle('notification_kind', prev.kinds[kind], on)
  writePrefs({ ...prev, kinds: { ...prev.kinds, [kind]: on } })
}

// De-dupe replayed events for the same kind+session. Self-evicting: entries
// older than the window are pruned on every dispatch, so the map can't grow.
const THROTTLE_MS = 1000
const lastFiredAt = new Map<string, number>()

function throttled(key: string, now: number): boolean {
  for (const [k, at] of lastFiredAt) {
    if (now - at >= THROTTLE_MS) {
      lastFiredAt.delete(k)
    }
  }

  if (lastFiredAt.has(key)) {
    return true
  }

  lastFiredAt.set(key, now)

  return false
}

// "Backgrounded" = the user isn't on Hermes. `document.hidden` only flips when
// minimized/occluded; an alt-tabbed window is visible-but-unfocused, so we also
// check `document.hasFocus()`.
function isBackgrounded(): boolean {
  if (typeof document === 'undefined') {
    return false
  }

  if (document.hidden) {
    return true
  }

  return typeof document.hasFocus === 'function' && !document.hasFocus()
}

function shouldFire(kind: NativeNotificationKind, sessionId?: null | string, global = false): boolean {
  // Global notifications aren't tied to a chat session (e.g. pet generation,
  // which runs from the command center with no active conversation). They fire
  // whenever the user is away, with no session-match requirement — otherwise a
  // background run started without an open session would be silently dropped.
  if (global) {
    return isBackgrounded()
  }

  // Attention kinds break through for an off-screen session even while focused.
  if (ATTENTION_KINDS.has(kind)) {
    return isBackgrounded() || (Boolean(sessionId) && sessionId !== $activeSessionId.get())
  }

  // Completion kinds: only the active session, only while away — so a busy
  // gateway (messaging, kanban, cron) can't spam a toast per background session.
  return isBackgrounded() && Boolean(sessionId) && sessionId === $activeSessionId.get()
}

/** Last-resort label for a session the renderer has no row for (yet): the id
 *  tail still tells three parked approvals apart. */
const shortSessionId = (id: string) => `#${id.slice(-6)}`

/** Blocking prompts name their session in the title ("Approval needed — Fix the
 *  flaky test") so parallel parked approvals stay tellable apart; the caller's
 *  `title` stays the bare fallback for a prompt with no session. */
const NAMED_TITLE_KEYS: Partial<Record<NativeNotificationKind, string>> = {
  approval: 'notifications.native.approvalTitleNamed',
  input: 'notifications.native.inputTitleNamed'
}

/** Sidebar naming order (title → preview → short id) via the locale's
 *  named-title template; the runtime id the caller already passes is the whole
 *  hint needed. */
function withSessionLabel(namedKey: string, runtimeSessionId: string): string {
  const storedId = storedSessionIdForRuntimeId(runtimeSessionId) ?? runtimeSessionId
  const row = ownerLookupSessionRows().find(session => sessionMatchesStoredId(session, storedId))
  const name = row?.title?.trim() || row?.preview?.trim() || shortSessionId(storedId)

  return translateNow(namedKey, name.length > 80 ? `${name.slice(0, 80).trimEnd()}…` : name)
}

export interface NativeNotificationAction {
  id: string
  text: string
  /** Serializable activate target echoed back on button press (plugin path). */
  activate?: string
}

export interface NativeNotificationInput {
  kind: NativeNotificationKind
  title: string
  body?: string
  sessionId?: null | string
  /**
   * Not tied to a chat session (e.g. pet generation). Fires whenever the user
   * is away, bypassing the session-match gate that completion kinds normally
   * require.
   */
  global?: boolean
  silent?: boolean
  actions?: NativeNotificationAction[]
  /**
   * Extra throttle/dedupe discriminator for session-less notifications (e.g.
   * the plugin id), so unrelated emitters of the same kind don't collapse
   * into one another. Never drives click-to-focus like `sessionId` does.
   */
  tag?: string
  /** Absolute file path for the OS notification icon (Electron). */
  icon?: string
  /**
   * Resolved hash-router path to open on body click when there is no
   * `sessionId` (plugins). Same vocabulary as `hermes://index-network/intent/1`.
   */
  activate?: string
  /** Renderer-side handle so click/action can invoke registered callbacks. */
  notifyId?: string
}

/** Returns true when the notification passed every guard and was handed to the
 *  OS bridge — callers registering per-notification state (plugin handlers)
 *  must only do so on true, or suppressed/throttled notifications leak it. */
export function dispatchNativeNotification(input: NativeNotificationInput): boolean {
  const prefs = $nativeNotifyPrefs.get()

  if (!prefs.enabled || !prefs.kinds[input.kind]) {
    return false
  }

  if (withinNativeNotifyBaseline()) {
    return false
  }

  if (!shouldFire(input.kind, input.sessionId, input.global)) {
    return false
  }

  if (throttled(`${input.kind}:${input.sessionId ?? input.tag ?? (input.global ? 'global' : '')}`, Date.now())) {
    return false
  }

  const namedKey = input.sessionId ? NAMED_TITLE_KEYS[input.kind] : undefined
  const title = namedKey && input.sessionId ? withSessionLabel(namedKey, input.sessionId) : input.title

  void window.hermesDesktop?.notify({
    actions: input.actions,
    activate: input.activate,
    body: input.body,
    focusSessionId: input.sessionId ? (storedSessionIdForRuntimeId(input.sessionId) ?? undefined) : undefined,
    icon: input.icon,
    kind: input.kind,
    notifyId: input.notifyId,
    sessionId: input.sessionId ?? undefined,
    // The app-sounds mute also silences OS notification sounds.
    silent: $hapticsMuted.get() || input.silent,
    tag: input.tag,
    title
  })

  return true
}

// -- the plugin door (`ctx.os.notify`) ----------------------------------------

export interface PluginNotificationAction {
  id: string
  label: string
  /** Navigate here on button press (path or `hermes://index-network/intent/1`). */
  activate?: HermesOpenTarget
  /** Renderer callback — only `id` crosses IPC; this stays in-process. */
  onAction?: () => void
}

export interface PluginNativeNotificationInput {
  title: string
  body?: string
  silent?: boolean
  /** Absolute filesystem path for the notification icon. */
  icon?: string
  /**
   * Where body-click should land. Accepts a plugin deep link
   * (`hermes://index-network/intent/1`), a hash path (`/index-network/intent/1`),
   * or `{ path, params }` — all resolve through the same helper as OS deep links.
   */
  activate?: HermesOpenTarget
  /** Extra work on body click (runs in addition to `activate` navigation). */
  onActivate?: () => void
  actions?: PluginNotificationAction[]
}

interface PendingPluginNotify {
  onActivate?: () => void
  actions: Map<string, () => void>
}

const pendingPluginNotify = new Map<string, PendingPluginNotify>()

function mintNotifyId(pluginId: string): string {
  return `${pluginId}:${Date.now().toString(36)}:${Math.random().toString(36).slice(2, 8)}`
}

/** Invoke body-click callback if one was registered for this notify id. */
export function invokePluginNotifyActivate(notifyId: string | undefined): void {
  if (!notifyId) {
    return
  }

  const pending = pendingPluginNotify.get(notifyId)
  pending?.onActivate?.()
}

/** Invoke an action-button callback. Returns true when a handler ran. */
export function invokePluginNotifyAction(notifyId: string | undefined, actionId: string | undefined): boolean {
  if (!notifyId || !actionId) {
    return false
  }

  const handler = pendingPluginNotify.get(notifyId)?.actions.get(actionId)

  if (!handler) {
    return false
  }

  handler()

  return true
}

/** Drop pending handlers (tests / after a click consumed the toast). */
export function clearPluginNotifyHandlers(notifyId?: string): void {
  if (notifyId) {
    pendingPluginNotify.delete(notifyId)

    return
  }

  pendingPluginNotify.clear()
}

/** Native OS notification on behalf of a plugin. One "Plugin notifications"
 *  preference gates all plugins; the plugin id keys throttling/dedupe so two
 *  plugins can't collapse each other's notifications. Fires only while the
 *  user is away from Hermes — the in-app toast (`host.notify`) covers the
 *  foreground case. */
export function dispatchPluginNativeNotification(pluginId: string, input: PluginNativeNotificationInput): void {
  const activate = resolveHermesOpenPath(input.activate) ?? undefined
  const notifyId = input.onActivate || input.actions?.some(a => a.onAction) ? mintNotifyId(pluginId) : undefined

  const actions: NativeNotificationAction[] | undefined = input.actions?.map(action => ({
    activate: resolveHermesOpenPath(action.activate) ?? undefined,
    id: action.id,
    text: action.label
  }))

  const fired = dispatchNativeNotification({
    actions,
    activate,
    body: input.body,
    global: true,
    icon: input.icon,
    kind: 'plugin',
    notifyId,
    // The app-sounds mute also silences OS notification sounds.
    silent: $hapticsMuted.get() || input.silent,
    tag: pluginId,
    title: input.title
  })

  // Register renderer callbacks only for notifications that actually reached
  // the OS — a throttled/suppressed one can never be clicked, so registering
  // first would leak the closures for the window's lifetime.
  if (fired && notifyId) {
    const handlers = new Map<string, () => void>()

    for (const action of input.actions ?? []) {
      if (action.onAction) {
        handlers.set(action.id, action.onAction)
      }
    }

    pendingPluginNotify.set(notifyId, { actions: handlers, onActivate: input.onActivate })
  }
}

// Resolve a pending approval from a notification button, mirroring the in-app
// Run/Reject bar. Keyed by session id — a background approval has no local guard.
export async function respondToApprovalAction(sessionId: null | string, actionId: string): Promise<void> {
  const [action, ...idParts] = actionId.split(':')
  const requestId = idParts.length ? idParts.join(':') : sessionApprovalRequest(sessionId).get()?.requestId
  const choice = action === 'approve' ? 'once' : action === 'reject' ? 'deny' : null

  if (!choice) {
    return
  }

  if (sessionId && isSessionGone(sessionId)) {
    return
  }

  const gateway = $gateway.get()

  if (!gateway) {
    return
  }

  try {
    const parked = sessionApprovalRequests(sessionId)
      .get()
      .find(request => request.requestId === requestId)

    await answerApproval(gateway, parked ?? { sessionId, requestId }, choice)

    if (requestId || sessionApprovalRequest(sessionId).get()?.requestId === undefined) {
      clearApprovalRequest(sessionId, requestId)
    }

    void replayPendingApproval(gateway, sessionId).catch(() => undefined)
  } catch (error) {
    if (sessionId && isSessionGoneForBackgroundPolling(error)) {
      markSessionGone(sessionId)
    }

    // Leave the prompt parked so the user can still resolve it in-app.
  }
}

// Settings "send test" — bypasses gating. Returns whether the OS accepted it so
// the panel can flag a silent permission failure instead of looking dead.
export async function sendTestNativeNotification(title: string, body: string): Promise<boolean> {
  const bridge = window.hermesDesktop

  if (!bridge?.notify) {
    return false
  }

  try {
    return await bridge.notify({ body, kind: 'turnDone', title })
  } catch {
    return false
  }
}