Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

feat: add Discord-style agent sidebar folders for unpinned agents

Gusc4b53e66222b
diff --git a/src/web/src/components/app-sidebar.tsx b/src/web/src/components/app-sidebar.tsx
index 90a83ea1a..33a0508b6 100644
--- a/src/web/src/components/app-sidebar.tsx
+++ b/src/web/src/components/app-sidebar.tsx
@@ -8,7 +8,7 @@ import type { Agent } from "@alook/shared";
import { useInboxCount } from "@/contexts/inbox-count-context";
import { Logo } from "@/components/logo";
import { cn } from "@/lib/utils";
-import { Monitor, SunMoon, Plus, CalendarDays, Settings, PinIcon, PinOffIcon, ArrowLeftRight, Home, CircleDot, Inbox } from "lucide-react";
+import { Monitor, SunMoon, Plus, CalendarDays, Settings, ArrowLeftRight, Home, CircleDot, Inbox, Folder, Ungroup, ArrowRightToLine } from "lucide-react";
import { Skeleton } from "@/components/ui/skeleton";
import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/ui/tooltip";
import { useTheme } from "next-themes";
@@ -18,97 +18,19 @@ import {
ContextMenuTrigger,
ContextMenuContent,
ContextMenuItem,
+ ContextMenuSeparator,
} from "@/components/ui/context-menu";
-import { AgentPreviewCard } from "@/components/agent-preview-card";
-import { Popover, PopoverTrigger, PopoverContent } from "@/components/ui/popover";
import { parseAvatarUrl } from "@/components/avatar";
import { AnimatedAvatar } from "@/components/avatar/animated-avatar";
-import { DndContext, closestCenter, PointerSensor, useSensor, useSensors, type DragEndEvent } from "@dnd-kit/core";
+import { DndContext, closestCenter, PointerSensor, useSensor, useSensors, DragOverlay, type DragEndEvent, type DragStartEvent, type DragOverEvent } from "@dnd-kit/core";
import { restrictToVerticalAxis } from "@dnd-kit/modifiers";
import { SortableContext, verticalListSortingStrategy, useSortable, arrayMove } from "@dnd-kit/sortable";
import { CSS } from "@dnd-kit/utilities";
-
-function AgentSidebarButton({
- agent,
- isActive,
- isPinned,
- isOnline,
- taskCount,
- onClick,
- onPin,
- onUnpin,
-}: {
- agent: Agent;
- isActive: boolean;
- isPinned: boolean;
- isOnline: boolean;
- taskCount: number;
- onClick: () => void;
- onPin: () => void;
- onUnpin: () => void;
-}) {
- const [previewOpen, setPreviewOpen] = useState(false);
- return (
- <Popover
- open={previewOpen}
- onOpenChange={(open, event) => {
- if (open && event.reason === "trigger-press") return;
- setPreviewOpen(open);
- }}
- >
- <ContextMenu>
- <PopoverTrigger
- openOnHover
- delay={10}
- render={
- <ContextMenuTrigger
- render={
- <button
- type="button"
- onClick={() => { setPreviewOpen(false); onClick(); }}
- className={cn(
- "relative flex shrink-0 items-center justify-center size-10 rounded-xl text-sm font-medium transition-all duration-200 cursor-pointer",
- isActive
- ? "ring-2 ring-primary shadow-sm"
- : "ring-0 bg-secondary text-secondary-foreground hover:bg-accent"
- )}
- />
- }
- />
- }
- >
- {(() => {
- const avatarConfig = parseAvatarUrl(agent.avatar_url);
- if (avatarConfig) {
- return <AnimatedAvatar config={avatarConfig} size={40} className="rounded-xl" isHovered={false} />;
- }
- return agent.name.charAt(0).toUpperCase();
- })()}
- <span className={cn(
- "absolute bottom-0 right-0 size-2 rounded-full ring-2 ring-background",
- isOnline ? "bg-status-online" : "bg-status-offline"
- )} />
- </PopoverTrigger>
- <ContextMenuContent>
- {isPinned ? (
- <ContextMenuItem onClick={onUnpin}>
- <PinOffIcon className="size-3.5 mr-1.5" />
- Unpin
- </ContextMenuItem>
- ) : (
- <ContextMenuItem onClick={onPin}>
- <PinIcon className="size-3.5 mr-1.5" />
- Pin to top
- </ContextMenuItem>
- )}
- </ContextMenuContent>
- </ContextMenu>
- <PopoverContent side="right" className="w-fit max-w-80">
- <AgentPreviewCard agent={agent} isOnline={isOnline} activeTaskCount={taskCount} />
- </PopoverContent>
- </Popover>
- );
-}
+import { useAgentFolders } from "@/hooks/use-agent-folders";
+import { AgentSidebarButton } from "@/components/sidebar/agent-sidebar-button";
+import { SortableFolderItem } from "@/components/sidebar/sortable-folder-item";
+import { FolderCollapsed } from "@/components/sidebar/folder-collapsed";
+import { FolderPopover } from "@/components/sidebar/folder-popover";
function SortableAgentButton({ id, children }: { id: string; children: React.ReactNode }) {
const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({ id });
@@ -130,12 +52,32 @@ export function AppSidebar({ onNavigate }: { onNavigate?: () => void } = {}) {
const pathname = usePathname();
const searchParams = useSearchParams();
const { agents, runtimes, loading, pins, unpinnedOrder, handlePinAgent, handleUnpinAgent, handleReorderPins, handleReorderUnpinned } = useAgentContext();
- const { slug } = useWorkspace();
+ const { slug, workspaceId } = useWorkspace();
const { resolvedTheme, setTheme } = useTheme();
const { activeTaskCounts: taskCounts } = useAgentContext();
const { count: inboxCount } = useInboxCount();
+ // --- Folder state (applies to unpinned section only) ---
+ const {
+ folders,
+ expandedFolderId,
+ setExpandedFolderId,
+ createFolder,
+ addToFolder,
+ removeFromFolder,
+ dissolveFolder,
+ reorderInFolder,
+ cleanupStaleAgents,
+ getTopLevelItems,
+ removeAgentFromAnyFolder,
+ mergeFolders,
+ } = useAgentFolders(workspaceId);
+
+ // --- Selection mode for "Create group" ---
+ const [selectionMode, setSelectionMode] = useState(false);
+ const [selectedAgentIds, setSelectedAgentIds] = useState<Set<string>>(new Set());
+
const pinned = agents
.filter((a) => pins.has(a.id))
.sort((a, b) => pins.get(a.id)!.position - pins.get(b.id)!.position);
@@ -150,11 +92,44 @@ export function AppSidebar({ onNavigate }: { onNavigate?: () => void } = {}) {
return a.name.localeCompare(b.name);
});
+ // Folders apply to the unpinned section
+ const unpinnedIds = unpinned.map((a) => a.id);
+ const topLevelUnpinnedItems = getTopLevelItems(unpinnedIds);
+
+ // Cleanup stale agents when workspace agents change
+ useEffect(() => {
+ if (agents.length > 0) {
+ cleanupStaleAgents(agents.map((a) => a.id));
+ }
+ }, [agents, cleanupStaleAgents]);
+
+ // --- Drag-hold merge state (unpinned section) ---
+ const [dragActiveId, setDragActiveId] = useState<string | null>(null);
+ const [mergeTargetId, setMergeTargetId] = useState<string | null>(null);
+ const [sortingDisabled, setSortingDisabled] = useState(false);
+ const hoverTimerRef = useRef<ReturnType<typeof setTimeout>>(null);
+ const hoverTargetRef = useRef<string | null>(null);
+
+ useEffect(() => {
+ return () => {
+ if (hoverTimerRef.current) clearTimeout(hoverTimerRef.current);
+ };
+ }, []);
+
+ // --- Folder anchor refs for popover positioning ---
+ const folderAnchorRefs = useRef<Map<string, HTMLElement | null>>(new Map());
+
const sensors = useSensors(
useSensor(PointerSensor, { activationConstraint: { distance: 5 } })
);
- function handleDragEnd(event: DragEndEvent) {
+ // Build sortable IDs for unpinned: mix of agent IDs and folder IDs
+ const unpinnedSortableIds = topLevelUnpinnedItems.map((item) =>
+ item.type === "agent" ? item.id : item.folder.id
+ );
+
+ // --- Pinned section drag (unchanged, simple reorder) ---
+ function handlePinnedDragEnd(event: DragEndEvent) {
const { active, over } = event;
if (!over || active.id === over.id) return;
const oldIndex = pinned.findIndex((a) => a.id === active.id);
@@ -163,15 +138,111 @@ export function AppSidebar({ onNavigate }: { onNavigate?: () => void } = {}) {
handleReorderPins(reordered.map((a) => a.id));
}
+ // --- Unpinned section drag (with folder merge support) ---
+ function handleUnpinnedDragStart(event: DragStartEvent) {
+ setDragActiveId(event.active.id as string);
+ setExpandedFolderId(null);
+ }
+
+ function handleUnpinnedDragOver(event: DragOverEvent) {
+ const { over } = event;
+ if (!over) {
+ clearMergeTimer();
+ return;
+ }
+
+ const overId = over.id as string;
+ if (overId === dragActiveId) {
+ clearMergeTimer();
+ return;
+ }
+
+ if (hoverTargetRef.current !== overId) {
+ clearMergeTimer();
+ hoverTargetRef.current = overId;
+ hoverTimerRef.current = setTimeout(() => {
+ setSortingDisabled(true);
+ setMergeTargetId(overId);
+ }, 300);
+ }
+ }
+
+ function clearMergeTimer() {
+ if (hoverTimerRef.current) {
+ clearTimeout(hoverTimerRef.current);
+ hoverTimerRef.current = null;
+ }
+ hoverTargetRef.current = null;
+ setMergeTargetId(null);
+ setSortingDisabled(false);
+ }
+
function handleUnpinnedDragEnd(event: DragEndEvent) {
const { active, over } = event;
+ clearMergeTimer();
+ setDragActiveId(null);
+
if (!over || active.id === over.id) return;
- const oldIndex = unpinned.findIndex((a) => a.id === active.id);
- const newIndex = unpinned.findIndex((a) => a.id === over.id);
- const reordered = arrayMove(unpinned, oldIndex, newIndex);
- handleReorderUnpinned(reordered.map((a) => a.id));
+
+ const activeId = active.id as string;
+ const overId = over.id as string;
+
+ if (mergeTargetId === overId) {
+ handleMerge(activeId, overId);
+ setMergeTargetId(null);
+ return;
+ }
+
+ const oldIndex = unpinnedSortableIds.indexOf(activeId);
+ const newIndex = unpinnedSortableIds.indexOf(overId);
+ if (oldIndex === -1 || newIndex === -1) return;
+
+ const reordered = arrayMove(topLevelUnpinnedItems, oldIndex, newIndex);
+ const flatIds: string[] = [];
+ for (const item of reordered) {
+ if (item.type === "agent") {
+ flatIds.push(item.id);
+ } else {
+ flatIds.push(...item.folder.agentIds);
+ }
+ }
+ handleReorderUnpinned(flatIds);
+ }
+
+ function handleUnpinnedDragCancel() {
+ clearMergeTimer();
+ setDragActiveId(null);
}
+ function handleMerge(draggedId: string, targetId: string) {
+ const targetFolder = folders.find((f) => f.id === targetId);
+ if (targetFolder) {
+ const draggedFolder = folders.find((f) => f.id === draggedId);
+ if (draggedFolder) {
+ mergeFolders(draggedId, targetId);
+ } else {
+ removeAgentFromAnyFolder(draggedId);
+ addToFolder(targetId, draggedId);
+ }
+ } else {
+ const draggedFolder = folders.find((f) => f.id === draggedId);
+ if (draggedFolder) {
+ addToFolder(draggedId, targetId);
+ } else {
+ createFolder([targetId, draggedId]);
+ }
+ }
+ }
+
+ // Wrapped pin handler: removes agent from folder before pinning
+ const handlePinWithFolderCleanup = useCallback(
+ (agentId: string) => {
+ removeAgentFromAnyFolder(agentId);
+ handlePinAgent(agentId);
+ },
+ [removeAgentFromAnyFolder, handlePinAgent]
+ );
+
const prefix = `/w/${slug}`;
const isHome = pathname === `${prefix}/home`;
const isRuntimes = pathname === `${prefix}/runtimes`;
@@ -181,7 +252,6 @@ export function AppSidebar({ onNavigate }: { onNavigate?: () => void } = {}) {
const isSettings = pathname === `${prefix}/settings`;
const isCreateAgent = pathname === `${prefix}/agents/new`;
- // Detect active agent from ?agent= param or /w/[slug]/agents/[id] route
const urlAgentId = searchParams.get("agent");
const pathnameAgentMatch = pathname.match(/^\/w\/[^/]+\/agents\/([^/]+)/);
const activeAgentId = urlAgentId ?? pathnameAgentMatch?.[1] ?? null;
@@ -215,7 +285,15 @@ export function AppSidebar({ onNavigate }: { onNavigate?: () => void } = {}) {
}, total);
}, [pinned.length, unpinned.length]);
- const renderAgentButton = (agent: typeof agents[number], animIndex: number) => (
+ // Get the drag overlay content for the unpinned section
+ const dragActiveAgent = dragActiveId
+ ? agents.find((a) => a.id === dragActiveId)
+ : null;
+ const dragActiveFolder = dragActiveId
+ ? folders.find((f) => f.id === dragActiveId)
+ : null;
+
+ const renderAgentButton = (agent: typeof agents[number], animIndex: number, extraContextMenuItems?: React.ReactNode) => (
<div
className={cn(wiggling && "sidebar-agent-pop")}
style={wiggling ? { animationDelay: `${animIndex * 60}ms` } : undefined}
@@ -227,15 +305,82 @@ export function AppSidebar({ onNavigate }: { onNavigate?: () => void } = {}) {
isOnline={hasOnlineRuntime}
taskCount={taskCounts[agent.id] ?? 0}
onClick={() => handleAgentClick(agent.id)}
- onPin={() => handlePinAgent(agent.id)}
+ onPin={() => handlePinWithFolderCleanup(agent.id)}
onUnpin={() => handleUnpinAgent(agent.id)}
+ extraContextMenuItems={extraContextMenuItems}
/>
</div>
);
+ // Build folder-related context menu items for a standalone unpinned agent
+ const buildUnpinnedAgentContextMenu = (agentId: string) => (
+ <>
+ <ContextMenuSeparator />
+ <ContextMenuItem
+ onClick={() => {
+ setSelectedAgentIds(new Set([agentId]));
+ setSelectionMode(true);
+ }}
+ >
+ <Folder className="size-3.5 mr-1.5" />
+ Create group
+ </ContextMenuItem>
+ {folders.length > 0 && (
+ <>
+ {folders.map((f) => {
+ const folderAgents = f.agentIds
+ .map((id) => agents.find((a) => a.id === id))
+ .filter(Boolean) as Agent[];
+ const label = folderAgents
+ .slice(0, 2)
+ .map((a) => a.name)
+ .join(", ");
+ return (
+ <ContextMenuItem
+ key={f.id}
+ onClick={() => addToFolder(f.id, agentId)}
+ >
+ <ArrowRightToLine className="size-3.5 mr-1.5" />
+ Move to {label}{folderAgents.length > 2 ? "…" : ""}
+ </ContextMenuItem>
+ );
+ })}
+ </>
+ )}
+ </>
+ );
+
+ const handleSelectionConfirm = () => {
+ if (selectedAgentIds.size >= 2) {
+ createFolder(Array.from(selectedAgentIds));
+ }
+ setSelectionMode(false);
+ setSelectedAgentIds(new Set());
+ };
+
+ const handleSelectionCancel = () => {
+ setSelectionMode(false);
+ setSelectedAgentIds(new Set());
+ };
+
+ const toggleAgentSelection = (agentId: string) => {
+ setSelectedAgentIds((prev) => {
+ const next = new Set(prev);
+ if (next.has(agentId)) next.delete(agentId);
+ else next.add(agentId);
+ return next;
+ });
+ };
+
+ const closeFolderPopover = useCallback(() => setExpandedFolderId(null), [setExpandedFolderId]);
+
+ const expandedFolder = expandedFolderId
+ ? folders.find((f) => f.id === expandedFolderId) ?? null
+ : null;
+
return (
<nav className={cn("flex h-full w-14 flex-col items-center pt-1 pb-2 gap-0.5", wiggling && "relative z-10")}>
- {/* Top — logo (easter egg: click to wake agents) */}
+ {/* Top — logo */}
<div className="pb-1.5 mb-1">
<div
className="flex shrink-0 items-center justify-center size-8 [&>button]:pointer-events-none cursor-pointer active:scale-90 transition-transform"
@@ -328,7 +473,8 @@ export function AppSidebar({ onNavigate }: { onNavigate?: () => void } = {}) {
<Skeleton className="size-10 rounded-xl" />
) : (
<>
- <DndContext sensors={sensors} collisionDetection={closestCenter} modifiers={[restrictToVerticalAxis]} onDragEnd={handleDragEnd}>
+ {/* Pinned section (flat, no folders) */}
+ <DndContext sensors={sensors} collisionDetection={closestCenter} modifiers={[restrictToVerticalAxis]} onDragEnd={handlePinnedDragEnd}>
<SortableContext items={pinned.map((a) => a.id)} strategy={verticalListSortingStrategy}>
{pinned.map((agent, i) => (
<SortableAgentButton key={agent.id} id={agent.id}>
@@ -337,18 +483,147 @@ export function AppSidebar({ onNavigate }: { onNavigate?: () => void } = {}) {
))}
</SortableContext>
</DndContext>
+
{pinned.length > 0 && unpinned.length > 0 && (
<div className="w-6 border-t border-border/50" />
)}
- <DndContext sensors={sensors} collisionDetection={closestCenter} modifiers={[restrictToVerticalAxis]} onDragEnd={handleUnpinnedDragEnd}>
- <SortableContext items={unpinned.map((a) => a.id)} strategy={verticalListSortingStrategy}>
- {unpinned.map((agent, i) => (
- <SortableAgentButton key={agent.id} id={agent.id}>
- {renderAgentButton(agent, pinned.length + i)}
- </SortableAgentButton>
- ))}
+
+ {/* Unpinned section with folders */}
+ <DndContext
+ sensors={sensors}
+ collisionDetection={closestCenter}
+ modifiers={[restrictToVerticalAxis]}
+ onDragStart={handleUnpinnedDragStart}
+ onDragOver={handleUnpinnedDragOver}
+ onDragEnd={handleUnpinnedDragEnd}
+ onDragCancel={handleUnpinnedDragCancel}
+ >
+ <SortableContext items={unpinnedSortableIds} strategy={sortingDisabled ? undefined : verticalListSortingStrategy}>
+ {topLevelUnpinnedItems.map((item, i) => {
+ if (item.type === "folder") {
+ const folder = item.folder;
+ const isAnyActive = folder.agentIds.includes(activeAgentId ?? "");
+ return (
+ <ContextMenu key={folder.id}>
+ <ContextMenuTrigger render={<div />}>
+ <SortableFolderItem
+ folder={folder}
+ agents={agents}
+ isActive={isAnyActive}
+ isMergeTarget={mergeTargetId === folder.id}
+ dragActiveId={dragActiveId}
+ onExpand={() =>
+ setExpandedFolderId(
+ expandedFolderId === folder.id ? null : folder.id
+ )
+ }
+ nodeRefCallback={(el) =>
+ folderAnchorRefs.current.set(folder.id, el)
+ }
+ />
+ </ContextMenuTrigger>
+ <ContextMenuContent>
+ <ContextMenuItem onClick={() => dissolveFolder(folder.id)}>
+ <Ungroup className="size-3.5 mr-1.5" />
+ Ungroup agents
+ </ContextMenuItem>
+ </ContextMenuContent>
+ </ContextMenu>
+ );
+ }
+
+ // Standalone unpinned agent in selection mode
+ if (selectionMode) {
+ const agent = agents.find((a) => a.id === item.id);
+ if (!agent) return null;
+ const isSelected = selectedAgentIds.has(agent.id);
+ return (
+ <div
+ key={agent.id}
+ className="relative cursor-pointer"
+ onClick={() => toggleAgentSelection(agent.id)}
+ >
+ <div className={cn(
+ "transition-all duration-150",
+ isSelected && "ring-2 ring-primary rounded-xl"
+ )}>
+ {renderAgentButton(agent, pinned.length + i)}
+ </div>
+ {isSelected && (
+ <span className="absolute -top-0.5 -right-0.5 size-3 rounded-full bg-primary ring-2 ring-background" />
+ )}
+ </div>
+ );
+ }
+
+ // Standalone unpinned agent (normal mode)
+ const agent = agents.find((a) => a.id === item.id);
+ if (!agent) return null;
+ return (
+ <SortableAgentButton key={agent.id} id={agent.id}>
+ {mergeTargetId === agent.id && dragActiveId ? (
+ <FolderCollapsed
+ folder={{ id: "merge-preview", agentIds: [agent.id, dragActiveId] }}
+ agents={agents}
+ isActive={false}
+ onClick={() => {}}
+ />
+ ) : (
+ renderAgentButton(agent, pinned.length + i, buildUnpinnedAgentContextMenu(agent.id))
+ )}
+ </SortableAgentButton>
+ );
+ })}
</SortableContext>
+
+ <DragOverlay>
+ {dragActiveAgent ? (
+ <div className="opacity-80">
+ {(() => {
+ const avatarConfig = parseAvatarUrl(dragActiveAgent.avatar_url);
+ if (avatarConfig) {
+ return <AnimatedAvatar config={avatarConfig} size={40} className="rounded-xl" isHovered={false} />;
+ }
+ return (
+ <div className="flex items-center justify-center size-10 rounded-xl bg-secondary text-sm font-medium">
+ {dragActiveAgent.name.charAt(0).toUpperCase()}
+ </div>
+ );
+ })()}
+ </div>
+ ) : dragActiveFolder ? (
+ <div className="opacity-80">
+ <FolderCollapsed
+ folder={dragActiveFolder}
+ agents={agents}
+ isActive={false}
+ onClick={() => {}}
+ />
+ </div>
+ ) : null}
+ </DragOverlay>
</DndContext>
+
+ {/* Selection mode confirmation bar */}
+ {selectionMode && (
+ <div className="flex flex-col gap-1 w-full px-1">
+ <button
+ type="button"
+ onClick={handleSelectionConfirm}
+ disabled={selectedAgentIds.size < 2}
+ className="flex items-center justify-center h-7 rounded-lg bg-primary text-primary-foreground text-xs font-medium disabled:opacity-40 cursor-pointer disabled:cursor-not-allowed"
+ >
+ Done ({selectedAgentIds.size})
+ </button>
+ <button
+ type="button"
+ onClick={handleSelectionCancel}
+ className="flex items-center justify-center h-7 rounded-lg bg-secondary text-secondary-foreground text-xs cursor-pointer hover:bg-accent"
+ >
+ Cancel
+ </button>
+ </div>
+ )}
</>
)}
@@ -394,6 +669,27 @@ export function AppSidebar({ onNavigate }: { onNavigate?: () => void } = {}) {
)}
</div>
+ {/* Folder popover */}
+ {expandedFolder && (
+ <FolderPopover
+ folder={expandedFolder}
+ agents={agents}
+ activeAgentId={activeAgentId}
+ isOnline={hasOnlineRuntime}
+ taskCounts={taskCounts}
+ anchorRef={folderAnchorRefs.current.get(expandedFolder.id) ?? null}
+ onAgentClick={handleAgentClick}
+ onRemoveFromFolder={(agentId) =>
+ removeFromFolder(expandedFolder.id, agentId)
+ }
+ onPinAgent={handlePinWithFolderCleanup}
+ onReorder={(ordered) =>
+ reorderInFolder(expandedFolder.id, ordered)
+ }
+ onClose={closeFolderPopover}
+ />
+ )}
+
{/* Bottom section */}
<div className="flex flex-col items-center gap-1 pt-2 border-t border-border/50 mt-1">
<Tooltip>
diff --git a/src/web/src/components/sidebar/agent-sidebar-button.tsx b/src/web/src/components/sidebar/agent-sidebar-button.tsx
new file mode 100644
index 000000000..072bd7eef
--- /dev/null
+++ b/src/web/src/components/sidebar/agent-sidebar-button.tsx
@@ -0,0 +1,101 @@
+"use client";
+
+import { useState } from "react";
+import type { Agent } from "@alook/shared";
+import { cn } from "@/lib/utils";
+import { PinIcon, PinOffIcon } from "lucide-react";
+import {
+ ContextMenu,
+ ContextMenuTrigger,
+ ContextMenuContent,
+ ContextMenuItem,
+} from "@/components/ui/context-menu";
+import { AgentPreviewCard } from "@/components/agent-preview-card";
+import { Popover, PopoverTrigger, PopoverContent } from "@/components/ui/popover";
+import { parseAvatarUrl } from "@/components/avatar";
+import { AnimatedAvatar } from "@/components/avatar/animated-avatar";
+
+export function AgentSidebarButton({
+ agent,
+ isActive,
+ isPinned,
+ isOnline,
+ taskCount,
+ onClick,
+ onPin,
+ onUnpin,
+ extraContextMenuItems,
+}: {
+ agent: Agent;
+ isActive: boolean;
+ isPinned: boolean;
+ isOnline: boolean;
+ taskCount: number;
+ onClick: () => void;
+ onPin: () => void;
+ onUnpin: () => void;
+ extraContextMenuItems?: React.ReactNode;
+}) {
+ const [previewOpen, setPreviewOpen] = useState(false);
+ return (
+ <Popover
+ open={previewOpen}
+ onOpenChange={(open, event) => {
+ if (open && event.reason === "trigger-press") return;
+ setPreviewOpen(open);
+ }}
+ >
+ <ContextMenu>
+ <PopoverTrigger
+ openOnHover
+ delay={10}
+ render={
+ <ContextMenuTrigger
+ render={
+ <button
+ type="button"
+ onClick={() => { setPreviewOpen(false); onClick(); }}
+ className={cn(
+ "relative flex shrink-0 items-center justify-center size-10 rounded-xl text-sm font-medium transition-all duration-200 cursor-pointer",
+ isActive
+ ? "ring-2 ring-primary shadow-sm"
+ : "ring-0 bg-secondary text-secondary-foreground hover:bg-accent"
+ )}
+ />
+ }
+ />
+ }
+ >
+ {(() => {
+ const avatarConfig = parseAvatarUrl(agent.avatar_url);
+ if (avatarConfig) {
+ return <AnimatedAvatar config={avatarConfig} size={40} className="rounded-xl" isHovered={false} />;
+ }
+ return agent.name.charAt(0).toUpperCase();
+ })()}
+ <span className={cn(
+ "absolute bottom-0 right-0 size-2 rounded-full ring-2 ring-background",
+ isOnline ? "bg-status-online" : "bg-status-offline"
+ )} />
+ </PopoverTrigger>
+ <ContextMenuContent>
+ {isPinned ? (
+ <ContextMenuItem onClick={onUnpin}>
+ <PinOffIcon className="size-3.5 mr-1.5" />
+ Unpin
+ </ContextMenuItem>
+ ) : (
+ <ContextMenuItem onClick={onPin}>
+ <PinIcon className="size-3.5 mr-1.5" />
+ Pin to top
+ </ContextMenuItem>
+ )}
+ {extraContextMenuItems}
+ </ContextMenuContent>
+ </ContextMenu>
+ <PopoverContent side="right" className="w-fit max-w-80">
+ <AgentPreviewCard agent={agent} isOnline={isOnline} activeTaskCount={taskCount} />
+ </PopoverContent>
+ </Popover>
+ );
+}
diff --git a/src/web/src/components/sidebar/folder-collapsed.tsx b/src/web/src/components/sidebar/folder-collapsed.tsx
new file mode 100644
index 000000000..7db2b61f5
--- /dev/null
+++ b/src/web/src/components/sidebar/folder-collapsed.tsx
@@ -0,0 +1,74 @@
+"use client";
+
+import type { Agent } from "@alook/shared";
+import type { AgentFolder } from "@/hooks/use-agent-folders";
+import { parseAvatarUrl } from "@/components/avatar";
+import { AnimatedAvatar } from "@/components/avatar/animated-avatar";
+import { cn } from "@/lib/utils";
+
+const MAX_STACKED = 3;
+
+export function FolderCollapsed({
+ folder,
+ agents,
+ isActive,
+ onClick,
+}: {
+ folder: AgentFolder;
+ agents: Agent[];
+ isActive: boolean;
+ onClick: () => void;
+}) {
+ const folderAgents = folder.agentIds
+ .map((id) => agents.find((a) => a.id === id))
+ .filter(Boolean) as Agent[];
+
+ const displayed = folderAgents.slice(0, MAX_STACKED);
+ const remaining = folderAgents.length - displayed.length;
+
+ return (
+ <button
+ type="button"
+ onClick={onClick}
+ className={cn(
+ "relative flex shrink-0 items-center justify-center size-10 rounded-xl transition-all duration-200 cursor-pointer",
+ "bg-secondary/50 border border-border/30",
+ isActive
+ ? "ring-2 ring-primary shadow-sm"
+ : "hover:bg-accent"
+ )}
+ >
+ <div className="relative flex items-center justify-center" style={{ width: 30, height: 20 }}>
+ {displayed.map((agent, i) => {
+ const avatarConfig = parseAvatarUrl(agent.avatar_url);
+ const offset = i * 6;
+ return (
+ <div
+ key={agent.id}
+ className="absolute rounded-full overflow-hidden ring-1 ring-background"
+ style={{
+ width: 20,
+ height: 20,
+ left: offset,
+ zIndex: i + 1,
+ }}
+ >
+ {avatarConfig ? (
+ <AnimatedAvatar config={avatarConfig} size={20} className="rounded-full" isHovered={false} />
+ ) : (
+ <div className="flex items-center justify-center size-full bg-muted text-[8px] font-medium">
+ {agent.name.charAt(0).toUpperCase()}
+ </div>
+ )}
+ </div>
+ );
+ })}
+ </div>
+ {remaining > 0 && (
+ <span className="absolute bottom-0 right-0 flex items-center justify-center min-w-3.5 h-3.5 rounded-full bg-muted text-muted-foreground text-[8px] font-bold ring-1 ring-background">
+ +{remaining}
+ </span>
+ )}
+ </button>
+ );
+}
diff --git a/src/web/src/components/sidebar/folder-popover.tsx b/src/web/src/components/sidebar/folder-popover.tsx
new file mode 100644
index 000000000..01bb800b6
--- /dev/null
+++ b/src/web/src/components/sidebar/folder-popover.tsx
@@ -0,0 +1,197 @@
+"use client";
+
+import { useState, useRef, useEffect, useCallback } from "react";
+import type { Agent } from "@alook/shared";
+import type { AgentFolder } from "@/hooks/use-agent-folders";
+import { AgentSidebarButton } from "./agent-sidebar-button";
+import {
+ ContextMenuItem,
+ ContextMenuSeparator,
+} from "@/components/ui/context-menu";
+import { PinOffIcon } from "lucide-react";
+import {
+ DndContext,
+ closestCenter,
+ PointerSensor,
+ useSensor,
+ useSensors,
+ type DragEndEvent,
+} from "@dnd-kit/core";
+import { restrictToVerticalAxis } from "@dnd-kit/modifiers";
+import {
+ SortableContext,
+ verticalListSortingStrategy,
+ useSortable,
+ arrayMove,
+} from "@dnd-kit/sortable";
+import { CSS } from "@dnd-kit/utilities";
+
+function SortablePopoverAgent({
+ id,
+ children,
+}: {
+ id: string;
+ children: React.ReactNode;
+}) {
+ const {
+ attributes,
+ listeners,
+ setNodeRef,
+ transform,
+ transition,
+ isDragging,
+ } = useSortable({ id });
+ const style = {
+ transform: CSS.Transform.toString(transform),
+ transition,
+ opacity: isDragging ? 0.5 : 1,
+ zIndex: isDragging ? 10 : undefined,
+ };
+ return (
+ <div ref={setNodeRef} style={style} {...attributes} {...listeners}>
+ {children}
+ </div>
+ );
+}
+
+export function FolderPopover({
+ folder,
+ agents,
+ activeAgentId,
+ isOnline,
+ taskCounts,
+ anchorRef,
+ onAgentClick,
+ onRemoveFromFolder,
+ onPinAgent,
+ onReorder,
+ onClose,
+}: {
+ folder: AgentFolder;
+ agents: Agent[];
+ activeAgentId: string | null;
+ isOnline: boolean;
+ taskCounts: Record<string, number>;
+ anchorRef: HTMLElement | null;
+ onAgentClick: (agentId: string) => void;
+ onRemoveFromFolder: (agentId: string) => void;
+ onPinAgent: (agentId: string) => void;
+ onReorder: (orderedAgentIds: string[]) => void;
+ onClose: () => void;
+}) {
+ const popoverRef = useRef<HTMLDivElement>(null);
+ const [position, setPosition] = useState<{ left: number; top: number } | null>(null);
+
+ const updatePosition = useCallback(() => {
+ if (!anchorRef) return;
+ const rect = anchorRef.getBoundingClientRect();
+ setPosition({ left: rect.right + 8, top: rect.top });
+ }, [anchorRef]);
+
+ useEffect(() => {
+ updatePosition();
+ }, [updatePosition]);
+
+ useEffect(() => {
+ function handleClickOutside(e: MouseEvent) {
+ const target = e.target as Node;
+ if (
+ popoverRef.current &&
+ !popoverRef.current.contains(target) &&
+ anchorRef &&
+ !anchorRef.contains(target)
+ ) {
+ onClose();
+ }
+ }
+ function handleEscape(e: KeyboardEvent) {
+ if (e.key === "Escape") onClose();
+ }
+ const scrollParent = anchorRef?.closest("[class*='overflow']") ?? window;
+ document.addEventListener("mousedown", handleClickOutside);
+ document.addEventListener("keydown", handleEscape);
+ window.addEventListener("resize", updatePosition);
+ scrollParent.addEventListener("scroll", updatePosition, { passive: true });
+ return () => {
+ document.removeEventListener("mousedown", handleClickOutside);
+ document.removeEventListener("keydown", handleEscape);
+ window.removeEventListener("resize", updatePosition);
+ scrollParent.removeEventListener("scroll", updatePosition);
+ };
+ }, [anchorRef, onClose, updatePosition]);
+
+ const sensors = useSensors(
+ useSensor(PointerSensor, { activationConstraint: { distance: 5 } })
+ );
+
+ const folderAgents = folder.agentIds
+ .map((id) => agents.find((a) => a.id === id))
+ .filter(Boolean) as Agent[];
+
+ function handleDragEnd(event: DragEndEvent) {
+ const { active, over } = event;
+ if (!over || active.id === over.id) return;
+ const oldIndex = folder.agentIds.indexOf(active.id as string);
+ const newIndex = folder.agentIds.indexOf(over.id as string);
+ onReorder(arrayMove(folder.agentIds, oldIndex, newIndex));
+ }
+
+ if (!anchorRef || !position) return null;
+
+ return (
+ <div
+ ref={popoverRef}
+ className="fixed z-50 bg-popover border rounded-xl shadow-md p-1.5 animate-in fade-in-0 zoom-in-95"
+ style={{
+ left: position.left,
+ top: position.top,
+ }}
+ >
+ <DndContext
+ sensors={sensors}
+ collisionDetection={closestCenter}
+ modifiers={[restrictToVerticalAxis]}
+ onDragEnd={handleDragEnd}
+ >
+ <SortableContext
+ items={folder.agentIds}
+ strategy={verticalListSortingStrategy}
+ >
+ <div className="flex flex-col gap-1">
+ {folderAgents.map((agent) => (
+ <SortablePopoverAgent key={agent.id} id={agent.id}>
+ <AgentSidebarButton
+ agent={agent}
+ isActive={activeAgentId === agent.id}
+ isPinned={false}
+ isOnline={isOnline}
+ taskCount={taskCounts[agent.id] ?? 0}
+ onClick={() => {
+ onAgentClick(agent.id);
+ onClose();
+ }}
+ onPin={() => {
+ onPinAgent(agent.id);
+ onClose();
+ }}
+ onUnpin={() => {}}
+ extraContextMenuItems={
+ <>
+ <ContextMenuSeparator />
+ <ContextMenuItem
+ onClick={() => onRemoveFromFolder(agent.id)}
+ >
+ <PinOffIcon className="size-3.5 mr-1.5" />
+ Remove from group
+ </ContextMenuItem>
+ </>
+ }
+ />
+ </SortablePopoverAgent>
+ ))}
+ </div>
+ </SortableContext>
+ </DndContext>
+ </div>
+ );
+}
diff --git a/src/web/src/components/sidebar/sortable-folder-item.tsx b/src/web/src/components/sidebar/sortable-folder-item.tsx
new file mode 100644
index 000000000..768f0550e
--- /dev/null
+++ b/src/web/src/components/sidebar/sortable-folder-item.tsx
@@ -0,0 +1,64 @@
+"use client";
+
+import type { Agent } from "@alook/shared";
+import type { AgentFolder } from "@/hooks/use-agent-folders";
+import { useSortable } from "@dnd-kit/sortable";
+import { CSS } from "@dnd-kit/utilities";
+import { FolderCollapsed } from "./folder-collapsed";
+import { cn } from "@/lib/utils";
+
+export function SortableFolderItem({
+ folder,
+ agents,
+ isActive,
+ isMergeTarget,
+ dragActiveId,
+ onExpand,
+ nodeRefCallback,
+}: {
+ folder: AgentFolder;
+ agents: Agent[];
+ isActive: boolean;
+ isMergeTarget: boolean;
+ dragActiveId?: string | null;
+ onExpand: () => void;
+ nodeRefCallback?: (el: HTMLElement | null) => void;
+}) {
+ const {
+ attributes,
+ listeners,
+ setNodeRef,
+ transform,
+ transition,
+ isDragging,
+ } = useSortable({ id: folder.id });
+
+ const style = {
+ transform: CSS.Transform.toString(transform),
+ transition,
+ opacity: isDragging ? 0.5 : 1,
+ zIndex: isDragging ? 10 : undefined,
+ };
+
+ return (
+ <div
+ ref={(el) => {
+ setNodeRef(el);
+ nodeRefCallback?.(el);
+ }}
+ style={style}
+ {...attributes}
+ {...listeners}
+ className="transition-all duration-200"
+ >
+ <FolderCollapsed
+ folder={isMergeTarget && dragActiveId
+ ? { ...folder, agentIds: [...folder.agentIds, dragActiveId] }
+ : folder}
+ agents={agents}
+ isActive={isActive}
+ onClick={onExpand}
+ />
+ </div>
+ );
+}
diff --git a/src/web/src/hooks/__tests__/use-agent-folders.test.ts b/src/web/src/hooks/__tests__/use-agent-folders.test.ts
new file mode 100644
index 000000000..9e82a84e1
--- /dev/null
+++ b/src/web/src/hooks/__tests__/use-agent-folders.test.ts
@@ -0,0 +1,300 @@
+import { describe, it, expect } from "vitest";
+
+interface AgentFolder {
+ id: string;
+ agentIds: string[];
+}
+
+interface FolderState {
+ folders: AgentFolder[];
+}
+
+type TopLevelItem =
+ | { type: "agent"; id: string }
+ | { type: "folder"; folder: AgentFolder };
+
+// Pure logic extracted from the hook for testing
+
+function createFolder(prev: FolderState, agentIds: string[], folderId: string): FolderState {
+ if (agentIds.length < 2) return prev;
+ const existingAgentIds = new Set(prev.folders.flatMap((f) => f.agentIds));
+ const clean = agentIds.filter((a) => !existingAgentIds.has(a));
+ if (clean.length < 2) return prev;
+ return { folders: [...prev.folders, { id: folderId, agentIds: clean }] };
+}
+
+function addToFolder(prev: FolderState, folderId: string, agentId: string): FolderState {
+ const alreadyInFolder = prev.folders.some((f) => f.agentIds.includes(agentId));
+ if (alreadyInFolder) return prev;
+ return {
+ folders: prev.folders.map((f) =>
+ f.id === folderId ? { ...f, agentIds: [...f.agentIds, agentId] } : f
+ ),
+ };
+}
+
+function removeFromFolder(prev: FolderState, folderId: string, agentId: string): FolderState {
+ const updated = prev.folders.map((f) =>
+ f.id === folderId ? { ...f, agentIds: f.agentIds.filter((id) => id !== agentId) } : f
+ );
+ return { folders: updated.filter((f) => f.agentIds.length > 1) };
+}
+
+function dissolveFolder(prev: FolderState, folderId: string): FolderState {
+ return { folders: prev.folders.filter((f) => f.id !== folderId) };
+}
+
+function reorderInFolder(prev: FolderState, folderId: string, orderedAgentIds: string[]): FolderState {
+ return {
+ folders: prev.folders.map((f) =>
+ f.id === folderId ? { ...f, agentIds: orderedAgentIds } : f
+ ),
+ };
+}
+
+function mergeFolders(prev: FolderState, sourceFolderId: string, targetFolderId: string): FolderState {
+ const source = prev.folders.find((f) => f.id === sourceFolderId);
+ if (!source) return prev;
+ return {
+ folders: prev.folders
+ .map((f) =>
+ f.id === targetFolderId
+ ? { ...f, agentIds: [...f.agentIds, ...source.agentIds] }
+ : f
+ )
+ .filter((f) => f.id !== sourceFolderId),
+ };
+}
+
+function cleanupStaleAgents(prev: FolderState, validAgentIds: string[]): FolderState {
+ const valid = new Set(validAgentIds);
+ const cleaned = prev.folders.map((f) => ({
+ ...f,
+ agentIds: f.agentIds.filter((id) => valid.has(id)),
+ }));
+ return { folders: cleaned.filter((f) => f.agentIds.length > 1) };
+}
+
+function getFolderForAgent(folders: AgentFolder[], agentId: string): AgentFolder | null {
+ return folders.find((f) => f.agentIds.includes(agentId)) ?? null;
+}
+
+function getTopLevelItems(folders: AgentFolder[], agentIds: string[]): TopLevelItem[] {
+ const agentToFolder = new Map<string, AgentFolder>();
+ for (const f of folders) {
+ for (const aid of f.agentIds) {
+ agentToFolder.set(aid, f);
+ }
+ }
+
+ const seen = new Set<string>();
+ const items: TopLevelItem[] = [];
+
+ for (const agentId of agentIds) {
+ const folder = agentToFolder.get(agentId);
+ if (folder) {
+ if (!seen.has(folder.id)) {
+ seen.add(folder.id);
+ items.push({ type: "folder", folder });
+ }
+ } else {
+ items.push({ type: "agent", id: agentId });
+ }
+ }
+
+ return items;
+}
+
+describe("useAgentFolders logic", () => {
+ const empty: FolderState = { folders: [] };
+
+ describe("createFolder", () => {
+ it("creates a folder with given agent IDs", () => {
+ const result = createFolder(empty, ["a1", "a2"], "f1");
+ expect(result.folders).toHaveLength(1);
+ expect(result.folders[0]).toEqual({ id: "f1", agentIds: ["a1", "a2"] });
+ });
+
+ it("rejects creation with fewer than 2 agents", () => {
+ const result = createFolder(empty, ["a1"], "f1");
+ expect(result).toBe(empty);
+ });
+
+ it("excludes agents already in other folders", () => {
+ const state: FolderState = { folders: [{ id: "f1", agentIds: ["a1", "a2"] }] };
+ const result = createFolder(state, ["a1", "a3"], "f2");
+ expect(result).toBe(state); // a1 already in f1, only a3 left = < 2
+ });
+
+ it("creates folder from agents not yet in any folder", () => {
+ const state: FolderState = { folders: [{ id: "f1", agentIds: ["a1", "a2"] }] };
+ const result = createFolder(state, ["a3", "a4"], "f2");
+ expect(result.folders).toHaveLength(2);
+ expect(result.folders[1]).toEqual({ id: "f2", agentIds: ["a3", "a4"] });
+ });
+ });
+
+ describe("addToFolder", () => {
+ it("appends agent to existing folder", () => {
+ const state: FolderState = { folders: [{ id: "f1", agentIds: ["a1", "a2"] }] };
+ const result = addToFolder(state, "f1", "a3");
+ expect(result.folders[0].agentIds).toEqual(["a1", "a2", "a3"]);
+ });
+
+ it("does not add agent already in a folder", () => {
+ const state: FolderState = { folders: [{ id: "f1", agentIds: ["a1", "a2"] }] };
+ const result = addToFolder(state, "f1", "a1");
+ expect(result).toBe(state);
+ });
+ });
+
+ describe("mergeFolders", () => {
+ it("moves all agents from source to target and removes source", () => {
+ const state: FolderState = {
+ folders: [
+ { id: "f1", agentIds: ["a1", "a2"] },
+ { id: "f2", agentIds: ["a3", "a4"] },
+ ],
+ };
+ const result = mergeFolders(state, "f1", "f2");
+ expect(result.folders).toHaveLength(1);
+ expect(result.folders[0].id).toBe("f2");
+ expect(result.folders[0].agentIds).toEqual(["a3", "a4", "a1", "a2"]);
+ });
+
+ it("returns unchanged state if source folder not found", () => {
+ const state: FolderState = { folders: [{ id: "f1", agentIds: ["a1", "a2"] }] };
+ const result = mergeFolders(state, "nonexistent", "f1");
+ expect(result).toBe(state);
+ });
+ });
+
+ describe("removeFromFolder", () => {
+ it("removes agent from folder", () => {
+ const state: FolderState = { folders: [{ id: "f1", agentIds: ["a1", "a2", "a3"] }] };
+ const result = removeFromFolder(state, "f1", "a3");
+ expect(result.folders[0].agentIds).toEqual(["a1", "a2"]);
+ });
+
+ it("auto-dissolves folder when <= 1 agent remains", () => {
+ const state: FolderState = { folders: [{ id: "f1", agentIds: ["a1", "a2"] }] };
+ const result = removeFromFolder(state, "f1", "a2");
+ expect(result.folders).toHaveLength(0);
+ });
+ });
+
+ describe("dissolveFolder", () => {
+ it("removes the folder entirely", () => {
+ const state: FolderState = { folders: [{ id: "f1", agentIds: ["a1", "a2"] }] };
+ const result = dissolveFolder(state, "f1");
+ expect(result.folders).toHaveLength(0);
+ });
+
+ it("leaves other folders intact", () => {
+ const state: FolderState = {
+ folders: [
+ { id: "f1", agentIds: ["a1", "a2"] },
+ { id: "f2", agentIds: ["a3", "a4"] },
+ ],
+ };
+ const result = dissolveFolder(state, "f1");
+ expect(result.folders).toHaveLength(1);
+ expect(result.folders[0].id).toBe("f2");
+ });
+ });
+
+ describe("reorderInFolder", () => {
+ it("updates agent order within a folder", () => {
+ const state: FolderState = { folders: [{ id: "f1", agentIds: ["a1", "a2", "a3"] }] };
+ const result = reorderInFolder(state, "f1", ["a3", "a1", "a2"]);
+ expect(result.folders[0].agentIds).toEqual(["a3", "a1", "a2"]);
+ });
+ });
+
+ describe("cleanupStaleAgents", () => {
+ it("removes non-existent agent IDs", () => {
+ const state: FolderState = { folders: [{ id: "f1", agentIds: ["a1", "a2", "a3"] }] };
+ const result = cleanupStaleAgents(state, ["a1", "a3"]);
+ expect(result.folders[0].agentIds).toEqual(["a1", "a3"]);
+ });
+
+ it("auto-dissolves folders reduced to <= 1 agent", () => {
+ const state: FolderState = { folders: [{ id: "f1", agentIds: ["a1", "a2"] }] };
+ const result = cleanupStaleAgents(state, ["a1"]);
+ expect(result.folders).toHaveLength(0);
+ });
+
+ it("handles empty valid agents list", () => {
+ const state: FolderState = { folders: [{ id: "f1", agentIds: ["a1", "a2"] }] };
+ const result = cleanupStaleAgents(state, []);
+ expect(result.folders).toHaveLength(0);
+ });
+ });
+
+ describe("getFolderForAgent", () => {
+ it("returns the folder containing the agent", () => {
+ const folders: AgentFolder[] = [{ id: "f1", agentIds: ["a1", "a2"] }];
+ const result = getFolderForAgent(folders, "a2");
+ expect(result?.id).toBe("f1");
+ });
+
+ it("returns null if agent is not in any folder", () => {
+ const folders: AgentFolder[] = [{ id: "f1", agentIds: ["a1", "a2"] }];
+ const result = getFolderForAgent(folders, "a3");
+ expect(result).toBeNull();
+ });
+ });
+
+ describe("getTopLevelItems", () => {
+ it("returns flat list when no folders exist", () => {
+ const result = getTopLevelItems([], ["a1", "a2", "a3"]);
+ expect(result).toEqual([
+ { type: "agent", id: "a1" },
+ { type: "agent", id: "a2" },
+ { type: "agent", id: "a3" },
+ ]);
+ });
+
+ it("reconciles server pin order with folder groupings", () => {
+ const folders: AgentFolder[] = [{ id: "f1", agentIds: ["b", "c"] }];
+ const result = getTopLevelItems(folders, ["a", "b", "c", "d", "e"]);
+ expect(result).toEqual([
+ { type: "agent", id: "a" },
+ { type: "folder", folder: folders[0] },
+ { type: "agent", id: "d" },
+ { type: "agent", id: "e" },
+ ]);
+ });
+
+ it("places folder at position of its first agent in server order", () => {
+ const folders: AgentFolder[] = [{ id: "f1", agentIds: ["c", "a"] }];
+ // Server order: a, b, c — "a" appears first, so folder placed at a's position
+ const result = getTopLevelItems(folders, ["a", "b", "c"]);
+ expect(result).toEqual([
+ { type: "folder", folder: folders[0] },
+ { type: "agent", id: "b" },
+ ]);
+ });
+
+ it("handles multiple folders", () => {
+ const folders: AgentFolder[] = [
+ { id: "f1", agentIds: ["a", "b"] },
+ { id: "f2", agentIds: ["d", "e"] },
+ ];
+ const result = getTopLevelItems(folders, ["a", "b", "c", "d", "e"]);
+ expect(result).toEqual([
+ { type: "folder", folder: folders[0] },
+ { type: "agent", id: "c" },
+ { type: "folder", folder: folders[1] },
+ ]);
+ });
+
+ it("skips subsequent folder agents after the folder is placed", () => {
+ const folders: AgentFolder[] = [{ id: "f1", agentIds: ["a", "c"] }];
+ const result = getTopLevelItems(folders, ["a", "b", "c"]);
+ expect(result).toHaveLength(2);
+ expect(result[0]).toEqual({ type: "folder", folder: folders[0] });
+ expect(result[1]).toEqual({ type: "agent", id: "b" });
+ });
+ });
+});
diff --git a/src/web/src/hooks/use-agent-folders.ts b/src/web/src/hooks/use-agent-folders.ts
new file mode 100644
index 000000000..da8fa78d1
--- /dev/null
+++ b/src/web/src/hooks/use-agent-folders.ts
@@ -0,0 +1,206 @@
+"use client";
+
+import { useState, useCallback, useEffect, useMemo } from "react";
+import { useLocalStorage } from "./use-local-storage";
+
+export interface AgentFolder {
+ id: string;
+ agentIds: string[];
+}
+
+interface FolderState {
+ folders: AgentFolder[];
+}
+
+export type TopLevelItem =
+ | { type: "agent"; id: string }
+ | { type: "folder"; folder: AgentFolder };
+
+const EMPTY_STATE: FolderState = { folders: [] };
+
+export function useAgentFolders(workspaceId: string) {
+ const [state, setState] = useLocalStorage<FolderState>(
+ `agent-sidebar-folders:${workspaceId}`,
+ EMPTY_STATE
+ );
+ const [expandedFolderId, setExpandedFolderId] = useState<string | null>(null);
+
+ const folders = state.folders;
+
+ const getFolderForAgent = useCallback(
+ (agentId: string): AgentFolder | null =>
+ folders.find((f) => f.agentIds.includes(agentId)) ?? null,
+ [folders]
+ );
+
+ const createFolder = useCallback(
+ (agentIds: string[]) => {
+ if (agentIds.length < 2) return;
+ const id = crypto.randomUUID();
+ setState((prev) => {
+ const existingAgentIds = new Set(
+ prev.folders.flatMap((f) => f.agentIds)
+ );
+ const clean = agentIds.filter((a) => !existingAgentIds.has(a));
+ if (clean.length < 2) return prev;
+ return { folders: [...prev.folders, { id, agentIds: clean }] };
+ });
+ setExpandedFolderId(id);
+ },
+ [setState]
+ );
+
+ const addToFolder = useCallback(
+ (folderId: string, agentId: string) => {
+ setState((prev) => {
+ const alreadyInFolder = prev.folders.some((f) =>
+ f.agentIds.includes(agentId)
+ );
+ if (alreadyInFolder) return prev;
+ return {
+ folders: prev.folders.map((f) =>
+ f.id === folderId
+ ? { ...f, agentIds: [...f.agentIds, agentId] }
+ : f
+ ),
+ };
+ });
+ },
+ [setState]
+ );
+
+ const removeFromFolder = useCallback(
+ (folderId: string, agentId: string) => {
+ setState((prev) => {
+ const updated = prev.folders.map((f) =>
+ f.id === folderId
+ ? { ...f, agentIds: f.agentIds.filter((id) => id !== agentId) }
+ : f
+ );
+ return { folders: updated.filter((f) => f.agentIds.length > 1) };
+ });
+ },
+ [setState]
+ );
+
+ const dissolveFolder = useCallback(
+ (folderId: string) => {
+ setState((prev) => ({
+ folders: prev.folders.filter((f) => f.id !== folderId),
+ }));
+ if (expandedFolderId === folderId) setExpandedFolderId(null);
+ },
+ [setState, expandedFolderId]
+ );
+
+ const reorderInFolder = useCallback(
+ (folderId: string, orderedAgentIds: string[]) => {
+ setState((prev) => ({
+ folders: prev.folders.map((f) =>
+ f.id === folderId ? { ...f, agentIds: orderedAgentIds } : f
+ ),
+ }));
+ },
+ [setState]
+ );
+
+ const cleanupStaleAgents = useCallback(
+ (validAgentIds: string[]) => {
+ const valid = new Set(validAgentIds);
+ setState((prev) => {
+ const cleaned = prev.folders.map((f) => ({
+ ...f,
+ agentIds: f.agentIds.filter((id) => valid.has(id)),
+ }));
+ const surviving = cleaned.filter((f) => f.agentIds.length > 1);
+ const changed =
+ surviving.length !== prev.folders.length ||
+ prev.folders.some(
+ (f) => f.agentIds.some((id) => !valid.has(id))
+ );
+ return changed ? { folders: surviving } : prev;
+ });
+ },
+ [setState]
+ );
+
+ const getTopLevelItems = useCallback(
+ (agentIds: string[]): TopLevelItem[] => {
+ const agentToFolder = new Map<string, AgentFolder>();
+ for (const f of folders) {
+ for (const aid of f.agentIds) {
+ agentToFolder.set(aid, f);
+ }
+ }
+
+ const seen = new Set<string>();
+ const items: TopLevelItem[] = [];
+
+ for (const agentId of agentIds) {
+ const folder = agentToFolder.get(agentId);
+ if (folder) {
+ if (!seen.has(folder.id)) {
+ seen.add(folder.id);
+ items.push({ type: "folder", folder });
+ }
+ } else {
+ items.push({ type: "agent", id: agentId });
+ }
+ }
+
+ return items;
+ },
+ [folders]
+ );
+
+ const mergeFolders = useCallback(
+ (sourceFolderId: string, targetFolderId: string) => {
+ setState((prev) => {
+ const source = prev.folders.find((f) => f.id === sourceFolderId);
+ if (!source) return prev;
+ return {
+ folders: prev.folders
+ .map((f) =>
+ f.id === targetFolderId
+ ? { ...f, agentIds: [...f.agentIds, ...source.agentIds] }
+ : f
+ )
+ .filter((f) => f.id !== sourceFolderId),
+ };
+ });
+ },
+ [setState]
+ );
+
+ const removeAgentFromAnyFolder = useCallback(
+ (agentId: string) => {
+ setState((prev) => {
+ const folder = prev.folders.find((f) => f.agentIds.includes(agentId));
+ if (!folder) return prev;
+ const updated = prev.folders.map((f) =>
+ f.id === folder.id
+ ? { ...f, agentIds: f.agentIds.filter((id) => id !== agentId) }
+ : f
+ );
+ return { folders: updated.filter((f) => f.agentIds.length > 1) };
+ });
+ },
+ [setState]
+ );
+
+ return {
+ folders,
+ expandedFolderId,
+ setExpandedFolderId,
+ createFolder,
+ addToFolder,
+ removeFromFolder,
+ dissolveFolder,
+ reorderInFolder,
+ cleanupStaleAgents,
+ getFolderForAgent,
+ getTopLevelItems,
+ removeAgentFromAnyFolder,
+ mergeFolders,
+ };
+}