@castlekit/castle 0.3.2 → 0.4.1

package/.next/standalone/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "@castlekit/castle",
+  "version": "0.4.1",
+  "description": "The multi-agent workspace",
+  "type": "module",
+  "bin": {
+    "castle": "./bin/castle.js"
+  },
+  "files": [
+    ".next/standalone/",
+    ".next/static/",
+    "bin/",
+    "src/",
+    "public/",
+    "index.js",
+    "install.sh",
+    "install.ps1",
+    "next.config.ts",
+    "postcss.config.mjs",
+    "tsconfig.json",
+    "drizzle.config.ts",
+    "LICENSE",
+    "README.md",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.*"
+  ],
+  "scripts": {
+    "prepack": "next build && cp -r .next/static .next/standalone/.next/static && cp -r public .next/standalone/public 2>/dev/null || true && rm -rf .next/standalone/node_modules",
+    "dev": "next dev -p 3333",
+    "build": "next build",
+    "start": "next start -p 3333",
+    "lint": "next lint",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "stress": "vitest run --config vitest.stress.config.ts",
+    "ci": "npm audit --omit=dev --audit-level=high && npm test && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/castlekit/castle.git"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "openclaw",
+    "multi-agent",
+    "local-first"
+  ],
+  "author": "Castle Kit Inc.",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/castlekit/castle/issues"
+  },
+  "homepage": "https://castlekit.com",
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.0",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@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",
+    "next-themes": "^0.4.6",
+    "open": "^11.0.0",
+    "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",
+    "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/.next/standalone/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/.next/standalone/server.js

@@ -0,0 +1,44 @@
+performance.mark('next-start');
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import module from 'node:module'
+const require = module.createRequire(import.meta.url)
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+
+
+const dir = path.join(__dirname)
+
+process.env.NODE_ENV = 'production'
+process.chdir(__dirname)
+
+const currentPort = parseInt(process.env.PORT, 10) || 3000
+const hostname = process.env.HOSTNAME || '0.0.0.0'
+
+let keepAliveTimeout = parseInt(process.env.KEEP_ALIVE_TIMEOUT, 10)
+const nextConfig = {"env":{},"webpack":null,"typescript":{"ignoreBuildErrors":false},"typedRoutes":false,"distDir":"./.next","cleanDistDir":true,"assetPrefix":"","cacheMaxMemorySize":52428800,"configOrigin":"next.config.ts","useFileSystemPublicRoutes":true,"generateEtags":true,"pageExtensions":["tsx","ts","jsx","js"],"poweredByHeader":true,"compress":true,"images":{"deviceSizes":[640,750,828,1080,1200,1920,2048,3840],"imageSizes":[32,48,64,96,128,256,384],"path":"/_next/image","loader":"default","loaderFile":"","domains":[],"disableStaticImages":false,"minimumCacheTTL":14400,"formats":["image/webp"],"maximumRedirects":3,"maximumResponseBody":50000000,"dangerouslyAllowLocalIP":false,"dangerouslyAllowSVG":false,"contentSecurityPolicy":"script-src 'none'; frame-src 'none'; sandbox;","contentDispositionType":"attachment","localPatterns":[{"pathname":"**","search":""}],"remotePatterns":[],"qualities":[75],"unoptimized":false},"devIndicators":false,"onDemandEntries":{"maxInactiveAge":60000,"pagesBufferLength":5},"basePath":"","sassOptions":{},"trailingSlash":false,"i18n":null,"productionBrowserSourceMaps":false,"excludeDefaultMomentLocales":true,"reactProductionProfiling":false,"reactStrictMode":null,"reactMaxHeadersLength":6000,"httpAgentOptions":{"keepAlive":true},"logging":{},"compiler":{},"expireTime":31536000,"staticPageGenerationTimeout":60,"output":"standalone","modularizeImports":{"@mui/icons-material":{"transform":"@mui/icons-material/{{member}}"},"lodash":{"transform":"lodash/{{member}}"}},"outputFileTracingRoot":"/home/runner/work/castle/castle","cacheComponents":false,"cacheLife":{"default":{"stale":300,"revalidate":900,"expire":4294967294},"seconds":{"stale":30,"revalidate":1,"expire":60},"minutes":{"stale":300,"revalidate":60,"expire":3600},"hours":{"stale":300,"revalidate":3600,"expire":86400},"days":{"stale":300,"revalidate":86400,"expire":604800},"weeks":{"stale":300,"revalidate":604800,"expire":2592000},"max":{"stale":300,"revalidate":2592000,"expire":31536000}},"cacheHandlers":{},"experimental":{"useSkewCookie":false,"cssChunking":true,"multiZoneDraftMode":false,"appNavFailHandling":false,"prerenderEarlyExit":true,"serverMinification":true,"linkNoTouchStart":false,"caseSensitiveRoutes":false,"dynamicOnHover":false,"preloadEntriesOnStart":true,"clientRouterFilter":true,"clientRouterFilterRedirects":false,"fetchCacheKeyPrefix":"","proxyPrefetch":"flexible","optimisticClientCache":true,"manualClientBasePath":false,"cpus":3,"memoryBasedWorkersCount":false,"imgOptConcurrency":null,"imgOptTimeoutInSeconds":7,"imgOptMaxInputPixels":268402689,"imgOptSequentialRead":null,"imgOptSkipMetadata":null,"isrFlushToDisk":true,"workerThreads":false,"optimizeCss":false,"nextScriptWorkers":false,"scrollRestoration":false,"externalDir":false,"disableOptimizedLoading":false,"gzipSize":true,"craCompat":false,"esmExternals":true,"fullySpecified":false,"swcTraceProfiling":false,"forceSwcTransforms":false,"largePageDataBytes":128000,"typedEnv":false,"parallelServerCompiles":false,"parallelServerBuildTraces":false,"ppr":false,"authInterrupts":false,"webpackMemoryOptimizations":false,"optimizeServerReact":true,"viewTransition":false,"removeUncaughtErrorAndRejectionListeners":false,"validateRSCRequestHeaders":false,"staleTimes":{"dynamic":0,"static":300},"reactDebugChannel":false,"serverComponentsHmrCache":true,"staticGenerationMaxConcurrency":8,"staticGenerationMinPagesPerWorker":25,"transitionIndicator":false,"inlineCss":false,"useCache":false,"globalNotFound":false,"browserDebugInfoInTerminal":false,"lockDistDir":true,"isolatedDevBuild":true,"proxyClientMaxBodySize":10485760,"hideLogsAfterAbort":false,"mcpServer":true,"turbopackFileSystemCacheForDev":true,"turbopackFileSystemCacheForBuild":false,"turbopackInferModuleSideEffects":false,"optimizePackageImports":["lucide-react","date-fns","lodash-es","ramda","antd","react-bootstrap","ahooks","@ant-design/icons","@headlessui/react","@headlessui-float/react","@heroicons/react/20/solid","@heroicons/react/24/solid","@heroicons/react/24/outline","@visx/visx","@tremor/react","rxjs","@mui/material","@mui/icons-material","recharts","react-use","effect","@effect/schema","@effect/platform","@effect/platform-node","@effect/platform-browser","@effect/platform-bun","@effect/sql","@effect/sql-mssql","@effect/sql-mysql2","@effect/sql-pg","@effect/sql-sqlite-node","@effect/sql-sqlite-bun","@effect/sql-sqlite-wasm","@effect/sql-sqlite-react-native","@effect/rpc","@effect/rpc-http","@effect/typeclass","@effect/experimental","@effect/opentelemetry","@material-ui/core","@material-ui/icons","@tabler/icons-react","mui-core","react-icons/ai","react-icons/bi","react-icons/bs","react-icons/cg","react-icons/ci","react-icons/di","react-icons/fa","react-icons/fa6","react-icons/fc","react-icons/fi","react-icons/gi","react-icons/go","react-icons/gr","react-icons/hi","react-icons/hi2","react-icons/im","react-icons/io","react-icons/io5","react-icons/lia","react-icons/lib","react-icons/lu","react-icons/md","react-icons/pi","react-icons/ri","react-icons/rx","react-icons/si","react-icons/sl","react-icons/tb","react-icons/tfi","react-icons/ti","react-icons/vsc","react-icons/wi"],"trustHostHeader":false,"isExperimentalCompile":false},"htmlLimitedBots":"[\\w-]+-Google|Google-[\\w-]+|Chrome-Lighthouse|Slurp|DuckDuckBot|baiduspider|yandex|sogou|bitlybot|tumblr|vkShare|quora link preview|redditbot|ia_archiver|Bingbot|BingPreview|applebot|facebookexternalhit|facebookcatalog|Twitterbot|LinkedInBot|Slackbot|Discordbot|WhatsApp|SkypeUriPreview|Yeti|googleweblight","bundlePagesRouterDependencies":false,"configFileName":"next.config.ts","serverExternalPackages":["better-sqlite3"],"turbopack":{"root":"/home/runner/work/castle/castle"},"distDirRoot":".next"}
+
+process.env.__NEXT_PRIVATE_STANDALONE_CONFIG = JSON.stringify(nextConfig)
+
+require('next')
+const { startServer } = require('next/dist/server/lib/start-server')
+
+if (
+  Number.isNaN(keepAliveTimeout) ||
+  !Number.isFinite(keepAliveTimeout) ||
+  keepAliveTimeout < 0
+) {
+  keepAliveTimeout = undefined
+}
+
+startServer({
+  dir,
+  isDev: false,
+  config: nextConfig,
+  hostname,
+  port: currentPort,
+  allowRetry: false,
+  keepAliveTimeout,
+}).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

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

@@ -0,0 +1,172 @@
+import { NextRequest, NextResponse } from "next/server";
+import { readFileSync, existsSync } from "fs";
+import { join, resolve } from "path";
+import { homedir } from "os";
+import { ensureGateway } from "@/lib/gateway-connection";
+
+export const dynamic = "force-dynamic";
+
+const EXTENSIONS = [".png", ".jpg", ".jpeg", ".webp", ".gif", ".svg"];
+
+const MIME_TYPES: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".svg": "image/svg+xml",
+};
+
+const CACHE_HEADERS = { "Cache-Control": "public, max-age=3600" };
+
+/**
+ * GET /api/avatars/[id]
+ *
+ * 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,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+
+  // Sanitize
+  const safeId = id.replace(/[^a-zA-Z0-9._-]/g, "");
+  if (!safeId || safeId.includes("..")) {
+    return new NextResponse("Not found", { status: 404 });
+  }
+
+  // 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;
+
+    if (/\.\w+$/.test(safeId)) {
+      const filePath = join(dir, safeId);
+      if (existsSync(filePath)) return serveFile(filePath);
+    }
+
+    for (const ext of EXTENSIONS) {
+      const filePath = join(dir, `${safeId}${ext}`);
+      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_HEADERS },
+  });
+}

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