@a5c-ai/babysitter-observer-dashboard 1.0.0

package/src/hooks/use-keyboard.ts

@@ -0,0 +1,45 @@
+"use client";
+import { useEffect, useRef } from "react";
+
+export interface Shortcut {
+  key: string;
+  ctrl?: boolean;
+  shift?: boolean;
+  action: () => void;
+  description: string;
+}
+
+export function useKeyboard(shortcuts: Shortcut[]) {
+  const shortcutsRef = useRef(shortcuts);
+  shortcutsRef.current = shortcuts;
+
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      // Don't fire in input/textarea/select
+      const target = e.target as HTMLElement;
+      if (
+        target.tagName === "INPUT" ||
+        target.tagName === "TEXTAREA" ||
+        target.tagName === "SELECT" ||
+        target.isContentEditable
+      ) {
+        return;
+      }
+
+      for (const shortcut of shortcutsRef.current) {
+        if (
+          e.key === shortcut.key &&
+          !!e.ctrlKey === !!shortcut.ctrl &&
+          !!e.shiftKey === !!shortcut.shift
+        ) {
+          e.preventDefault();
+          shortcut.action();
+          return;
+        }
+      }
+    };
+
+    window.addEventListener("keydown", handler);
+    return () => window.removeEventListener("keydown", handler);
+  }, []);
+}

package/src/hooks/use-notifications.ts

@@ -0,0 +1,82 @@
+"use client";
+import { useState, useCallback, useRef, useEffect } from "react";
+
+export interface AppNotification {
+  id: string;
+  title: string;
+  body: string;
+  type: "success" | "error" | "warning" | "info";
+  timestamp: number;
+  href?: string;
+  /** When true the notification will not auto-dismiss and must be closed manually or resolved externally. */
+  persistent?: boolean;
+}
+
+export function useNotifications() {
+  const [notifications, setNotifications] = useState<AppNotification[]>([]);
+  const [permission, setPermission] =
+    useState<NotificationPermission>("default");
+  const counterRef = useRef(0);
+
+  useEffect(() => {
+    if (typeof window !== "undefined" && "Notification" in window) {
+      setPermission(Notification.permission);
+    }
+  }, []);
+
+  const requestPermission = useCallback(async () => {
+    if (typeof window === "undefined" || !("Notification" in window)) return;
+    const result = await Notification.requestPermission();
+    setPermission(result);
+  }, []);
+
+  const notify = useCallback(
+    (
+      title: string,
+      body: string,
+      type: AppNotification["type"] = "info",
+      options?: { href?: string; persistent?: boolean },
+    ) => {
+      const id = `notif-${++counterRef.current}-${Date.now()}`;
+
+      // In-app toast
+      const notification: AppNotification = {
+        id,
+        title,
+        body,
+        type,
+        timestamp: Date.now(),
+        href: options?.href,
+        persistent: options?.persistent,
+      };
+      setNotifications((prev) => [...prev, notification]);
+
+      // Auto-dismiss after 5 seconds (skip for persistent notifications like breakpoints)
+      if (!options?.persistent) {
+        setTimeout(() => {
+          setNotifications((prev) => prev.filter((n) => n.id !== id));
+        }, 5000);
+      }
+
+      // Browser notification when tab is hidden
+      if (
+        permission === "granted" &&
+        typeof window !== "undefined" &&
+        document.hidden
+      ) {
+        try {
+          new Notification(title, { body, tag: id });
+        } catch {
+          // Silent fail for environments that don't support Notification constructor
+        }
+      }
+    },
+    [permission],
+  );
+
+  const dismiss = useCallback((id: string) => {
+    setNotifications((prev) => prev.filter((n) => n.id !== id));
+  }, []);
+
+  return { notifications, notify, dismiss, requestPermission, permission };
+}

package/src/hooks/use-persisted-state.ts

@@ -0,0 +1,60 @@
+"use client";
+import { useState, useCallback, useLayoutEffect, useEffect } from "react";
+
+const NAMESPACE = "observer:";
+
+// useLayoutEffect on client (runs before paint → no flash),
+// useEffect on server (suppresses Next.js SSR warning).
+const useIsomorphicLayoutEffect =
+  typeof window !== "undefined" ? useLayoutEffect : useEffect;
+
+/**
+ * Custom hook that wraps useState with localStorage persistence.
+ * Values are serialized with JSON.stringify/parse and namespaced
+ * under the "observer:" prefix to avoid collisions.
+ *
+ * Hydration-safe: first render uses defaultValue (matching SSR),
+ * then useLayoutEffect reads localStorage before the browser paints
+ * so the persisted value appears with no visible flash.
+ */
+export function usePersistedState<T>(
+  key: string,
+  defaultValue: T
+): [T, (value: T | ((prev: T) => T)) => void] {
+  const prefixedKey = key.startsWith(NAMESPACE) ? key : `${NAMESPACE}${key}`;
+
+  // Always start with defaultValue to match SSR output (hydration-safe).
+  const [state, setState] = useState<T>(defaultValue);
+
+  // Read localStorage before paint — avoids both hydration mismatch and flash.
+  useIsomorphicLayoutEffect(() => {
+    try {
+      const stored = window.localStorage.getItem(prefixedKey);
+      if (stored !== null) {
+        const parsed = JSON.parse(stored) as T;
+        setState(parsed);
+      }
+    } catch {
+      // localStorage unavailable — keep default
+    }
+  }, [prefixedKey]);
+
+  const setPersistedState = useCallback(
+    (value: T | ((prev: T) => T)) => {
+      setState((prev) => {
+        const next = typeof value === "function" ? (value as (prev: T) => T)(prev) : value;
+        try {
+          if (typeof window !== "undefined") {
+            window.localStorage.setItem(prefixedKey, JSON.stringify(next));
+          }
+        } catch {
+          // localStorage may be full or blocked — silently ignore
+        }
+        return next;
+      });
+    },
+    [prefixedKey]
+  );
+
+  return [state, setPersistedState];
+}

package/src/hooks/use-polling.ts

@@ -0,0 +1,60 @@
+"use client";
+import { useState, useEffect, useCallback, useRef } from "react";
+import { resilientFetch } from "@/lib/fetcher";
+
+interface UsePollingOptions {
+  interval?: number;
+  enabled?: boolean;
+}
+
+export function usePolling<T>(
+  url: string,
+  options: UsePollingOptions = {}
+): { data: T | null; loading: boolean; error: string | null; refresh: () => void } {
+  const { interval = 2000, enabled = true } = options;
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(enabled && !!url);
+  const [error, setError] = useState<string | null>(null);
+  const mountedRef = useRef(true);
+  const abortRef = useRef<AbortController | null>(null);
+
+  const fetchData = useCallback(async () => {
+    if (!url) return;
+    abortRef.current?.abort();
+    abortRef.current = new AbortController();
+    const result = await resilientFetch<T>(url, { signal: abortRef.current.signal });
+    if (!result.ok) {
+      if (result.error.isAborted) return;
+      if (mountedRef.current) {
+        setError(result.error.message);
+        setLoading(false);
+      }
+      return;
+    }
+    if (mountedRef.current) {
+      setData(result.data);
+      setError(null);
+      setLoading(false);
+    }
+  }, [url]);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    if (!enabled || !url) {
+      setLoading(false);
+      return;
+    }
+
+    setLoading(true);
+    fetchData();
+    const id = setInterval(fetchData, interval);
+
+    return () => {
+      mountedRef.current = false;
+      abortRef.current?.abort();
+      clearInterval(id);
+    };
+  }, [fetchData, interval, enabled, url]);
+
+  return { data, loading, error, refresh: fetchData };
+}

package/src/hooks/use-project-runs.ts

@@ -0,0 +1,51 @@
+'use client';
+import { useSmartPolling } from './use-smart-polling';
+import { Run } from '@/types';
+
+interface ProjectRunsResponse {
+  runs: Run[];
+  totalCount: number;
+  project: string;
+}
+
+interface UseProjectRunsOptions {
+  limit?: number;
+  offset?: number;
+  search?: string;
+  status?: string;
+  sort?: 'status' | 'activity';
+  enabled?: boolean;
+}
+
+export function useProjectRuns(
+  projectName: string,
+  options: UseProjectRunsOptions = {}
+) {
+  const { limit = 10, offset = 0, search = '', status = '', sort = 'status', enabled = true } = options;
+  const params = new URLSearchParams();
+  params.set('project', projectName);
+  params.set('limit', String(limit));
+  params.set('offset', String(offset));
+  if (search) params.set('search', search);
+  if (status) params.set('status', status);
+  if (sort && sort !== 'status') params.set('sort', sort);
+
+  const url = `/api/runs?${params.toString()}`;
+
+  const { data, loading, error, refresh } = useSmartPolling<ProjectRunsResponse>(
+    url,
+    {
+      interval: 5000,
+      sseFilter: () => true, // Any run update could affect this project
+      enabled
+    }
+  );
+
+  return {
+    runs: enabled && data ? data.runs : [],
+    totalCount: enabled && data ? data.totalCount : 0,
+    loading,
+    error,
+    refresh
+  };
+}

package/src/hooks/use-projects.ts

@@ -0,0 +1,26 @@
+'use client';
+import { useSmartPolling } from './use-smart-polling';
+import { ProjectSummary } from '@/types';
+
+interface ProjectsResponse {
+  projects: ProjectSummary[];
+  recentCompletionWindowMs?: number;
+}
+
+export function useProjects(interval: number = 5000, suppressSseRefetch: boolean = false) {
+  const { data, loading, error, refresh } = useSmartPolling<ProjectsResponse>(
+    '/api/runs?mode=projects',
+    {
+      interval,
+      sseFilter: (event) => event.type === 'update' || event.type === 'new-run',
+      suppressSseRefetch,
+    }
+  );
+  return {
+    projects: data?.projects || [],
+    recentCompletionWindowMs: data?.recentCompletionWindowMs ?? 14400000,
+    loading,
+    error,
+    refresh
+  };
+}

package/src/hooks/use-run-dashboard.ts

@@ -0,0 +1,207 @@
+"use client";
+import { useState, useMemo, useCallback, useRef } from "react";
+import { useProjects } from "./use-projects";
+import { useBatchedUpdates, type CatchUpState } from "./use-batched-updates";
+import { usePersistedState } from "./use-persisted-state";
+import type { RunStatus, ProjectSummary, BreakpointRunInfo } from "@/types";
+import type { ExecutiveSummaryMetrics } from "@/components/dashboard/executive-summary-banner";
+
+/** Aggregated KPI metrics across all projects. */
+export interface DashboardMetrics {
+  totalRuns: number;
+  activeRuns: number;
+  completedRuns: number;
+  failedRuns: number;
+  staleRuns: number;
+  totalTasks: number;
+  completedTasks: number;
+}
+
+export type DashboardSortMode = "status" | "activity";
+export type DashboardStatusFilter = RunStatus | "all" | "stale";
+
+export interface UseRunDashboardReturn {
+  // Data
+  projects: ProjectSummary[];
+  loading: boolean;
+  error: string | null | undefined;
+  metrics: DashboardMetrics;
+  allBreakpointRuns: BreakpointRunInfo[];
+  summaryMetrics: ExecutiveSummaryMetrics;
+  bannerFingerprint: string;
+  bannerDismissed: boolean;
+  filterCounts: Record<DashboardStatusFilter, number>;
+  filteredProjects: ProjectSummary[];
+  activeProjects: ProjectSummary[];
+  historyProjects: ProjectSummary[];
+
+  // State
+  statusFilter: DashboardStatusFilter;
+  sortMode: DashboardSortMode;
+  historyCollapsed: boolean;
+  cardStatusFilter: RunStatus | "all";
+  hasStaleRuns: boolean;
+
+  // Catch-up mode
+  catchUp: CatchUpState;
+
+  // Actions
+  setStatusFilter: (value: DashboardStatusFilter) => void;
+  setSortMode: (value: DashboardSortMode | ((prev: DashboardSortMode) => DashboardSortMode)) => void;
+  setHistoryCollapsed: (value: boolean | ((prev: boolean) => boolean)) => void;
+  setDismissedFingerprint: (value: string | null | ((prev: string | null) => string | null)) => void;
+  toggleMetricFilter: (filter: DashboardStatusFilter) => void;
+  handleHideProject: (projectName: string) => void;
+}
+
+export function useRunDashboard(): UseRunDashboardReturn {
+  // Use a ref to bridge the circular dependency between useBatchedUpdates.onFlush
+  // and the refresh function returned by useProjects.
+  const refreshRef = useRef<() => void>(() => {});
+
+  // Monitor SSE event rate and activate catch-up mode during bursts.
+  // When catch-up is active, useProjects suppresses SSE-triggered refetches
+  // so the UI stays calm until the user clicks "refresh now" or the burst subsides.
+  const sseFilter = useCallback(
+    (event: { type: string }) => event.type === "update" || event.type === "new-run",
+    []
+  );
+  const catchUp = useBatchedUpdates({
+    sseFilter,
+    onFlush: () => refreshRef.current(),
+  });
+
+  const { projects, recentCompletionWindowMs, loading, error, refresh } = useProjects(
+    5000,
+    catchUp.active
+  );
+  refreshRef.current = refresh;
+
+  const [statusFilter, setStatusFilter] = useState<DashboardStatusFilter>("all");
+  const [sortMode, setSortMode] = usePersistedState<DashboardSortMode>("observer:sort-mode", "status");
+  const [dismissedFingerprint, setDismissedFingerprint] = usePersistedState<string | null>("banner-dismissed-fingerprint", null);
+
+  // Toggle filter from metric tile: clicking active filter clears it
+  const toggleMetricFilter = useCallback((filter: DashboardStatusFilter) => {
+    setStatusFilter((prev) => (prev === filter ? "all" : filter));
+  }, []);
+
+  const handleHideProject = useCallback((_projectName: string) => {
+    refresh();
+  }, [refresh]);
+
+  // Aggregate metrics across all projects
+  const metrics = useMemo<DashboardMetrics>(() => {
+    const totalRuns = projects.reduce((s, p) => s + p.totalRuns, 0);
+    const activeRuns = projects.reduce((s, p) => s + p.activeRuns, 0);
+    const completedRuns = projects.reduce((s, p) => s + p.completedRuns, 0);
+    const failedRuns = projects.reduce((s, p) => s + p.failedRuns, 0);
+    const staleRuns = projects.reduce((s, p) => s + p.staleRuns, 0);
+    const totalTasks = projects.reduce((s, p) => s + p.totalTasks, 0);
+    const completedTasks = projects.reduce((s, p) => s + p.completedTasksAggregate, 0);
+    return { totalRuns, activeRuns, completedRuns, failedRuns, staleRuns, totalTasks, completedTasks };
+  }, [projects]);
+
+  // Collect all breakpoint runs across all projects
+  const allBreakpointRuns = useMemo<BreakpointRunInfo[]>(() => {
+    return projects.flatMap((p) => p.breakpointRuns ?? []);
+  }, [projects]);
+
+  // Executive summary metrics for the banner
+  const summaryMetrics = useMemo<ExecutiveSummaryMetrics>(() => ({
+    totalProjects: projects.length,
+    activeRuns: metrics.activeRuns,
+    failedRuns: metrics.failedRuns,
+    completedRuns: metrics.completedRuns,
+    staleRuns: metrics.staleRuns,
+    pendingBreakpoints: projects.reduce((s, p) => s + p.pendingBreakpoints, 0),
+  }), [projects, metrics]);
+
+  // Fingerprint for banner dismiss
+  const bannerFingerprint = `${summaryMetrics.failedRuns}-${summaryMetrics.staleRuns}-${summaryMetrics.pendingBreakpoints}`;
+  const bannerDismissed = dismissedFingerprint === bannerFingerprint;
+
+  const filterCounts = useMemo(() => {
+    return {
+      all: metrics.totalRuns,
+      waiting: metrics.activeRuns,
+      stale: metrics.staleRuns,
+      completed: metrics.completedRuns,
+      failed: metrics.failedRuns,
+      pending: 0,
+    } as Record<DashboardStatusFilter, number>;
+  }, [metrics]);
+
+  // Filter projects by status counts
+  const filteredProjects = useMemo(() => {
+    if (statusFilter === "all") return projects;
+    if (statusFilter === "stale") return projects.filter((p) => p.staleRuns > 0);
+    return projects.filter((project) => {
+      if (statusFilter === "waiting") return project.activeRuns > 0;
+      if (statusFilter === "completed") return project.completedRuns > 0;
+      if (statusFilter === "failed") return project.failedRuns > 0;
+      return false;
+    });
+  }, [projects, statusFilter]);
+
+  // Determine the status filter to pass to ProjectHealthCard
+  const cardStatusFilter: RunStatus | "all" = statusFilter === "stale" ? "all" : statusFilter;
+
+  // Split filtered projects into sections based on sort mode
+  const { activeProjects, historyProjects } = useMemo(() => {
+    const now = Date.now();
+    if (sortMode === "activity") {
+      const twentyFourHours = 24 * 60 * 60 * 1000;
+      const recent = filteredProjects.filter((p) =>
+        now - new Date(p.latestUpdate).getTime() < twentyFourHours
+      );
+      const earlier = filteredProjects.filter((p) =>
+        now - new Date(p.latestUpdate).getTime() >= twentyFourHours
+      );
+      return { activeProjects: recent, historyProjects: earlier };
+    }
+    const active = filteredProjects.filter((p) =>
+      p.activeRuns > 0 || p.staleRuns > 0 ||
+      (now - new Date(p.latestUpdate).getTime() < recentCompletionWindowMs)
+    );
+    const history = filteredProjects.filter((p) =>
+      p.activeRuns === 0 && p.staleRuns === 0 &&
+      (now - new Date(p.latestUpdate).getTime() >= recentCompletionWindowMs)
+    );
+    return { activeProjects: active, historyProjects: history };
+  }, [filteredProjects, recentCompletionWindowMs, sortMode]);
+
+  const [historyCollapsed, setHistoryCollapsed] = usePersistedState(
+    "observer:history-collapsed",
+    historyProjects.length > 5
+  );
+
+  const hasStaleRuns = metrics.staleRuns > 0;
+
+  return {
+    projects,
+    loading,
+    error,
+    metrics,
+    allBreakpointRuns,
+    summaryMetrics,
+    bannerFingerprint,
+    bannerDismissed,
+    filterCounts,
+    filteredProjects,
+    activeProjects,
+    historyProjects,
+    statusFilter,
+    sortMode,
+    historyCollapsed,
+    cardStatusFilter,
+    hasStaleRuns,
+    catchUp,
+    setStatusFilter,
+    setSortMode,
+    setHistoryCollapsed,
+    setDismissedFingerprint,
+    toggleMetricFilter,
+    handleHideProject,
+  };
+}

package/src/hooks/use-run-detail.ts

@@ -0,0 +1,77 @@
+"use client";
+import { useMemo, useRef } from "react";
+import { useSmartPolling } from "./use-smart-polling";
+import type { RunDetailResponse, TaskDetailResponse, RunStatus } from "@/types";
+
+// Poll intervals by run status:
+// - Active/waiting runs change frequently, poll every 3s
+// - Completed/failed runs are static, poll every 30s (just in case of late events)
+const POLL_ACTIVE = 3000;
+const POLL_COMPLETED = 30000;
+
+function getIntervalForStatus(status: RunStatus | undefined): number {
+  if (!status) return POLL_ACTIVE;
+  return status === "completed" || status === "failed"
+    ? POLL_COMPLETED
+    : POLL_ACTIVE;
+}
+
+export function useRunDetail(runId: string, intervalOverride?: number) {
+  // Track last known run status to adapt poll interval.
+  // useRef avoids triggering re-render; the interval change takes effect
+  // on the next useSmartPolling dependency cycle.
+  const lastStatusRef = useRef<RunStatus | undefined>(undefined);
+
+  const adaptiveInterval = intervalOverride ?? getIntervalForStatus(lastStatusRef.current);
+
+  const { data, loading, error, refresh } = useSmartPolling<RunDetailResponse>(
+    `/api/runs/${runId}?maxEvents=50`,
+    {
+      interval: adaptiveInterval,
+      sseFilter: (event) =>
+        event.runId === runId || (event.runIds?.includes(runId) ?? false)
+    }
+  );
+
+  const run = data?.run || null;
+
+  // Update status ref so next render picks up the adaptive interval.
+  // When status transitions (e.g. "waiting" -> "completed"), the interval
+  // changes from 3s to 30s, and useSmartPolling restarts its timer.
+  if (run && run.status !== lastStatusRef.current) {
+    lastStatusRef.current = run.status;
+  }
+
+  // Detect if any breakpoint tasks are waiting for approval
+  const hasBreakpointWaiting = useMemo(() => {
+    if (!run) return false;
+    return run.tasks.some(
+      (t) => t.kind === "breakpoint" && t.status === "requested"
+    );
+  }, [run]);
+
+  return {
+    run,
+    loading,
+    error,
+    refresh,
+    hasBreakpointWaiting,
+  };
+}
+
+export function useTaskDetail(runId: string, effectId: string | null) {
+  const { data, loading, error } = useSmartPolling<TaskDetailResponse>(
+    effectId ? `/api/runs/${runId}/tasks/${effectId}` : "",
+    {
+      enabled: !!effectId,
+      interval: 5000,
+      sseFilter: (event) =>
+        event.runId === runId || (event.runIds?.includes(runId) ?? false),
+    }
+  );
+  return {
+    task: data?.task || null,
+    loading,
+    error,
+  };
+}