@castlekit/castle 0.1.6 → 0.3.1

package/src/lib/hooks/use-compaction-events.ts

@@ -0,0 +1,132 @@
+"use client";
+
+import { useState, useEffect, useCallback, useRef } from "react";
+import { subscribe, type SSEEvent } from "@/lib/sse-singleton";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface CompactionEvent {
+  phase: "start" | "end";
+  willRetry?: boolean;
+  timestamp: number;
+}
+
+interface UseCompactionEventsOptions {
+  /** The session key to monitor. Null disables monitoring. */
+  sessionKey: string | null;
+  /** Callback fired when compaction completes (phase: "end"). */
+  onCompactionComplete?: () => void;
+}
+
+interface UseCompactionEventsReturn {
+  /** Whether a compaction is currently in progress. */
+  isCompacting: boolean;
+  /** The last compaction event received. */
+  lastCompaction: CompactionEvent | null;
+  /** Number of compactions observed in this session (since mount). */
+  compactionCount: number;
+  /** Whether to show the compaction banner (auto-dismissed after 8s). */
+  showBanner: boolean;
+  /** Manually dismiss the banner. */
+  dismissBanner: () => void;
+}
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * Subscribes to real-time compaction events from the Gateway via SSE singleton.
+ *
+ * Compaction events arrive as agent events with `stream: "compaction"`:
+ *   { stream: "compaction", data: { phase: "start"|"end", willRetry?: boolean } }
+ *
+ * These are forwarded through the SSE system as events with type starting
+ * with "agent." or as top-level events. We subscribe to "*" and filter.
+ */
+export function useCompactionEvents({
+  sessionKey,
+  onCompactionComplete,
+}: UseCompactionEventsOptions): UseCompactionEventsReturn {
+  const [isCompacting, setIsCompacting] = useState(false);
+  const [lastCompaction, setLastCompaction] = useState<CompactionEvent | null>(null);
+  const [compactionCount, setCompactionCount] = useState(0);
+  const [showBanner, setShowBanner] = useState(false);
+  const bannerTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const onCompleteRef = useRef(onCompactionComplete);
+  onCompleteRef.current = onCompactionComplete;
+
+  useEffect(() => {
+    if (!sessionKey) return;
+
+    // Subscribe to all events and filter for compaction events.
+    // Compaction events come through as agent events with stream: "compaction"
+    const unsubscribe = subscribe("*", (evt: SSEEvent) => {
+      // Check for compaction event payload
+      const payload = evt.payload as Record<string, unknown> | undefined;
+      if (!payload) return;
+
+      // Compaction events can arrive in several shapes depending on Gateway version.
+      // Look for stream === "compaction" in the payload
+      const stream = payload.stream as string | undefined;
+      if (stream !== "compaction") return;
+
+      const data = (payload.data ?? payload) as {
+        phase?: string;
+        willRetry?: boolean;
+      };
+
+      const phase = data.phase as "start" | "end" | undefined;
+      if (!phase) return;
+
+      const compEvent: CompactionEvent = {
+        phase,
+        willRetry: data.willRetry,
+        timestamp: Date.now(),
+      };
+
+      setLastCompaction(compEvent);
+
+      if (phase === "start") {
+        setIsCompacting(true);
+      } else if (phase === "end") {
+        setIsCompacting(false);
+        setCompactionCount((c) => c + 1);
+
+        // Show banner
+        setShowBanner(true);
+        if (bannerTimer.current) clearTimeout(bannerTimer.current);
+        bannerTimer.current = setTimeout(() => setShowBanner(false), 8000);
+
+        // Notify parent (e.g. to refresh session stats)
+        onCompleteRef.current?.();
+      }
+    });
+
+    return () => {
+      unsubscribe();
+      if (bannerTimer.current) {
+        clearTimeout(bannerTimer.current);
+        bannerTimer.current = null;
+      }
+    };
+  }, [sessionKey]);
+
+  const dismissBanner = useCallback(() => {
+    setShowBanner(false);
+    if (bannerTimer.current) {
+      clearTimeout(bannerTimer.current);
+      bannerTimer.current = null;
+    }
+  }, []);
+
+  return {
+    isCompacting,
+    lastCompaction,
+    compactionCount,
+    showBanner,
+    dismissBanner,
+  };
+}

package/src/lib/hooks/use-context-boundary.ts

@@ -0,0 +1,82 @@
+"use client";
+
+import { useCallback } from "react";
+import useSWR from "swr";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface ContextBoundaryData {
+  boundaryMessageId: string | null;
+  fresh: boolean;
+}
+
+interface UseContextBoundaryOptions {
+  /** Gateway session key. Null disables fetching. */
+  sessionKey: string | null;
+  /** Channel ID for matching preview messages to local DB. */
+  channelId: string;
+}
+
+interface UseContextBoundaryReturn {
+  /** ID of the oldest message still in agent context. Null = no compaction yet or unknown. */
+  boundaryMessageId: string | null;
+  /** Whether data is loading. */
+  isLoading: boolean;
+  /** Re-fetch the boundary (call after compaction events). */
+  refresh: () => void;
+}
+
+// ============================================================================
+// Fetcher
+// ============================================================================
+
+const fetcher = async (url: string): Promise<ContextBoundaryData | null> => {
+  const res = await fetch(url);
+  if (res.status === 204) return null;
+  if (!res.ok) return null;
+  return res.json();
+};
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * Fetches and caches the compaction context boundary for a session.
+ *
+ * Returns the ID of the oldest message the agent can still "see".
+ * Messages before this boundary have been compacted (summarized).
+ *
+ * Polls infrequently (every 60s) since compaction events trigger explicit refreshes.
+ */
+export function useContextBoundary({
+  sessionKey,
+  channelId,
+}: UseContextBoundaryOptions): UseContextBoundaryReturn {
+  const swrKey = sessionKey
+    ? `/api/openclaw/session/context?sessionKey=${encodeURIComponent(sessionKey)}&channelId=${encodeURIComponent(channelId)}`
+    : null;
+
+  const { data, isLoading, mutate } = useSWR<ContextBoundaryData | null>(
+    swrKey,
+    fetcher,
+    {
+      refreshInterval: 60000, // Refresh every 60s as background check
+      dedupingInterval: 10000,
+      revalidateOnFocus: false,
+      errorRetryCount: 1,
+    }
+  );
+
+  const refresh = useCallback(() => {
+    mutate();
+  }, [mutate]);
+
+  return {
+    boundaryMessageId: data?.boundaryMessageId ?? null,
+    isLoading,
+    refresh,
+  };
+}

package/src/lib/hooks/use-openclaw.ts

@@ -1,6 +1,8 @@
 "use client";
 
-import { useState, useEffect, useCallback, useRef } from "react";
+import { useEffect, useCallback } from "react";
+import useSWR from "swr";
+import { subscribe, onError, type SSEEvent } from "@/lib/sse-singleton";
 
 // ============================================================================
 // Types
@@ -26,138 +28,158 @@ export interface OpenClawStatus {
   };
 }
 
-interface GatewaySSEEvent {
-  event: string;
-  payload?: unknown;
-  seq?: number;
-}
+// ============================================================================
+// Fetchers
+// ============================================================================
+
+const statusFetcher = async (url: string): Promise<OpenClawStatus> => {
+  const res = await fetch(url, { method: "POST" });
+  if (!res.ok) {
+    console.warn(`[useOpenClaw] Status fetch returned ${res.status}`);
+  }
+  return res.json();
+};
+
+const agentsFetcher = async (url: string): Promise<OpenClawAgent[]> => {
+  const res = await fetch(url);
+  if (!res.ok) {
+    console.warn(`[useOpenClaw] Agents fetch failed: ${res.status}`);
+    return [];
+  }
+  const data = await res.json();
+  return data.agents || [];
+};
 
 // ============================================================================
 // Hook
 // ============================================================================
 
+/**
+ * Shared OpenClaw connection status and agents hook.
+ * Uses SWR for cache-based sharing across all components —
+ * any component calling useOpenClaw() gets the same cached data without extra fetches.
+ *
+ * SSE subscription pushes real-time updates that trigger SWR cache invalidation.
+ */
 export function useOpenClaw() {
-  const [status, setStatus] = useState<OpenClawStatus | null>(null);
-  const [agents, setAgents] = useState<OpenClawAgent[]>([]);
-  const [isLoading, setIsLoading] = useState(true);
-  const [agentsLoading, setAgentsLoading] = useState(true);
-  const eventSourceRef = useRef<EventSource | null>(null);
-
-  // Fetch connection status
-  const fetchStatus = useCallback(async () => {
-    try {
-      const res = await fetch("/api/openclaw/ping", { method: "POST" });
-      const data: OpenClawStatus = await res.json();
-      setStatus(data);
-      return data;
-    } catch {
-      setStatus({ ok: false, configured: false, error: "Failed to reach Castle server" });
-      return null;
-    } finally {
-      setIsLoading(false);
+
+  // ---------------------------------------------------------------------------
+  // SWR: Connection status
+  // ---------------------------------------------------------------------------
+  const {
+    data: status,
+    error: statusError,
+    isLoading: statusLoading,
+    mutate: mutateStatus,
+  } = useSWR<OpenClawStatus>(
+    "/api/openclaw/ping",
+    statusFetcher,
+    {
+      refreshInterval: 60000,        // Background refresh every 60s
+      revalidateOnFocus: true,
+      dedupingInterval: 10000,       // Dedup rapid calls within 10s
+      errorRetryCount: 2,
     }
-  }, []);
-
-  // Fetch agents
-  const fetchAgents = useCallback(async () => {
-    try {
-      setAgentsLoading(true);
-      const res = await fetch("/api/openclaw/agents");
-      if (!res.ok) {
-        setAgents([]);
-        return;
-      }
-      const data = await res.json();
-      setAgents(data.agents || []);
-    } catch {
-      setAgents([]);
-    } finally {
-      setAgentsLoading(false);
+  );
+
+  const isConnected = status?.ok ?? false;
+
+  // ---------------------------------------------------------------------------
+  // SWR: Agents (conditional — only fetch when connected)
+  // ---------------------------------------------------------------------------
+  const {
+    data: agents,
+    isLoading: agentsLoading,
+    mutate: mutateAgents,
+  } = useSWR<OpenClawAgent[]>(
+    isConnected ? "/api/openclaw/agents" : null,
+    agentsFetcher,
+    {
+      refreshInterval: 300000,       // Refresh agents every 5 min
+      revalidateOnFocus: false,
+      dedupingInterval: 30000,       // Dedup within 30s
     }
-  }, []);
+  );
 
-  // Refresh everything
+  // ---------------------------------------------------------------------------
+  // Refresh helpers
+  // ---------------------------------------------------------------------------
   const refresh = useCallback(async () => {
-    const newStatus = await fetchStatus();
-    if (newStatus?.ok) {
-      await fetchAgents();
-    }
-  }, [fetchStatus, fetchAgents]);
-
-  // Initial data fetch
-  useEffect(() => {
-    let cancelled = false;
-
-    async function init() {
-      const s = await fetchStatus();
-      if (!cancelled && s?.ok) {
-        await fetchAgents();
-      }
+    await mutateStatus();
+    if (isConnected) {
+      await mutateAgents();
     }
+  }, [mutateStatus, mutateAgents, isConnected]);
 
-    init();
-    return () => { cancelled = true; };
-  }, [fetchStatus, fetchAgents]);
+  const refreshAgents = useCallback(() => mutateAgents(), [mutateAgents]);
 
-  // SSE subscription for real-time events
+  // ---------------------------------------------------------------------------
+  // SSE subscription for real-time events via shared singleton
+  // ---------------------------------------------------------------------------
   useEffect(() => {
-    const es = new EventSource("/api/openclaw/events");
-    eventSourceRef.current = es;
-
-    es.onmessage = (e) => {
-      try {
-        const evt: GatewaySSEEvent = JSON.parse(e.data);
-
-        // Handle Castle state changes
-        if (evt.event === "castle.state") {
-          const payload = evt.payload as { state: string; isConnected: boolean; server?: Record<string, unknown> };
-          setStatus((prev) => ({
-            ok: payload.isConnected,
-            configured: prev?.configured ?? true,
-            state: payload.state,
-            server: payload.server as OpenClawStatus["server"],
-          }));
-
-          // Re-fetch agents when connection state changes to connected
-          if (payload.isConnected) {
-            fetchAgents();
-          }
-        }
-
-        // Handle agent-related events -- re-fetch agent list
-        if (evt.event?.startsWith("agent.")) {
-          fetchAgents();
-        }
-      } catch {
-        // Ignore parse errors
+    const handleState = (evt: SSEEvent) => {
+      const payload = evt.payload as {
+        state: string;
+        isConnected: boolean;
+        server?: Record<string, unknown>;
+      };
+
+      mutateStatus(
+        (prev) => ({
+          ok: payload.isConnected,
+          configured: prev?.configured ?? true,
+          state: payload.state,
+          server: payload.server as OpenClawStatus["server"],
+        }),
+        { revalidate: false }
+      );
+
+      if (payload.isConnected) {
+        mutateAgents();
       }
     };
 
-    es.onerror = () => {
-      // EventSource auto-reconnects, but update state
-      setStatus((prev) => prev ? { ...prev, ok: false, state: "disconnected" } : prev);
+    const handleAgent = (_evt: SSEEvent) => {
+      mutateAgents();
     };
 
+    const handleError = () => {
+      console.warn("[useOpenClaw] SSE error — marking as disconnected");
+      mutateStatus(
+        (prev) => prev ? { ...prev, ok: false, state: "disconnected" } : prev,
+        { revalidate: false }
+      );
+    };
+
+    const unsub1 = subscribe("castle.state", handleState);
+    const unsub2 = subscribe("agent.*", handleAgent);
+    const unsub3 = subscribe("agentAvatarUpdated", handleAgent);
+    const unsub4 = onError(handleError);
+
     return () => {
-      es.close();
-      eventSourceRef.current = null;
+      unsub1();
+      unsub2();
+      unsub3();
+      unsub4();
     };
-  }, [fetchAgents]);
+  }, [mutateStatus, mutateAgents]);
 
   return {
     // Status
     status,
-    isLoading,
-    isConnected: status?.ok ?? false,
+    isLoading: statusLoading,
+    isError: !!statusError,
+    isConnected,
     isConfigured: status?.configured ?? false,
     latency: status?.latency_ms,
     serverVersion: status?.server?.version,
 
     // Agents
-    agents,
+    agents: agents ?? [],
     agentsLoading,
 
     // Actions
     refresh,
+    refreshAgents,
   };
 }

package/src/lib/hooks/use-search.ts

@@ -0,0 +1,114 @@
+"use client";
+
+import { useState, useCallback, useRef, useEffect } from "react";
+import type { SearchResult } from "@/lib/types/search";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const DEBOUNCE_MS = 300;
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+export function useSearch() {
+  const [query, setQuery] = useState("");
+  const [results, setResults] = useState<SearchResult[]>([]);
+  const [isSearching, setIsSearching] = useState(false);
+  const [recentSearches, setRecentSearches] = useState<string[]>([]);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const abortRef = useRef<AbortController | null>(null);
+  const recentLoaded = useRef(false);
+
+  // Load recent searches from DB on first mount
+  useEffect(() => {
+    if (recentLoaded.current) return;
+    recentLoaded.current = true;
+    fetch("/api/openclaw/chat/search?recent=1")
+      .then((res) => (res.ok ? res.json() : { recent: [] }))
+      .then((data) => setRecentSearches(data.recent ?? []))
+      .catch(() => {});
+  }, []);
+
+  // Debounced search
+  const search = useCallback((q: string) => {
+    setQuery(q);
+
+    // Cancel pending request
+    if (timerRef.current) clearTimeout(timerRef.current);
+    if (abortRef.current) abortRef.current.abort();
+
+    if (!q.trim()) {
+      setResults([]);
+      setIsSearching(false);
+      return;
+    }
+
+    setIsSearching(true);
+    timerRef.current = setTimeout(async () => {
+      const controller = new AbortController();
+      abortRef.current = controller;
+
+      try {
+        const res = await fetch(
+          `/api/openclaw/chat/search?q=${encodeURIComponent(q.trim())}`,
+          { signal: controller.signal }
+        );
+        if (res.ok) {
+          const data = await res.json();
+          const searchResults: SearchResult[] = data.results ?? [];
+          setResults(searchResults);
+
+          // Save to recent searches in DB if results found
+          if (searchResults.length > 0) {
+            const trimmed = q.trim();
+            fetch("/api/openclaw/chat/search", {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({ query: trimmed }),
+            })
+              .then(() => {
+                // Update local state to reflect the save
+                setRecentSearches((prev) => {
+                  const filtered = prev.filter((s) => s !== trimmed);
+                  return [trimmed, ...filtered].slice(0, 15);
+                });
+              })
+              .catch(() => {});
+          }
+        }
+      } catch (err) {
+        if ((err as Error).name !== "AbortError") {
+          console.error("[useSearch] Search failed:", (err as Error).message);
+          setResults([]);
+        }
+      } finally {
+        setIsSearching(false);
+      }
+    }, DEBOUNCE_MS);
+  }, []);
+
+  const clearRecentSearches = useCallback(() => {
+    setRecentSearches([]);
+    fetch("/api/openclaw/chat/search", { method: "DELETE" }).catch(() => {});
+  }, []);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+      if (abortRef.current) abortRef.current.abort();
+    };
+  }, []);
+
+  return {
+    query,
+    setQuery: search,
+    results,
+    isSearching,
+    recentSearches,
+    clearRecentSearches,
+  };
+}

package/src/lib/hooks/use-session-stats.ts

@@ -0,0 +1,60 @@
+"use client";
+
+import { useCallback } from "react";
+import useSWR from "swr";
+import type { SessionStatus } from "@/lib/types/chat";
+
+const fetcher = async (url: string): Promise<SessionStatus | null> => {
+  const res = await fetch(url);
+  if (res.status === 204) return null;
+  if (!res.ok) {
+    console.error(`[useSessionStats] Fetch failed: ${res.status} ${url}`);
+    throw new Error("Failed to fetch session stats");
+  }
+  return res.json();
+};
+
+interface UseSessionStatsOptions {
+  sessionKey: string | null;
+}
+
+interface UseSessionStatsReturn {
+  stats: SessionStatus | null;
+  isLoading: boolean;
+  isError: boolean;
+  refresh: () => void;
+}
+
+/**
+ * SWR-based hook for fetching session statistics from the Gateway.
+ * Conditional fetching: only when sessionKey is non-null.
+ * Polls every 30s while active, dedupes within 5s.
+ */
+export function useSessionStats({ sessionKey }: UseSessionStatsOptions): UseSessionStatsReturn {
+  const {
+    data,
+    isLoading,
+    error,
+    mutate,
+  } = useSWR<SessionStatus | null>(
+    sessionKey ? `/api/openclaw/session/status?sessionKey=${sessionKey}` : null,
+    fetcher,
+    {
+      refreshInterval: 30000,
+      dedupingInterval: 5000,
+      revalidateOnFocus: false,
+      errorRetryCount: 1,
+    }
+  );
+
+  const refresh = useCallback(() => {
+    mutate();
+  }, [mutate]);
+
+  return {
+    stats: data ?? null,
+    isLoading,
+    isError: !!error,
+    refresh,
+  };
+}