@castlekit/castle 0.1.6 → 0.3.1

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/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

@@ -0,0 +1,202 @@
+// ============================================================================
+// 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 (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;       // 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;
+  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;
+    }>;
+  };
+}
+
+// ============================================================================
+// 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;
+}

package/src/lib/types/search.ts

@@ -0,0 +1,60 @@
+// ============================================================================
+// Universal Search — Type System
+// ============================================================================
+//
+// Discriminated union so every result carries its type and the dialog can
+// render + navigate each type differently. Adding a new searchable content
+// type later requires only:
+//
+//   1. Add a new interface extending SearchResultBase
+//   2. Add it to the SearchResult union
+//   3. Add a renderer in the search dialog
+//   4. Add a search function in the API
+//
+// No changes to the dialog, hook, provider, keyboard shortcuts, or routing.
+
+// --- Content type registry ---
+
+export type SearchResultType = "message" | "task" | "note" | "project";
+// ^ Extend this union as new content types are added
+
+// --- Base result shape (shared fields) ---
+
+export interface SearchResultBase {
+  id: string;
+  type: SearchResultType;
+  title: string;        // Primary display text
+  subtitle?: string;    // Secondary line (sender, project name, etc.)
+  snippet: string;      // Content excerpt with match context
+  timestamp: number;    // For sorting / display
+  href: string;         // Where to navigate on click
+}
+
+// --- Content-specific result types ---
+
+export interface MessageSearchResult extends SearchResultBase {
+  type: "message";
+  channelId: string;
+  channelName: string;
+  messageId: string;
+  senderType: "user" | "agent";
+  senderName: string;
+  archived?: boolean;
+}
+
+// Future examples (not implemented in v1):
+// export interface TaskSearchResult extends SearchResultBase {
+//   type: "task";
+//   projectId: string;
+//   status: "todo" | "in_progress" | "done";
+// }
+//
+// export interface NoteSearchResult extends SearchResultBase {
+//   type: "note";
+//   notebookId: string;
+// }
+
+// --- Discriminated union ---
+
+export type SearchResult = MessageSearchResult;
+// ^ Becomes: MessageSearchResult | TaskSearchResult | NoteSearchResult | ...

package/src/middleware.ts

@@ -0,0 +1,52 @@
+import { NextRequest, NextResponse } from "next/server";
+
+/**
+ * Next.js Middleware — applies security checks to all API routes.
+ *
+ * In production, rejects requests from non-localhost IPs.
+ * Castle is a local-first app and should never be exposed to the internet.
+ */
+
+const LOCALHOST_HOSTS = new Set([
+  "localhost",
+  "127.0.0.1",
+  "::1",
+  "::ffff:127.0.0.1",
+]);
+
+export function middleware(request: NextRequest) {
+  // Only enforce in production — dev is always allowed
+  if (process.env.NODE_ENV === "development") {
+    return NextResponse.next();
+  }
+
+  // Check if the request originates from localhost
+  const host = request.headers.get("host") || "";
+  const hostname = host.split(":")[0];
+
+  const forwarded = request.headers.get("x-forwarded-for");
+  const clientIp = forwarded?.split(",")[0].trim();
+
+  // If x-forwarded-for is present and it's not localhost, reject
+  if (clientIp && !LOCALHOST_HOSTS.has(clientIp)) {
+    return NextResponse.json(
+      { error: "Forbidden — Castle is only accessible from localhost" },
+      { status: 403 }
+    );
+  }
+
+  // If the host header isn't a localhost variant, reject
+  if (hostname && !LOCALHOST_HOSTS.has(hostname)) {
+    return NextResponse.json(
+      { error: "Forbidden — Castle is only accessible from localhost" },
+      { status: 403 }
+    );
+  }
+
+  return NextResponse.next();
+}
+
+// Only run middleware on API routes
+export const config = {
+  matcher: "/api/:path*",
+};