@castlekit/castle 0.1.5 → 0.3.0

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

@@ -1,6 +1,7 @@
 "use client";
 
-import { useState, useEffect, useCallback, useRef } from "react";
+import { useEffect, useRef, useCallback } from "react";
+import useSWR from "swr";
 
 // ============================================================================
 // Types
@@ -32,74 +33,89 @@ interface GatewaySSEEvent {
   seq?: number;
 }
 
+// ============================================================================
+// Fetchers
+// ============================================================================
+
+const statusFetcher = async (url: string): Promise<OpenClawStatus> => {
+  const res = await fetch(url, { method: "POST" });
+  return res.json();
+};
+
+const agentsFetcher = async (url: string): Promise<OpenClawAgent[]> => {
+  const res = await fetch(url);
+  if (!res.ok) 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();
+    await mutateStatus();
+    if (isConnected) {
+      await mutateAgents();
     }
-  }, [fetchStatus, fetchAgents]);
+  }, [mutateStatus, mutateAgents, isConnected]);
 
-  // Initial data fetch
-  useEffect(() => {
-    let cancelled = false;
-
-    async function init() {
-      const s = await fetchStatus();
-      if (!cancelled && s?.ok) {
-        await fetchAgents();
-      }
-    }
-
-    init();
-    return () => { cancelled = true; };
-  }, [fetchStatus, fetchAgents]);
+  const refreshAgents = useCallback(() => mutateAgents(), [mutateAgents]);
 
+  // ---------------------------------------------------------------------------
   // SSE subscription for real-time events
+  // ---------------------------------------------------------------------------
   useEffect(() => {
     const es = new EventSource("/api/openclaw/events");
     eventSourceRef.current = es;
@@ -108,25 +124,39 @@ export function useOpenClaw() {
       try {
         const evt: GatewaySSEEvent = JSON.parse(e.data);
 
-        // Handle Castle state changes
+        // Handle Castle state changes — update status via SWR
         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"],
-          }));
+          const payload = evt.payload as {
+            state: string;
+            isConnected: boolean;
+            server?: Record<string, unknown>;
+          };
+
+          // Optimistically update the SWR cache with the SSE data
+          mutateStatus(
+            (prev) => ({
+              ok: payload.isConnected,
+              configured: prev?.configured ?? true,
+              state: payload.state,
+              server: payload.server as OpenClawStatus["server"],
+            }),
+            { revalidate: false }
+          );
 
           // Re-fetch agents when connection state changes to connected
           if (payload.isConnected) {
-            fetchAgents();
+            mutateAgents();
           }
         }
 
-        // Handle agent-related events -- re-fetch agent list
+        // Handle agent-related events — re-fetch agent list
         if (evt.event?.startsWith("agent.")) {
-          fetchAgents();
+          mutateAgents();
+        }
+
+        // Handle avatar update events
+        if (evt.event === "agentAvatarUpdated") {
+          mutateAgents();
         }
       } catch {
         // Ignore parse errors
@@ -135,29 +165,34 @@ export function useOpenClaw() {
 
     es.onerror = () => {
       // EventSource auto-reconnects, but update state
-      setStatus((prev) => prev ? { ...prev, ok: false, state: "disconnected" } : prev);
+      mutateStatus(
+        (prev) => prev ? { ...prev, ok: false, state: "disconnected" } : prev,
+        { revalidate: false }
+      );
     };
 
     return () => {
       es.close();
       eventSourceRef.current = null;
     };
-  }, [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,113 @@
+"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") {
+          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,57 @@
+"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) 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/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(),
+  };
+}

package/src/lib/types/chat.ts

@@ -0,0 +1,186 @@
+// ============================================================================
+// Channel
+// ============================================================================
+
+export interface Channel {
+  id: string;
+  name: string;
+  defaultAgentId: string;
+  agents: string[];         // Agent IDs in this channel
+  createdAt: number;        // unix ms
+  archivedAt?: number | null; // unix ms — null if active
+}
+
+// ============================================================================
+// Session
+// ============================================================================
+
+export interface ChannelSession {
+  id: string;
+  channelId: string;
+  sessionKey: string | null; // Gateway session key
+  startedAt: number;         // unix ms
+  endedAt: number | null;    // unix ms
+  summary: string | null;
+  totalInputTokens: number;
+  totalOutputTokens: number;
+}
+
+// ============================================================================
+// Message
+// ============================================================================
+
+export type MessageStatus = "complete" | "interrupted" | "aborted";
+
+export interface ChatMessage {
+  id: string;
+  channelId: string;
+  sessionId: string | null;
+  senderType: "user" | "agent";
+  senderId: string;
+  senderName: string | null;
+  content: string;
+  status: MessageStatus;
+  mentionedAgentId: string | null;
+  runId: string | null;       // Gateway run ID for streaming correlation
+  sessionKey: string | null;  // Gateway session key
+  inputTokens: number | null;
+  outputTokens: number | null;
+  createdAt: number;          // unix ms
+  attachments: MessageAttachment[];
+  reactions: MessageReaction[];
+}
+
+// ============================================================================
+// Attachment
+// ============================================================================
+
+export interface MessageAttachment {
+  id: string;
+  messageId: string;
+  attachmentType: "image" | "audio";
+  filePath: string;
+  mimeType: string | null;
+  fileSize: number | null;
+  originalName: string | null;
+  createdAt: number;         // unix ms
+}
+
+// ============================================================================
+// Reaction
+// ============================================================================
+
+export interface MessageReaction {
+  id: string;
+  messageId: string;
+  agentId: string | null;
+  emoji: string;
+  emojiChar: string;
+  createdAt: number;         // unix ms
+}
+
+// ============================================================================
+// Streaming
+// ============================================================================
+
+/** A message currently being streamed from the Gateway */
+export interface StreamingMessage {
+  runId: string;
+  agentId: string;
+  agentName: string;
+  sessionKey: string;
+  content: string;           // Accumulated text so far
+  startedAt: number;
+}
+
+/** A single streaming delta from the Gateway SSE */
+export interface ChatDelta {
+  runId: string;
+  sessionKey: string;
+  seq: number;
+  state: "delta" | "final" | "error";
+  text?: string;
+  errorMessage?: string;
+  message?: {
+    content?: Array<{ type?: string; text?: string }>;
+    role?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+  };
+}
+
+// ============================================================================
+// Message Queue
+// ============================================================================
+
+export interface QueuedMessage {
+  id: string;               // Temp ID for tracking
+  content: string;
+  agentId?: string;
+  attachments?: File[];
+  addedAt: number;
+}
+
+// ============================================================================
+// Session Status (from Gateway session.status RPC)
+// ============================================================================
+
+export interface SessionStatus {
+  sessionKey: string;
+  agentId: string;
+  model: string;
+  tokens: {
+    input: number;
+    output: number;
+  };
+  context: {
+    used: number;
+    limit: number;
+    percentage: number;
+  };
+  compactions: number;
+  runtime: string;
+  thinking: string;
+  updatedAt: number;
+}
+
+// ============================================================================
+// Storage Stats
+// ============================================================================
+
+export interface StorageStats {
+  messages: number;
+  channels: number;
+  attachments: number;
+  totalAttachmentBytes: number;
+  dbSizeBytes?: number;      // Size of castle.db file
+}
+
+// ============================================================================
+// API Payloads
+// ============================================================================
+
+export interface ChatSendRequest {
+  channelId: string;
+  content: string;
+  agentId?: string;
+  attachmentIds?: string[];
+}
+
+export interface ChatSendResponse {
+  runId: string;
+  messageId: string;
+  sessionKey: string;
+}
+
+export interface ChatCompleteRequest {
+  runId: string;
+  channelId: string;
+  content: string;
+  sessionKey: string;
+  agentId: string;
+  agentName?: string;
+  status: MessageStatus;
+  inputTokens?: number;
+  outputTokens?: number;
+}