@castlekit/castle 0.1.5 → 0.3.0

package/drizzle.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  schema: "./src/lib/db/schema.ts",
+  out: "./src/lib/db/migrations",
+  dialect: "sqlite",
+});

package/next.config.ts

@@ -2,6 +2,7 @@ import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
   devIndicators: false,
+  serverExternalPackages: ["better-sqlite3"],
 };
 
 export default nextConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@castlekit/castle",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "description": "The multi-agent workspace",
   "type": "module",
   "bin": {
@@ -10,7 +10,9 @@
     "dev": "next dev -p 3333",
     "build": "next build",
     "start": "next start -p 3333",
-    "lint": "next lint"
+    "lint": "next lint",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "repository": {
     "type": "git",
@@ -39,11 +41,15 @@
     "@dnd-kit/utilities": "^3.2.2",
     "@radix-ui/react-slider": "^1.3.6",
     "@tailwindcss/postcss": "^4.1.18",
+    "@twemoji/api": "^17.0.2",
     "@types/node": "^25.2.1",
     "@types/react": "^19.2.13",
     "@types/react-dom": "^19.2.3",
+    "@types/ws": "^8.18.1",
+    "better-sqlite3": "^12.6.2",
     "clsx": "^2.1.1",
     "commander": "^14.0.3",
+    "drizzle-orm": "^0.45.1",
     "json5": "^2.2.3",
     "lucide-react": "^0.563.0",
     "next": "^16.1.6",
@@ -52,13 +58,28 @@
     "picocolors": "^1.1.1",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
+    "react-markdown": "^10.1.0",
+    "react-syntax-highlighter": "^16.1.0",
     "recharts": "^3.7.0",
+    "remark-gfm": "^4.0.1",
+    "sharp": "^0.34.5",
     "swr": "^2.4.0",
     "tailwind-merge": "^3.4.0",
     "tailwindcss": "^4.1.18",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "ws": "^8.19.0",
-    "@types/ws": "^8.18.1"
+    "uuid": "^13.0.0",
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/react-syntax-highlighter": "^15.5.13",
+    "@types/sharp": "^0.31.1",
+    "@types/uuid": "^10.0.0",
+    "drizzle-kit": "^0.31.8",
+    "jsdom": "^28.0.0",
+    "vitest": "^4.0.18"
   }
 }

package/src/app/api/avatars/[id]/route.ts

@@ -1,14 +1,12 @@
 import { NextRequest, NextResponse } from "next/server";
 import { readFileSync, existsSync } from "fs";
-import { join } from "path";
+import { join, resolve } from "path";
 import { homedir } from "os";
+import { ensureGateway } from "@/lib/gateway-connection";
 
 export const dynamic = "force-dynamic";
 
-const AVATAR_DIRS = [
-  join(homedir(), ".castle", "avatars"),
-  join(homedir(), ".openclaw", "avatars"),
-];
+const EXTENSIONS = [".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg"];
 
 const MIME_TYPES: Record<string, string> = {
   ".png": "image/png",
@@ -19,10 +17,17 @@ const MIME_TYPES: Record<string, string> = {
   ".svg": "image/svg+xml",
 };
 
+const CACHE_HEADERS = { "Cache-Control": "public, max-age=3600" };
+
 /**
  * GET /api/avatars/[id]
- * Serves avatar images from ~/.castle/avatars/ or ~/.openclaw/avatars/
- * Supports IDs with or without extension (tries .png, .jpg, .webp)
+ *
+ * Proxies avatar images so they work from any device (mobile, Tailscale, etc).
+ *
+ * Resolution order:
+ *   1. Stored URL from Gateway → workspace path or HTTP fetch
+ *   2. Local file in ~/.castle/avatars/ or ~/.openclaw/avatars/
+ *   3. 404
  */
 export async function GET(
   _request: NextRequest,
@@ -30,46 +35,138 @@ export async function GET(
 ) {
   const { id } = await params;
 
-  // Sanitize -- prevent path traversal
+  // Sanitize
   const safeId = id.replace(/[^a-zA-Z0-9._-]/g, "");
   if (!safeId || safeId.includes("..")) {
     return new NextResponse("Not found", { status: 404 });
   }
 
-  // Try each avatar directory
-  for (const dir of AVATAR_DIRS) {
+  // 1. Try stored URL from Gateway
+  try {
+    const gw = ensureGateway();
+    const storedUrl = gw.getAvatarUrl(safeId);
+
+    if (storedUrl) {
+      // Workspace-relative: workspace:///absolute/path/to/workspace/avatars/file.png
+      if (storedUrl.startsWith("workspace://")) {
+        const pathPart = storedUrl.slice("workspace://".length);
+        // Resolve ~ in workspace path
+        const resolved = resolve(
+          pathPart.startsWith("~") ? join(homedir(), pathPart.slice(1)) : pathPart
+        );
+        // Prevent traversal: resolved path must not escape the workspace
+        // and must be a simple file path (no symlink-based escapes for known dirs)
+        if (
+          !resolved.includes("..") &&
+          !resolved.includes("\0") &&
+          existsSync(resolved)
+        ) {
+          return serveFile(resolved);
+        }
+      }
+      // HTTP(S) URL: fetch server-side and proxy
+      else if (storedUrl.startsWith("http://") || storedUrl.startsWith("https://")) {
+        const response = await fetchAvatar(storedUrl);
+        if (response) return response;
+      }
+    }
+  } catch {
+    // Gateway unavailable
+  }
+
+  // 2. Local avatar directories
+  const localDirs = [
+    join(homedir(), ".castle", "avatars"),
+    join(homedir(), ".openclaw", "avatars"),
+  ];
+
+  for (const dir of localDirs) {
     if (!existsSync(dir)) continue;
 
-    // Try exact filename first (if it has an extension)
-    const hasExtension = /\.\w+$/.test(safeId);
-    if (hasExtension) {
+    if (/\.\w+$/.test(safeId)) {
       const filePath = join(dir, safeId);
-      if (existsSync(filePath)) {
-        return serveFile(filePath);
-      }
+      if (existsSync(filePath)) return serveFile(filePath);
     }
 
-    // Try common extensions
-    for (const ext of [".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg"]) {
+    for (const ext of EXTENSIONS) {
       const filePath = join(dir, `${safeId}${ext}`);
-      if (existsSync(filePath)) {
-        return serveFile(filePath);
-      }
+      if (existsSync(filePath)) return serveFile(filePath);
     }
   }
 
   return new NextResponse("Not found", { status: 404 });
 }
 
+/**
+ * Check if a URL resolves to a private/internal IP range (SSRF protection).
+ * Blocks access to localhost, private networks, link-local, and cloud metadata.
+ */
+function isPrivateUrl(urlStr: string): boolean {
+  try {
+    const parsed = new URL(urlStr);
+    const hostname = parsed.hostname;
+
+    // Block cloud metadata endpoints
+    if (hostname === "169.254.169.254" || hostname === "metadata.google.internal") {
+      return true;
+    }
+
+    // Block localhost variants
+    if (
+      hostname === "localhost" ||
+      hostname === "127.0.0.1" ||
+      hostname === "::1" ||
+      hostname === "0.0.0.0"
+    ) {
+      return true;
+    }
+
+    // Block private IP ranges (10.x, 172.16-31.x, 192.168.x)
+    const parts = hostname.split(".").map(Number);
+    if (parts.length === 4 && parts.every((p) => !isNaN(p))) {
+      if (parts[0] === 10) return true;
+      if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) return true;
+      if (parts[0] === 192 && parts[1] === 168) return true;
+      if (parts[0] === 169 && parts[1] === 254) return true; // link-local
+    }
+
+    return false;
+  } catch {
+    return true; // Reject malformed URLs
+  }
+}
+
+/** Fetch an avatar from an HTTP URL with a short timeout and SSRF protection */
+async function fetchAvatar(url: string): Promise<NextResponse | null> {
+  // Block requests to private/internal networks
+  if (isPrivateUrl(url)) return null;
+
+  try {
+    const resp = await fetch(url, { signal: AbortSignal.timeout(2000) });
+    if (!resp.ok) return null;
+
+    const contentType = resp.headers.get("content-type") || "image/png";
+    if (!contentType.startsWith("image/")) return null;
+
+    // Limit response size to prevent memory exhaustion
+    const data = Buffer.from(await resp.arrayBuffer());
+    if (data.length > 5 * 1024 * 1024) return null; // 5MB max
+
+    return new NextResponse(data, {
+      headers: { "Content-Type": contentType, ...CACHE_HEADERS },
+    });
+  } catch {
+    return null;
+  }
+}
+
+/** Serve a local file with appropriate content type */
 function serveFile(filePath: string): NextResponse {
   const data = readFileSync(filePath);
   const ext = filePath.substring(filePath.lastIndexOf(".")).toLowerCase();
   const contentType = MIME_TYPES[ext] || "application/octet-stream";
 
   return new NextResponse(data, {
-    headers: {
-      "Content-Type": contentType,
-      "Cache-Control": "public, max-age=86400, immutable",
-    },
+    headers: { "Content-Type": contentType, ...CACHE_HEADERS },
   });
 }

package/src/app/api/openclaw/agents/[id]/avatar/route.ts

@@ -0,0 +1,216 @@
+import { NextRequest, NextResponse } from "next/server";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import JSON5 from "json5";
+import sharp from "sharp";
+import { ensureGateway } from "@/lib/gateway-connection";
+import { checkCsrf } from "@/lib/api-security";
+
+export const dynamic = "force-dynamic";
+
+const MAX_UPLOAD_SIZE = 5 * 1024 * 1024; // 5MB raw upload limit
+const AVATAR_SIZE = 256; // px (square)
+const MAX_OUTPUT_SIZE = 100 * 1024; // 100KB after processing
+
+const ALLOWED_TYPES = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/webp",
+  "image/gif",
+]);
+
+interface AgentConfig {
+  id: string;
+  workspace?: string;
+  identity?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+interface OpenClawConfig {
+  agents?: {
+    list?: AgentConfig[];
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+/**
+ * Resize and compress an avatar image to 256x256, under 100KB.
+ */
+async function processAvatar(input: Buffer): Promise<{ data: Buffer; ext: string }> {
+  const processed = sharp(input)
+    .resize(AVATAR_SIZE, AVATAR_SIZE, { fit: "cover", position: "centre" });
+
+  // Try PNG first (transparency support)
+  let data = await processed.png({ quality: 80, compressionLevel: 9 }).toBuffer();
+  if (data.length <= MAX_OUTPUT_SIZE) return { data, ext: ".png" };
+
+  // WebP (better compression, keeps transparency)
+  data = await processed.webp({ quality: 80 }).toBuffer();
+  if (data.length <= MAX_OUTPUT_SIZE) return { data, ext: ".webp" };
+
+  // JPEG with lower quality
+  data = await processed.jpeg({ quality: 70 }).toBuffer();
+  if (data.length <= MAX_OUTPUT_SIZE) return { data, ext: ".jpg" };
+
+  // Last resort
+  data = await processed.jpeg({ quality: 40 }).toBuffer();
+  return { data, ext: ".jpg" };
+}
+
+/**
+ * Find the OpenClaw config file path.
+ */
+function getOpenClawConfigPath(): string | null {
+  const paths = [
+    join(homedir(), ".openclaw", "openclaw.json"),
+    join(homedir(), ".openclaw", "openclaw.json5"),
+  ];
+  for (const p of paths) {
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * POST /api/openclaw/agents/[id]/avatar
+ *
+ * Upload a new avatar image for an agent.
+ * - Resizes to 256x256 and compresses under 100KB
+ * - Saves to the agent's workspace directory
+ * - Writes config file directly (Gateway hot-reloads identity changes, no restart needed)
+ */
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const csrfError = checkCsrf(request);
+  if (csrfError) return csrfError;
+
+  const { id: agentId } = await params;
+
+  const safeId = agentId.replace(/[^a-zA-Z0-9._-]/g, "");
+  if (!safeId) {
+    return NextResponse.json({ error: "Invalid agent ID" }, { status: 400 });
+  }
+
+  const formData = await request.formData();
+  const file = formData.get("avatar") as File | null;
+
+  if (!file) {
+    return NextResponse.json({ error: "No file provided" }, { status: 400 });
+  }
+
+  if (!ALLOWED_TYPES.has(file.type)) {
+    return NextResponse.json(
+      { error: "Unsupported format. Use PNG, JPEG, WebP, or GIF." },
+      { status: 400 }
+    );
+  }
+
+  if (file.size > MAX_UPLOAD_SIZE) {
+    return NextResponse.json(
+      { error: "File too large (max 5MB)" },
+      { status: 400 }
+    );
+  }
+
+  // Process image: resize to 256x256, compress to <100KB
+  let processed: { data: Buffer; ext: string };
+  try {
+    const rawBuffer = Buffer.from(await file.arrayBuffer());
+    processed = await processAvatar(rawBuffer);
+  } catch (err) {
+    return NextResponse.json(
+      { error: `Failed to process image: ${err instanceof Error ? err.message : "unknown"}` },
+      { status: 400 }
+    );
+  }
+
+  // Read the OpenClaw config file directly
+  const configPath = getOpenClawConfigPath();
+  if (!configPath) {
+    return NextResponse.json(
+      { error: "OpenClaw config file not found" },
+      { status: 500 }
+    );
+  }
+
+  let config: OpenClawConfig;
+  try {
+    config = JSON5.parse(readFileSync(configPath, "utf-8"));
+  } catch (err) {
+    return NextResponse.json(
+      { error: `Failed to read config: ${err instanceof Error ? err.message : "unknown"}` },
+      { status: 500 }
+    );
+  }
+
+  const agents = config.agents?.list || [];
+  const agent = agents.find((a) => a.id === safeId);
+
+  if (!agent) {
+    return NextResponse.json({ error: "Agent not found" }, { status: 404 });
+  }
+
+  if (!agent.workspace) {
+    return NextResponse.json(
+      { error: "Agent has no workspace configured" },
+      { status: 400 }
+    );
+  }
+
+  const workspacePath = agent.workspace.startsWith("~")
+    ? join(homedir(), agent.workspace.slice(1))
+    : agent.workspace;
+
+  // Save processed avatar to workspace
+  const avatarsDir = join(workspacePath, "avatars");
+  const fileName = `avatar${processed.ext}`;
+  const filePath = join(avatarsDir, fileName);
+
+  try {
+    mkdirSync(avatarsDir, { recursive: true, mode: 0o755 });
+    writeFileSync(filePath, processed.data);
+  } catch (err) {
+    return NextResponse.json(
+      { error: `Failed to save avatar: ${err instanceof Error ? err.message : "unknown"}` },
+      { status: 500 }
+    );
+  }
+
+  // Update config file directly — Gateway's file watcher hot-reloads identity changes
+  // No config.patch, no restart, no WebSocket disconnect
+  try {
+    agent.identity = agent.identity || {};
+    agent.identity.avatar = `avatars/${fileName}`;
+    writeFileSync(configPath, JSON5.stringify(config, null, 2), "utf-8");
+  } catch (err) {
+    return NextResponse.json(
+      { error: `Failed to update config: ${err instanceof Error ? err.message : "unknown"}` },
+      { status: 500 }
+    );
+  }
+
+  // Wait briefly for Gateway's file watcher to hot-reload (~300ms debounce)
+  await new Promise((resolve) => setTimeout(resolve, 500));
+
+  // Refresh Castle's agent list from the Gateway
+  try {
+    const gw = ensureGateway();
+    if (gw.isConnected) {
+      // Emit a signal so SSE clients re-fetch agents
+      gw.emit("agentAvatarUpdated", { agentId: safeId });
+    }
+  } catch {
+    // Non-critical
+  }
+
+  return NextResponse.json({
+    success: true,
+    avatar: `avatars/${fileName}`,
+    size: processed.data.length,
+    message: "Avatar updated",
+  });
+}

package/src/app/api/openclaw/agents/route.ts

@@ -24,34 +24,66 @@ interface AgentsListPayload {
   agents: GatewayAgent[];
 }
 
+interface AgentConfig {
+  id: string;
+  workspace?: string;
+}
+
+interface ConfigGetPayload {
+  hash: string;
+  parsed: {
+    agents?: {
+      list?: AgentConfig[];
+    };
+  };
+}
+
+/** Avatar URL patterns containing a hash */
+const AVATAR_HASH_PATTERNS = [
+  /\/api\/v\d+\/avatars\/([a-f0-9]+)/i,
+  /\/avatars\/([a-f0-9]+)/i,
+];
+
 /**
- * Rewrite avatar URLs to local /api/avatars/ endpoint.
- * Handles URLs like "http://localhost:8787/api/v1/avatars/HASH" -> "/api/avatars/HASH"
+ * Resolve an avatar value into a Castle-proxied URL.
+ *
+ * Handles three formats:
+ *   1. Data URI       → pass through (self-contained)
+ *   2. HTTP(S) URL    → proxy via /api/avatars/:key
+ *   3. Relative path  → proxy via /api/avatars/:key (resolved server-side against workspace)
  */
-function rewriteAvatarUrl(url: string | null): string | null {
-  if (!url) return null;
-
-  // Extract hash from known avatar URL patterns
-  const patterns = [
-    /\/api\/v\d+\/avatars\/([a-f0-9]+)/i,
-    /\/avatars\/([a-f0-9]+)/i,
-  ];
-
-  for (const pattern of patterns) {
-    const match = url.match(pattern);
-    if (match) {
-      return `/api/avatars/${match[1]}`;
+function resolveAvatarUrl(
+  avatar: string | null,
+  agentId: string,
+  workspace: string | undefined,
+  gw: ReturnType<typeof ensureGateway>,
+): string | null {
+  if (!avatar) return null;
+
+  // Data URIs are self-contained
+  if (avatar.startsWith("data:")) return avatar;
+
+  // HTTP(S) URL — proxy through Castle
+  if (avatar.startsWith("http://") || avatar.startsWith("https://")) {
+    // Try to extract a hash for a cleaner key
+    for (const pattern of AVATAR_HASH_PATTERNS) {
+      const match = avatar.match(pattern);
+      if (match) {
+        gw.setAvatarUrl(match[1], avatar);
+        return `/api/avatars/${match[1]}`;
+      }
     }
+    // No hash — use agent ID as key
+    const key = `agent-${agentId}`;
+    gw.setAvatarUrl(key, avatar);
+    return `/api/avatars/${key}`;
   }
 
-  // If it's already a relative path or data URI, pass through
-  if (url.startsWith("/") || url.startsWith("data:")) {
-    return url;
-  }
-
-  // Only allow http/https URLs through; reject file:, javascript:, etc.
-  if (url.startsWith("http://") || url.startsWith("https://")) {
-    return url;
+  // Relative path (e.g. "avatars/sam.png") — resolve against workspace
+  if (workspace && !avatar.startsWith("/")) {
+    const key = `agent-${agentId}`;
+    gw.setAvatarUrl(key, `workspace://${workspace}/${avatar}`);
+    return `/api/avatars/${key}`;
   }
 
   return null;
@@ -59,7 +91,8 @@ function rewriteAvatarUrl(url: string | null): string | null {
 
 /**
  * GET /api/openclaw/agents
- * Discover agents from OpenClaw Gateway via agents.list
+ * Discover agents from OpenClaw Gateway via agents.list,
+ * with workspace info from config.get for avatar resolution.
  */
 export async function GET() {
   const gw = ensureGateway();
@@ -72,31 +105,34 @@ export async function GET() {
   }
 
   try {
-    const result = await gw.request<AgentsListPayload>("agents.list", {});
+    // Fetch agents and config in parallel
+    const [agentsResult, configResult] = await Promise.all([
+      gw.request<AgentsListPayload>("agents.list", {}),
+      gw.request<ConfigGetPayload>("config.get", {}).catch(() => null),
+    ]);
+
+    // Build workspace lookup from config
+    const workspaceMap = new Map<string, string>();
+    if (configResult?.parsed?.agents?.list) {
+      for (const a of configResult.parsed.agents.list) {
+        if (a.workspace) workspaceMap.set(a.id, a.workspace);
+      }
+    }
 
-    const agents = (result?.agents || []).map((agent: GatewayAgent) => {
-      const name =
-        agent.identity?.name || agent.name || agent.id;
-      const rawAvatar =
-        agent.identity?.avatarUrl || agent.identity?.avatar || null;
+    const agents = (agentsResult?.agents || []).map((agent: GatewayAgent) => {
+      const name = agent.identity?.name || agent.name || agent.id;
+      const rawAvatar = agent.identity?.avatarUrl || agent.identity?.avatar || null;
       const emoji = agent.identity?.emoji || null;
       const description = agent.identity?.theme || null;
+      const workspace = workspaceMap.get(agent.id);
+      const avatar = resolveAvatarUrl(rawAvatar, agent.id, workspace, gw);
 
-      // Rewrite external avatar URLs to our local /api/avatars/ endpoint
-      const avatar = rewriteAvatarUrl(rawAvatar);
-
-      return {
-        id: agent.id,
-        name,
-        description,
-        avatar,
-        emoji,
-      };
+      return { id: agent.id, name, description, avatar, emoji };
     });
 
     return NextResponse.json({
       agents,
-      defaultId: result?.defaultId,
+      defaultId: agentsResult?.defaultId,
     });
   } catch (err) {
     return NextResponse.json(