@castlekit/castle 0.3.1 → 0.4.0

package/.next/standalone/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/.next/standalone/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/.next/standalone/src/lib/hooks/use-openclaw.ts

@@ -0,0 +1,185 @@
+"use client";
+
+import { useEffect, useCallback } from "react";
+import useSWR from "swr";
+import { subscribe, onError, type SSEEvent } from "@/lib/sse-singleton";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface OpenClawAgent {
+  id: string;
+  name: string;
+  description: string | null;
+  avatar: string | null;
+  emoji: string | null;
+}
+
+export interface OpenClawStatus {
+  ok: boolean;
+  configured: boolean;
+  latency_ms?: number;
+  state?: string;
+  error?: string;
+  server?: {
+    version?: string;
+    connId?: string;
+  };
+}
+
+// ============================================================================
+// 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() {
+
+  // ---------------------------------------------------------------------------
+  // 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,
+    }
+  );
+
+  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 helpers
+  // ---------------------------------------------------------------------------
+  const refresh = useCallback(async () => {
+    await mutateStatus();
+    if (isConnected) {
+      await mutateAgents();
+    }
+  }, [mutateStatus, mutateAgents, isConnected]);
+
+  const refreshAgents = useCallback(() => mutateAgents(), [mutateAgents]);
+
+  // ---------------------------------------------------------------------------
+  // SSE subscription for real-time events via shared singleton
+  // ---------------------------------------------------------------------------
+  useEffect(() => {
+    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();
+      }
+    };
+
+    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 () => {
+      unsub1();
+      unsub2();
+      unsub3();
+      unsub4();
+    };
+  }, [mutateStatus, mutateAgents]);
+
+  return {
+    // Status
+    status,
+    isLoading: statusLoading,
+    isError: !!statusError,
+    isConnected,
+    isConfigured: status?.configured ?? false,
+    latency: status?.latency_ms,
+    serverVersion: status?.server?.version,
+
+    // Agents
+    agents: agents ?? [],
+    agentsLoading,
+
+    // Actions
+    refresh,
+    refreshAgents,
+  };
+}

package/.next/standalone/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/.next/standalone/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,
+  };
+}

package/.next/standalone/src/lib/hooks/use-user-settings.ts

@@ -0,0 +1,46 @@
+"use client";
+
+import useSWR from "swr";
+
+const SETTINGS_KEY = "/api/settings";
+
+const fetcher = (url: string) => fetch(url).then((r) => r.json());
+
+interface UserSettings {
+  displayName?: string;
+  avatarPath?: string;
+  tooltips?: string;
+}
+
+/**
+ * Shared hook for user settings (display name, avatar, etc).
+ *
+ * All consumers share the same SWR cache. Call `refresh()` after
+ * updating settings to instantly propagate changes everywhere
+ * (user menu, chat headers, message avatars).
+ */
+export function useUserSettings() {
+  const { data, mutate, isLoading } = useSWR<UserSettings>(
+    SETTINGS_KEY,
+    fetcher,
+    {
+      revalidateOnFocus: true,
+      dedupingInterval: 5000,
+    }
+  );
+
+  const displayName = data?.displayName || "";
+  const avatarUrl = data?.avatarPath
+    ? `/api/settings/avatar?v=${encodeURIComponent(data.avatarPath)}`
+    : null;
+  const tooltips = data?.tooltips !== "false"; // default true
+
+  return {
+    displayName,
+    avatarUrl,
+    tooltips,
+    isLoading,
+    /** Call after saving settings to refresh all consumers */
+    refresh: () => mutate(),
+  };
+}