AgentHub/client/src/hooks/useNotifications.ts

/**
 * @file useNotifications.ts
 * @description Defines a custom React hook for managing browser notifications in the agent dashboard application. The hook subscribes to the event bus to listen for specific events such as new sessions, session errors, session completions, and subagent spawns. Based on user preferences stored in localStorage, it triggers browser notifications to keep users informed of important updates without needing to actively monitor the dashboard. The hook should be called once at the root level of the application to ensure notifications are handled globally.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */
/* =============================================================================
 * MODULE_GUIDE — extended in-file reference (comments only; safe to read, never executed)
 * =============================================================================
 * **Purpose:** React hook: isolates side effects and subscription wiring so presentational components stay declarative.
 *
 * ## Design constraints
 * - Local-first: no telemetry leaves the machine unless the user configures webhooks.
 * - Fail-safe hooks path on the server must never block Claude Code; UI mirrors that
 *   philosophy by degrading gracefully (empty states, stale badges, reconnect loops).
 * - Destructive flows stay behind explicit confirmation modals and server-side gates.
 * - Internationalization: user-visible strings belong in i18n JSON, not literals here.
 *
 * ## Remote data & SSH
 * Remote Data Sources let operators aggregate multiple machines. SSH entries describe
 * how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
 * scoped GET via `?sources=`. Health checks and import history surface in Settings.
 *
 * ## Internal dependencies
 * - `../i18n`
 * - `../lib/eventBus`
 * - `../lib/push`
 * - `../lib/notify`
 * - `../lib/types`
 *
 * ## Public surface
 * - `useNotifications` — exported API; see TSDoc on the symbol for behavior.
 *
 * ## Testing pointers
 * - Prefer colocated `__tests__` with Vitest + Testing Library for UI.
 * - Server contract changes require `npm run test:server` and OpenAPI sync.
 *
 * ## Related docs
 * - `ARCHITECTURE.md` — hooks → API → SQLite → WebSocket → UI pipeline.
 * - `docs/API.md` — REST reference.
 * - `skills/file-headers/` — mandatory `@author` header policy.
 * ============================================================================= */
/* -----------------------------------------------------------------------------
 * EXPORT CATALOG — quick index of symbols defined below (documentation only).
 * -----------------------------------------------------------------------------
 * **useNotifications**
 *   Part of this module's public contract. Downstream imports should treat
 *   the signature and return type as stable unless release notes say otherwise.
 *   When behavior changes, update the `@file` overview and relevant tests.
 *
 * ----------------------------------------------------------------------------- */

import { useEffect, useRef } from "react";
import i18n from "../i18n";
import { api } from "../lib/api";
import { eventBus } from "../lib/eventBus";
import { subscribeToPush } from "../lib/push";
import { notify, playSound } from "../lib/notify";
import { loadNotifPrefs, soundFor, type NotifType } from "../lib/notifPrefs";
import type { WSMessage, Session, Agent, DashboardEvent, Lane } from "../lib/types";

/**
 * Wires the dashboard's {@link eventBus} up to browser notifications, per the
 * user's saved {@link NotifPrefs}. Mount once at the app root (it has no
 * return value and no props) - it re-reads preferences from `localStorage` on
 * every incoming message, so toggling a Settings checkbox takes effect
 * immediately without remounting. Also opportunistically (re-)subscribes to
 * Web Push on mount when notifications are enabled and permission has
 * already been granted, so push delivery survives a page reload.
 */
export function useNotifications() {
  // A lane's `session_id` is its current/last-run session — matching on it
  // is how a click lands on the lane that actually raised the notification,
  // instead of just focusing whichever browser tab was already open.
  const lanesRef = useRef<Lane[]>([]);

  useEffect(() => {
    const prefs = loadNotifPrefs();
    if (prefs.enabled && "Notification" in window && Notification.permission === "granted") {
      subscribeToPush().catch(() => {});
    }

    api.lanes
      .list()
      .then((r) => (lanesRef.current = r.lanes))
      .catch(() => {});

    // Straight into the pane that holds the session (any slot, from the
    // hooks' `run_id` binding) — the agent waiting on the user is there, not
    // on the workspace's home; the home when no pane holds it.
    async function laneUrlForSession(sessionId: string): Promise<string | undefined> {
      const runs = await api.run
        .list()
        .then((r) => r.items ?? [])
        .catch(() => []);
      const run = runs.find((r) => r.sessionId === sessionId && r.status === "running");
      if (run && run.laneId !== null) {
        return `/workspace?lane=${run.laneId}&run=${encodeURIComponent(run.id)}`;
      }
      const lane = (lanesRef.current ?? []).find((l) => l.session_id === sessionId);
      return lane ? `/workspace?lane=${lane.id}` : undefined;
    }

    return eventBus.subscribe((msg: WSMessage) => {
      if (msg.type === "lane_update") {
        const payload = msg.data as { lane?: Lane; removed?: number };
        if (payload.lane) {
          const i = lanesRef.current.findIndex((l) => l.id === payload.lane!.id);
          if (i === -1) lanesRef.current = [...lanesRef.current, payload.lane];
          else lanesRef.current = lanesRef.current.map((l, idx) => (idx === i ? payload.lane! : l));
        } else if (payload.removed !== undefined) {
          lanesRef.current = lanesRef.current.filter((l) => l.id !== payload.removed);
        }
        return;
      }

      const prefs = loadNotifPrefs();
      if (!prefs.enabled) return;
      // A notification that was shown (pushed, native or local) plays its
      // type's sound; one that reached nobody plays nothing.
      const show = (
        type: NotifType,
        title: string,
        body: string,
        // A thunk: the pane lookup (GET /api/run) runs only for a
        // notification that is actually shown, never per incoming event.
        url?: () => Promise<string | undefined>
      ) =>
        void Promise.resolve(url?.())
          .then((u) => notify(title, body, u))
          .then((r) => {
            if (r.via === "native" || r.via === "push" || r.via === "local")
              playSound(soundFor(prefs, type));
          });

      switch (msg.type) {
        case "session_created": {
          if (!prefs.onNewSession) return;
          const s = msg.data as Session;
          show(
            "onNewSession",
            i18n.t("errors:notifications.newSession"),
            s.name || `${i18n.t("errors:notifications.sessionDefault")}${s.id.slice(0, 8)}`,
            () => laneUrlForSession(s.id)
          );
          break;
        }
        case "session_updated": {
          const s = msg.data as Session;
          if (s.status === "error" && prefs.onSessionError) {
            show(
              "onSessionError",
              i18n.t("errors:notifications.sessionError"),
              s.name || `${i18n.t("errors:notifications.sessionDefault")}${s.id.slice(0, 8)}`,
              () => laneUrlForSession(s.id)
            );
          }
          break;
        }
        case "agent_created": {
          if (!prefs.onSubagentSpawn) return;
          const a = msg.data as Agent;
          if (a.type === "subagent") {
            show("onSubagentSpawn", i18n.t("errors:notifications.subagentSpawned"), a.name, () =>
              laneUrlForSession(a.session_id)
            );
          }
          break;
        }
        case "new_event": {
          const ev = msg.data as DashboardEvent;
          const url = () => laneUrlForSession(ev.session_id);
          // The two states where Claude is BLOCKED on the user get their own
          // flags (issue #29): `Notification` is a permission prompt or a
          // question, `Stop` is the end of a turn. Both used to hang off
          // `onSessionComplete` / nothing at all, so the one thing the user
          // actually waits for was either off by default or unswitchable.
          if (ev.event_type === "Notification" && prefs.onAwaitingInput) {
            show(
              "onAwaitingInput",
              i18n.t("errors:notifications.awaitingInput"),
              ev.summary || i18n.t("errors:notifications.defaultBody"),
              url
            );
          } else if (ev.event_type === "Stop" && prefs.onTurnComplete) {
            show(
              "onTurnComplete",
              i18n.t("errors:notifications.finishedResponding"),
              ev.summary || i18n.t("errors:notifications.readyForInput"),
              url
            );
          } else if (ev.event_type === "SessionEnd" && prefs.onSessionComplete) {
            show(
              "onSessionComplete",
              i18n.t("errors:notifications.sessionCompleted"),
              ev.summary || i18n.t("errors:notifications.sessionClosed"),
              url
            );
          }
          break;
        }
      }
    });
  }, []);
}