@castlekit/castle 0.3.0 → 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,7 +1,8 @@
 "use client";
 
-import { useEffect, useRef, useCallback } from "react";
+import { useEffect, useCallback } from "react";
 import useSWR from "swr";
+import { subscribe, onError, type SSEEvent } from "@/lib/sse-singleton";
 
 // ============================================================================
 // Types
@@ -27,24 +28,24 @@ 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) return [];
+  if (!res.ok) {
+    console.warn(`[useOpenClaw] Agents fetch failed: ${res.status}`);
+    return [];
+  }
   const data = await res.json();
   return data.agents || [];
 };
@@ -61,7 +62,6 @@ const agentsFetcher = async (url: string): Promise<OpenClawAgent[]> => {
  * SSE subscription pushes real-time updates that trigger SWR cache invalidation.
  */
 export function useOpenClaw() {
-  const eventSourceRef = useRef<EventSource | null>(null);
 
   // ---------------------------------------------------------------------------
   // SWR: Connection status
@@ -114,66 +114,53 @@ export function useOpenClaw() {
   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 — update status via SWR
-        if (evt.event === "castle.state") {
-          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) {
-            mutateAgents();
-          }
-        }
-
-        // Handle agent-related events — re-fetch agent list
-        if (evt.event?.startsWith("agent.")) {
-          mutateAgents();
-        }
-
-        // Handle avatar update events
-        if (evt.event === "agentAvatarUpdated") {
-          mutateAgents();
-        }
-      } 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
+    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();
     };
   }, [mutateStatus, mutateAgents]);
 

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

@@ -81,6 +81,7 @@ export function useSearch() {
         }
       } catch (err) {
         if ((err as Error).name !== "AbortError") {
+          console.error("[useSearch] Search failed:", (err as Error).message);
           setResults([]);
         }
       } finally {

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

@@ -7,7 +7,10 @@ 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");
+  if (!res.ok) {
+    console.error(`[useSessionStats] Fetch failed: ${res.status} ${url}`);
+    throw new Error("Failed to fetch session stats");
+  }
   return res.json();
 };
 

package/src/lib/sse-singleton.ts

@@ -0,0 +1,184 @@
+/**
+ * Shared SSE singleton for Castle.
+ *
+ * Creates a SINGLE EventSource connection to /api/openclaw/events that is
+ * shared across all consumers (use-chat, use-openclaw, etc.).
+ *
+ * Ref-counted: the first subscriber opens the connection, the last
+ * unsubscribe closes it. Events are dispatched to handlers by event type.
+ *
+ * Deduplication: tracks the last seen `seq` number and drops duplicates
+ * as a safety net against multiple connections or reconnect replays.
+ */
+
+export interface SSEEvent {
+  event: string;
+  payload?: unknown;
+  seq?: number;
+}
+
+type EventHandler = (evt: SSEEvent) => void;
+
+// ---------------------------------------------------------------------------
+// Module-level singleton state
+// ---------------------------------------------------------------------------
+
+let es: EventSource | null = null;
+let refCount = 0;
+let lastSeq = -1;
+let lastEventTimestamp = Date.now();
+
+/** Handlers keyed by event pattern. Exact match or "*" for all events. */
+const handlers = new Map<string, Set<EventHandler>>();
+
+/** Error handlers notified on connection loss */
+const errorHandlers = new Set<() => void>();
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function matchesPattern(eventType: string, pattern: string): boolean {
+  if (pattern === "*") return true;
+  if (pattern.endsWith(".*")) {
+    return eventType.startsWith(pattern.slice(0, -1));
+  }
+  return eventType === pattern;
+}
+
+function dispatch(evt: SSEEvent) {
+  // Update last-event timestamp for heartbeat monitoring
+  lastEventTimestamp = Date.now();
+
+  // Dedup by seq — drop events we've already seen
+  if (typeof evt.seq === "number") {
+    if (evt.seq <= lastSeq) {
+      console.debug("[SSE Client] Dropped duplicate event seq:", evt.seq, "event:", evt.event);
+      return;
+    }
+    lastSeq = evt.seq;
+  }
+
+  const eventType = evt.event;
+  for (const [pattern, handlerSet] of handlers) {
+    if (matchesPattern(eventType, pattern)) {
+      for (const handler of handlerSet) {
+        try {
+          handler(evt);
+        } catch (err) {
+          console.error("[SSE] Handler error:", err);
+        }
+      }
+    }
+  }
+}
+
+function openConnection() {
+  if (es) return;
+
+  console.log("[SSE Client] Opening connection (subscribers:", refCount + ")");
+  es = new EventSource("/api/openclaw/events");
+  lastEventTimestamp = Date.now();
+
+  es.onopen = () => {
+    console.log("[SSE Client] Connected");
+  };
+
+  es.onmessage = (e) => {
+    try {
+      const evt: SSEEvent = JSON.parse(e.data);
+      dispatch(evt);
+    } catch (err) {
+      console.warn("[SSE Client] Failed to parse event:", (err as Error).message, "data:", e.data?.slice(0, 100));
+    }
+  };
+
+  es.onerror = (e) => {
+    console.warn("[SSE Client] Connection error (readyState:", es?.readyState + ")");
+    // EventSource auto-reconnects. Notify error handlers so they can
+    // update UI state (e.g. show "disconnected").
+    for (const handler of errorHandlers) {
+      try {
+        handler();
+      } catch {
+        // ignore
+      }
+    }
+  };
+}
+
+function closeConnection() {
+  if (es) {
+    console.log("[SSE Client] Closing connection");
+    es.close();
+    es = null;
+  }
+  lastSeq = -1;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Subscribe to SSE events matching a pattern.
+ *
+ * Patterns:
+ *  - `"chat"`         — exact match for chat events
+ *  - `"castle.state"` — exact match for state events
+ *  - `"agent.*"`      — wildcard: matches agent.created, agent.updated, etc.
+ *  - `"*"`            — all events
+ *
+ * Returns an unsubscribe function. Call it in your useEffect cleanup.
+ */
+export function subscribe(pattern: string, handler: EventHandler): () => void {
+  if (!handlers.has(pattern)) {
+    handlers.set(pattern, new Set());
+  }
+  handlers.get(pattern)!.add(handler);
+
+  refCount++;
+  if (refCount === 1) {
+    openConnection();
+  }
+
+  return () => {
+    const set = handlers.get(pattern);
+    if (set) {
+      set.delete(handler);
+      if (set.size === 0) handlers.delete(pattern);
+    }
+
+    refCount--;
+    if (refCount <= 0) {
+      refCount = 0;
+      closeConnection();
+    }
+  };
+}
+
+/**
+ * Subscribe to connection error events.
+ * Returns an unsubscribe function.
+ */
+export function onError(handler: () => void): () => void {
+  errorHandlers.add(handler);
+  return () => {
+    errorHandlers.delete(handler);
+  };
+}
+
+/**
+ * Get the timestamp of the last received SSE event.
+ * Used for heartbeat-based timeout detection.
+ */
+export function getLastEventTimestamp(): number {
+  return lastEventTimestamp;
+}
+
+/**
+ * Check if the SSE connection is currently open.
+ */
+export function isConnected(): boolean {
+  return es !== null && es.readyState !== EventSource.CLOSED;
+}

package/src/lib/types/chat.ts

@@ -122,26 +122,42 @@ export interface QueuedMessage {
 }
 
 // ============================================================================
-// Session Status (from Gateway session.status RPC)
+// Session Status (read from OpenClaw session store on filesystem)
 // ============================================================================
 
 export interface SessionStatus {
   sessionKey: string;
+  sessionId: string;
   agentId: string;
   model: string;
+  modelProvider: string;
   tokens: {
     input: number;
     output: number;
+    total: number;
   };
   context: {
-    used: number;
-    limit: number;
-    percentage: number;
+    used: number;       // totalTokens (current context window usage)
+    limit: number;      // effective operating limit (from config, default 200k)
+    modelMax: number;   // model's theoretical max (e.g. 1M for Sonnet 4.5)
+    percentage: number; // used / limit * 100
   };
   compactions: number;
-  runtime: string;
-  thinking: string;
+  thinkingLevel: string | null;
   updatedAt: number;
+  /** System prompt breakdown — only present when the session has run at least once */
+  systemPrompt?: {
+    totalChars: number;
+    projectContextChars: number;
+    nonProjectContextChars: number;
+    skills: { promptChars: number; count: number };
+    tools: { listChars: number; schemaChars: number; count: number };
+    workspaceFiles: Array<{
+      name: string;
+      injectedChars: number;
+      truncated: boolean;
+    }>;
+  };
 }
 
 // ============================================================================