chore: format

- Updated the `LibraryAgentCard` component to include a focus ring on the link for improved accessibility.
- Refactored the test for navigating to an agent by clicking the link inside the card, ensuring reliable interaction through the draggable wrapper layers.
- Improved the visibility handling of the "Start Task" button in tests by waiting for it to be visible before clicking, enhancing test robustness.

These changes improve user experience and test reliability in the library interface.

autogpt_platform/backend/backend/api/features/library/db_test.py

@@ -144,6 +144,7 @@ async def test_add_agent_to_library(mocker):
     )
 
     mock_library_agent = mocker.patch("prisma.models.LibraryAgent.prisma")
+    mock_library_agent.return_value.find_first = mocker.AsyncMock(return_value=None)
     mock_library_agent.return_value.find_unique = mocker.AsyncMock(return_value=None)
     mock_library_agent.return_value.create = mocker.AsyncMock(
         return_value=mock_library_agent_data
@@ -178,7 +179,6 @@ async def test_add_agent_to_library(mocker):
                 "agentGraphVersion": 1,
             }
         },
-        include={"AgentGraph": True},
     )
     # Check that create was called with the expected data including settings
     create_call_args = mock_library_agent.return_value.create.call_args

autogpt_platform/backend/backend/api/features/library/exceptions.py

@@ -0,0 +1,10 @@
+class FolderValidationError(Exception):
+    """Raised when folder operations fail validation."""
+
+    pass
+
+
+class FolderAlreadyExistsError(FolderValidationError):
+    """Raised when a folder with the same name already exists in the location."""
+
+    pass

autogpt_platform/backend/backend/api/features/library/model.py

@@ -26,6 +26,95 @@ class LibraryAgentStatus(str, Enum):
     ERROR = "ERROR"
 
 
+# === Folder Models ===
+
+
+class LibraryFolder(pydantic.BaseModel):
+    """Represents a folder for organizing library agents."""
+
+    id: str
+    user_id: str
+    name: str
+    icon: str | None = None
+    color: str | None = None
+    parent_id: str | None = None
+    created_at: datetime.datetime
+    updated_at: datetime.datetime
+    agent_count: int = 0  # Direct agents in folder
+    subfolder_count: int = 0  # Direct child folders
+
+    @staticmethod
+    def from_db(
+        folder: prisma.models.LibraryFolder,
+        agent_count: int = 0,
+        subfolder_count: int = 0,
+    ) -> "LibraryFolder":
+        """Factory method that constructs a LibraryFolder from a Prisma model."""
+        return LibraryFolder(
+            id=folder.id,
+            user_id=folder.userId,
+            name=folder.name,
+            icon=folder.icon,
+            color=folder.color,
+            parent_id=folder.parentId,
+            created_at=folder.createdAt,
+            updated_at=folder.updatedAt,
+            agent_count=agent_count,
+            subfolder_count=subfolder_count,
+        )
+
+
+class LibraryFolderTree(LibraryFolder):
+    """Folder with nested children for tree view."""
+
+    children: list["LibraryFolderTree"] = []
+
+
+class FolderCreateRequest(pydantic.BaseModel):
+    """Request model for creating a folder."""
+
+    name: str = pydantic.Field(..., min_length=1, max_length=100)
+    icon: str | None = None
+    color: str | None = pydantic.Field(
+        None, pattern=r"^#[0-9A-Fa-f]{6}$", description="Hex color code (#RRGGBB)"
+    )
+    parent_id: str | None = None
+
+
+class FolderUpdateRequest(pydantic.BaseModel):
+    """Request model for updating a folder."""
+
+    name: str | None = pydantic.Field(None, min_length=1, max_length=100)
+    icon: str | None = None
+    color: str | None = None
+
+
+class FolderMoveRequest(pydantic.BaseModel):
+    """Request model for moving a folder to a new parent."""
+
+    target_parent_id: str | None = None  # None = move to root
+
+
+class BulkMoveAgentsRequest(pydantic.BaseModel):
+    """Request model for moving multiple agents to a folder."""
+
+    agent_ids: list[str]
+    folder_id: str | None = None  # None = move to root
+
+
+class FolderListResponse(pydantic.BaseModel):
+    """Response schema for a list of folders."""
+
+    folders: list[LibraryFolder]
+    pagination: Pagination
+
+
+class FolderTreeResponse(pydantic.BaseModel):
+    """Response schema for folder tree structure."""
+
+    tree: list[LibraryFolderTree]
+
+
 class MarketplaceListingCreator(pydantic.BaseModel):
     """Creator information for a marketplace listing."""
 
@@ -120,6 +209,9 @@ class LibraryAgent(pydantic.BaseModel):
     can_access_graph: bool
     is_latest_version: bool
     is_favorite: bool
+    folder_id: str | None = None
+    folder_name: str | None = None  # Denormalized for display
+
     recommended_schedule_cron: str | None = None
     settings: GraphSettings = pydantic.Field(default_factory=GraphSettings)
     marketplace_listing: Optional["MarketplaceListing"] = None
@@ -259,6 +351,8 @@ class LibraryAgent(pydantic.BaseModel):
             can_access_graph=can_access_graph,
             is_latest_version=is_latest_version,
             is_favorite=agent.isFavorite,
+            folder_id=agent.folderId,
+            folder_name=agent.Folder.name if agent.Folder else None,
             recommended_schedule_cron=agent.AgentGraph.recommendedScheduleCron,
             settings=_parse_settings(agent.settings),
             marketplace_listing=marketplace_listing_data,
@@ -470,3 +564,7 @@ class LibraryAgentUpdateRequest(pydantic.BaseModel):
     settings: Optional[GraphSettings] = pydantic.Field(
         default=None, description="User-specific settings for this library agent"
     )
+    folder_id: Optional[str] = pydantic.Field(
+        default=None,
+        description="Folder ID to move agent to (None to move to root)",
+    )

autogpt_platform/backend/backend/api/features/library/routes/__init__.py

@@ -1,9 +1,11 @@
 import fastapi
 
 from .agents import router as agents_router
+from .folders import router as folders_router
 from .presets import router as presets_router
 
 router = fastapi.APIRouter()
 
 router.include_router(presets_router)
+router.include_router(folders_router)
 router.include_router(agents_router)

autogpt_platform/backend/backend/api/features/library/routes/agents.py

@@ -41,6 +41,14 @@ async def list_library_agents(
         ge=1,
         description="Number of agents per page (must be >= 1)",
     ),
+    folder_id: Optional[str] = Query(
+        None,
+        description="Filter by folder ID",
+    ),
+    include_root_only: bool = Query(
+        False,
+        description="Only return agents without a folder (root-level agents)",
+    ),
 ) -> library_model.LibraryAgentResponse:
     """
     Get all agents in the user's library (both created and saved).
@@ -51,6 +59,8 @@ async def list_library_agents(
         sort_by=sort_by,
         page=page,
         page_size=page_size,
+        folder_id=folder_id,
+        include_root_only=include_root_only,
     )
 
 
@@ -168,6 +178,7 @@ async def update_library_agent(
         is_favorite=payload.is_favorite,
         is_archived=payload.is_archived,
         settings=payload.settings,
+        folder_id=payload.folder_id,
     )
 
 

autogpt_platform/backend/backend/api/features/library/routes/folders.py

@@ -0,0 +1,287 @@
+from typing import Optional
+
+import autogpt_libs.auth as autogpt_auth_lib
+from fastapi import APIRouter, Query, Security, status
+from fastapi.responses import Response
+
+from .. import db as library_db
+from .. import model as library_model
+
+router = APIRouter(
+    prefix="/folders",
+    tags=["library", "folders", "private"],
+    dependencies=[Security(autogpt_auth_lib.requires_user)],
+)
+
+
+@router.get(
+    "",
+    summary="List Library Folders",
+    response_model=library_model.FolderListResponse,
+    responses={
+        200: {"description": "List of folders"},
+        500: {"description": "Server error"},
+    },
+)
+async def list_folders(
+    user_id: str = Security(autogpt_auth_lib.get_user_id),
+    parent_id: Optional[str] = Query(
+        None,
+        description="Filter by parent folder ID. If not provided, returns root-level folders.",
+    ),
+    include_relations: bool = Query(
+        True,
+        description="Include agent and subfolder relations (for counts)",
+    ),
+) -> library_model.FolderListResponse:
+    """
+    List folders for the authenticated user.
+
+    Args:
+        user_id: ID of the authenticated user.
+        parent_id: Optional parent folder ID to filter by.
+        include_relations: Whether to include agent and subfolder relations for counts.
+
+    Returns:
+        A FolderListResponse containing folders.
+    """
+    folders = await library_db.list_folders(
+        user_id=user_id,
+        parent_id=parent_id,
+        include_relations=include_relations,
+    )
+    return library_model.FolderListResponse(
+        folders=folders,
+        pagination=library_model.Pagination(
+            total_items=len(folders),
+            total_pages=1,
+            current_page=1,
+            page_size=len(folders),
+        ),
+    )
+
+
+@router.get(
+    "/tree",
+    summary="Get Folder Tree",
+    response_model=library_model.FolderTreeResponse,
+    responses={
+        200: {"description": "Folder tree structure"},
+        500: {"description": "Server error"},
+    },
+)
+async def get_folder_tree(
+    user_id: str = Security(autogpt_auth_lib.get_user_id),
+) -> library_model.FolderTreeResponse:
+    """
+    Get the full folder tree for the authenticated user.
+
+    Args:
+        user_id: ID of the authenticated user.
+
+    Returns:
+        A FolderTreeResponse containing the nested folder structure.
+    """
+    tree = await library_db.get_folder_tree(user_id=user_id)
+    return library_model.FolderTreeResponse(tree=tree)
+
+
+@router.get(
+    "/{folder_id}",
+    summary="Get Folder",
+    response_model=library_model.LibraryFolder,
+    responses={
+        200: {"description": "Folder details"},
+        404: {"description": "Folder not found"},
+        500: {"description": "Server error"},
+    },
+)
+async def get_folder(
+    folder_id: str,
+    user_id: str = Security(autogpt_auth_lib.get_user_id),
+) -> library_model.LibraryFolder:
+    """
+    Get a specific folder.
+
+    Args:
+        folder_id: ID of the folder to retrieve.
+        user_id: ID of the authenticated user.
+
+    Returns:
+        The requested LibraryFolder.
+    """
+    return await library_db.get_folder(folder_id=folder_id, user_id=user_id)
+
+
+@router.post(
+    "",
+    summary="Create Folder",
+    status_code=status.HTTP_201_CREATED,
+    response_model=library_model.LibraryFolder,
+    responses={
+        201: {"description": "Folder created successfully"},
+        400: {"description": "Validation error"},
+        404: {"description": "Parent folder not found"},
+        409: {"description": "Folder name conflict"},
+        500: {"description": "Server error"},
+    },
+)
+async def create_folder(
+    payload: library_model.FolderCreateRequest,
+    user_id: str = Security(autogpt_auth_lib.get_user_id),
+) -> library_model.LibraryFolder:
+    """
+    Create a new folder.
+
+    Args:
+        payload: The folder creation request.
+        user_id: ID of the authenticated user.
+
+    Returns:
+        The created LibraryFolder.
+    """
+    return await library_db.create_folder(
+        user_id=user_id,
+        name=payload.name,
+        parent_id=payload.parent_id,
+        icon=payload.icon,
+        color=payload.color,
+    )
+
+
+@router.patch(
+    "/{folder_id}",
+    summary="Update Folder",
+    response_model=library_model.LibraryFolder,
+    responses={
+        200: {"description": "Folder updated successfully"},
+        400: {"description": "Validation error"},
+        404: {"description": "Folder not found"},
+        409: {"description": "Folder name conflict"},
+        500: {"description": "Server error"},
+    },
+)
+async def update_folder(
+    folder_id: str,
+    payload: library_model.FolderUpdateRequest,
+    user_id: str = Security(autogpt_auth_lib.get_user_id),
+) -> library_model.LibraryFolder:
+    """
+    Update a folder's properties.
+
+    Args:
+        folder_id: ID of the folder to update.
+        payload: The folder update request.
+        user_id: ID of the authenticated user.
+
+    Returns:
+        The updated LibraryFolder.
+    """
+    return await library_db.update_folder(
+        folder_id=folder_id,
+        user_id=user_id,
+        name=payload.name,
+        icon=payload.icon,
+        color=payload.color,
+    )
+
+
+@router.post(
+    "/{folder_id}/move",
+    summary="Move Folder",
+    response_model=library_model.LibraryFolder,
+    responses={
+        200: {"description": "Folder moved successfully"},
+        400: {"description": "Validation error (circular reference)"},
+        404: {"description": "Folder or target parent not found"},
+        409: {"description": "Folder name conflict in target location"},
+        500: {"description": "Server error"},
+    },
+)
+async def move_folder(
+    folder_id: str,
+    payload: library_model.FolderMoveRequest,
+    user_id: str = Security(autogpt_auth_lib.get_user_id),
+) -> library_model.LibraryFolder:
+    """
+    Move a folder to a new parent.
+
+    Args:
+        folder_id: ID of the folder to move.
+        payload: The move request with target parent.
+        user_id: ID of the authenticated user.
+
+    Returns:
+        The moved LibraryFolder.
+    """
+    return await library_db.move_folder(
+        folder_id=folder_id,
+        user_id=user_id,
+        target_parent_id=payload.target_parent_id,
+    )
+
+
+@router.delete(
+    "/{folder_id}",
+    summary="Delete Folder",
+    status_code=status.HTTP_204_NO_CONTENT,
+    responses={
+        204: {"description": "Folder deleted successfully"},
+        404: {"description": "Folder not found"},
+        500: {"description": "Server error"},
+    },
+)
+async def delete_folder(
+    folder_id: str,
+    user_id: str = Security(autogpt_auth_lib.get_user_id),
+) -> Response:
+    """
+    Soft-delete a folder and all its contents.
+
+    Args:
+        folder_id: ID of the folder to delete.
+        user_id: ID of the authenticated user.
+
+    Returns:
+        204 No Content if successful.
+    """
+    await library_db.delete_folder(
+        folder_id=folder_id,
+        user_id=user_id,
+        soft_delete=True,
+    )
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+# === Bulk Agent Operations ===
+
+
+@router.post(
+    "/agents/bulk-move",
+    summary="Bulk Move Agents",
+    response_model=list[library_model.LibraryAgent],
+    responses={
+        200: {"description": "Agents moved successfully"},
+        404: {"description": "Folder not found"},
+        500: {"description": "Server error"},
+    },
+)
+async def bulk_move_agents(
+    payload: library_model.BulkMoveAgentsRequest,
+    user_id: str = Security(autogpt_auth_lib.get_user_id),
+) -> list[library_model.LibraryAgent]:
+    """
+    Move multiple agents to a folder.
+
+    Args:
+        payload: The bulk move request with agent IDs and target folder.
+        user_id: ID of the authenticated user.
+
+    Returns:
+        The updated LibraryAgents.
+    """
+    return await library_db.bulk_move_agents_to_folder(
+        agent_ids=payload.agent_ids,
+        folder_id=payload.folder_id,
+        user_id=user_id,
+    )

autogpt_platform/backend/backend/api/features/library/routes_test.py

@@ -115,6 +115,8 @@ async def test_get_library_agents_success(
         sort_by=library_model.LibraryAgentSort.UPDATED_AT,
         page=1,
         page_size=15,
+        folder_id=None,
+        include_root_only=False,
     )
 
 

autogpt_platform/backend/backend/api/rest_api.py

@@ -41,6 +41,10 @@ import backend.data.user
 import backend.integrations.webhooks.utils
 import backend.util.service
 import backend.util.settings
+from backend.api.features.library.exceptions import (
+    FolderAlreadyExistsError,
+    FolderValidationError,
+)
 from backend.blocks.llm import DEFAULT_LLM_MODEL
 from backend.copilot.completion_consumer import (
     start_completion_consumer,
@@ -277,6 +281,10 @@ async def validation_error_handler(
 
 
 app.add_exception_handler(PrismaError, handle_internal_http_error(500))
+app.add_exception_handler(
+    FolderAlreadyExistsError, handle_internal_http_error(409, False)
+)
+app.add_exception_handler(FolderValidationError, handle_internal_http_error(400, False))
 app.add_exception_handler(NotFoundError, handle_internal_http_error(404, False))
 app.add_exception_handler(NotAuthorizedError, handle_internal_http_error(403, False))
 app.add_exception_handler(RequestValidationError, validation_error_handler)

autogpt_platform/backend/backend/copilot/config.py

@@ -27,7 +27,6 @@ class ChatConfig(BaseSettings):
     session_ttl: int = Field(default=43200, description="Session TTL in seconds")
 
     # Streaming Configuration
-    stream_timeout: int = Field(default=300, description="Stream timeout in seconds")
     max_retries: int = Field(
         default=3,
         description="Max retries for fallback path (SDK handles retries internally)",
@@ -39,8 +38,10 @@ class ChatConfig(BaseSettings):
 
     # Long-running operation configuration
     long_running_operation_ttl: int = Field(
-        default=600,
-        description="TTL in seconds for long-running operation tracking in Redis (safety net if pod dies)",
+        default=3600,
+        description="TTL in seconds for long-running operation deduplication lock "
+        "(1 hour, matches stream_ttl). Prevents duplicate operations if pod dies. "
+        "For longer operations, the stream_registry heartbeat keeps them alive.",
     )
 
     # Stream registry configuration for SSE reconnection
@@ -48,6 +49,11 @@ class ChatConfig(BaseSettings):
         default=3600,
         description="TTL in seconds for stream data in Redis (1 hour)",
     )
+    stream_lock_ttl: int = Field(
+        default=120,
+        description="TTL in seconds for stream lock (2 minutes). Short timeout allows "
+        "reconnection after refresh/crash without long waits.",
+    )
     stream_max_length: int = Field(
         default=10000,
         description="Maximum number of messages to store per stream",

autogpt_platform/backend/backend/copilot/db.py

@@ -3,8 +3,9 @@
 import asyncio
 import logging
 from datetime import UTC, datetime
-from typing import Any, cast
+from typing import Any
 
+from prisma.errors import UniqueViolationError
 from prisma.models import ChatMessage as PrismaChatMessage
 from prisma.models import ChatSession as PrismaChatSession
 from prisma.types import (
@@ -92,10 +93,9 @@ async def add_chat_message(
     function_call: dict[str, Any] | None = None,
 ) -> ChatMessage:
     """Add a message to a chat session."""
-    # Build input dict dynamically rather than using ChatMessageCreateInput directly
-    # because Prisma's TypedDict validation rejects optional fields set to None.
-    # We only include fields that have values, then cast at the end.
-    data: dict[str, Any] = {
+    # Build ChatMessageCreateInput with only non-None values
+    # (Prisma TypedDict rejects optional fields set to None)
+    data: ChatMessageCreateInput = {
         "Session": {"connect": {"id": session_id}},
         "role": role,
         "sequence": sequence,
@@ -123,7 +123,7 @@ async def add_chat_message(
             where={"id": session_id},
             data={"updatedAt": datetime.now(UTC)},
         ),
-        PrismaChatMessage.prisma().create(data=cast(ChatMessageCreateInput, data)),
+        PrismaChatMessage.prisma().create(data=data),
     )
     return ChatMessage.from_db(message)
 
@@ -132,58 +132,93 @@ async def add_chat_messages_batch(
     session_id: str,
     messages: list[dict[str, Any]],
     start_sequence: int,
-) -> list[ChatMessage]:
+) -> int:
     """Add multiple messages to a chat session in a batch.
 
-    Uses a transaction for atomicity - if any message creation fails,
-    the entire batch is rolled back.
+    Uses collision detection with retry: tries to create messages starting
+    at start_sequence. If a unique constraint violation occurs (e.g., the
+    streaming loop and long-running callback race), queries the latest
+    sequence and retries with the correct offset. This avoids unnecessary
+    upserts and DB queries in the common case (no collision).
+
+    Returns:
+        Next sequence number for the next message to be inserted. This equals
+        start_sequence + len(messages) and allows callers to update their
+        counters even when collision detection adjusts start_sequence.
     """
     if not messages:
-        return []
+        # No messages to add - return current count
+        return start_sequence
 
-    created_messages = []
+    max_retries = 5
+    for attempt in range(max_retries):
+        try:
+            # Single timestamp for all messages and session update
+            now = datetime.now(UTC)
 
-    async with db.transaction() as tx:
-        for i, msg in enumerate(messages):
-            # Build input dict dynamically rather than using ChatMessageCreateInput
-            # directly because Prisma's TypedDict validation rejects optional fields
-            # set to None. We only include fields that have values, then cast.
-            data: dict[str, Any] = {
-                "Session": {"connect": {"id": session_id}},
-                "role": msg["role"],
-                "sequence": start_sequence + i,
-            }
+            async with db.transaction() as tx:
+                # Build all message data
+                messages_data = []
+                for i, msg in enumerate(messages):
+                    # Build ChatMessageCreateInput with only non-None values
+                    # (Prisma TypedDict rejects optional fields set to None)
+                    # Note: create_many doesn't support nested creates, use sessionId directly
+                    data: ChatMessageCreateInput = {
+                        "sessionId": session_id,
+                        "role": msg["role"],
+                        "sequence": start_sequence + i,
+                        "createdAt": now,
+                    }
 
-            # Add optional string fields
-            if msg.get("content") is not None:
-                data["content"] = msg["content"]
-            if msg.get("name") is not None:
-                data["name"] = msg["name"]
-            if msg.get("tool_call_id") is not None:
-                data["toolCallId"] = msg["tool_call_id"]
-            if msg.get("refusal") is not None:
-                data["refusal"] = msg["refusal"]
+                    # Add optional string fields
+                    if msg.get("content") is not None:
+                        data["content"] = msg["content"]
+                    if msg.get("name") is not None:
+                        data["name"] = msg["name"]
+                    if msg.get("tool_call_id") is not None:
+                        data["toolCallId"] = msg["tool_call_id"]
+                    if msg.get("refusal") is not None:
+                        data["refusal"] = msg["refusal"]
 
-            # Add optional JSON fields only when they have values
-            if msg.get("tool_calls") is not None:
-                data["toolCalls"] = SafeJson(msg["tool_calls"])
-            if msg.get("function_call") is not None:
-                data["functionCall"] = SafeJson(msg["function_call"])
+                    # Add optional JSON fields only when they have values
+                    if msg.get("tool_calls") is not None:
+                        data["toolCalls"] = SafeJson(msg["tool_calls"])
+                    if msg.get("function_call") is not None:
+                        data["functionCall"] = SafeJson(msg["function_call"])
 
-            created = await PrismaChatMessage.prisma(tx).create(
-                data=cast(ChatMessageCreateInput, data)
-            )
-            created_messages.append(created)
+                    messages_data.append(data)
 
-        # Update session's updatedAt timestamp within the same transaction.
-        # Note: Token usage (total_prompt_tokens, total_completion_tokens) is updated
-        # separately via update_chat_session() after streaming completes.
-        await PrismaChatSession.prisma(tx).update(
-            where={"id": session_id},
-            data={"updatedAt": datetime.now(UTC)},
-        )
+                # Run create_many and session update in parallel within transaction
+                # Both use the same timestamp for consistency
+                await asyncio.gather(
+                    PrismaChatMessage.prisma(tx).create_many(data=messages_data),
+                    PrismaChatSession.prisma(tx).update(
+                        where={"id": session_id},
+                        data={"updatedAt": now},
+                    ),
+                )
 
-    return [ChatMessage.from_db(m) for m in created_messages]
+            # Return next sequence number for counter sync
+            return start_sequence + len(messages)
+
+        except UniqueViolationError:
+            if attempt < max_retries - 1:
+                # Collision detected - query MAX(sequence)+1 and retry with correct offset
+                logger.info(
+                    f"Collision detected for session {session_id} at sequence "
+                    f"{start_sequence}, querying DB for latest sequence"
+                )
+                start_sequence = await get_next_sequence(session_id)
+                logger.info(
+                    f"Retrying batch insert with start_sequence={start_sequence}"
+                )
+                continue
+            else:
+                # Max retries exceeded - propagate error
+                raise
+
+    # Should never reach here due to raise in exception handler
+    raise RuntimeError(f"Failed to insert messages after {max_retries} attempts")
 
 
 async def get_user_chat_sessions(
@@ -237,10 +272,20 @@ async def delete_chat_session(session_id: str, user_id: str | None = None) -> bo
         return False
 
 
-async def get_chat_session_message_count(session_id: str) -> int:
-    """Get the number of messages in a chat session."""
-    count = await PrismaChatMessage.prisma().count(where={"sessionId": session_id})
-    return count
+async def get_next_sequence(session_id: str) -> int:
+    """Get the next sequence number for a new message in this session.
+
+    Uses MAX(sequence) + 1 for robustness. Returns 0 if no messages exist.
+    More robust than COUNT(*) because it's immune to deleted messages.
+
+    Optimized to select only the sequence column using raw SQL.
+    The unique index on (sessionId, sequence) makes this query fast.
+    """
+    results = await db.query_raw_with_schema(
+        'SELECT "sequence" FROM {schema_prefix}"ChatMessage" WHERE "sessionId" = $1 ORDER BY "sequence" DESC LIMIT 1',
+        session_id,
+    )
+    return 0 if not results else results[0]["sequence"] + 1
 
 
 async def update_tool_message_content(

autogpt_platform/backend/backend/copilot/executor/processor.py

@@ -266,7 +266,11 @@ class CoPilotProcessor:
 
         except asyncio.CancelledError:
             log.info("Task cancelled")
-            await stream_registry.mark_task_completed(entry.task_id, status="failed")
+            await stream_registry.mark_task_completed(
+                entry.task_id,
+                status="failed",
+                error_message="Task was cancelled",
+            )
             raise
 
         except Exception as e:

autogpt_platform/backend/backend/copilot/model.py

@@ -432,7 +432,9 @@ async def _get_session_from_db(session_id: str) -> ChatSession | None:
     return session
 
 
-async def upsert_chat_session(session: ChatSession) -> ChatSession:
+async def upsert_chat_session(
+    session: ChatSession,
+) -> ChatSession:
     """Update a chat session in both cache and database.
 
     Uses session-level locking to prevent race conditions when concurrent
@@ -449,16 +451,18 @@ async def upsert_chat_session(session: ChatSession) -> ChatSession:
     lock = await _get_session_lock(session.session_id)
 
     async with lock:
-        # Get existing message count from DB for incremental saves
-        existing_message_count = await chat_db().get_chat_session_message_count(
-            session.session_id
-        )
+        # Always query DB for existing message count to ensure consistency
+        existing_message_count = await chat_db().get_next_sequence(session.session_id)
 
         db_error: Exception | None = None
 
         # Save to database (primary storage)
         try:
-            await _save_session_to_db(session, existing_message_count)
+            await _save_session_to_db(
+                session,
+                existing_message_count,
+                skip_existence_check=existing_message_count > 0,
+            )
         except Exception as e:
             logger.error(
                 f"Failed to save session {session.session_id} to database: {e}"
@@ -489,21 +493,31 @@ async def upsert_chat_session(session: ChatSession) -> ChatSession:
 
 
 async def _save_session_to_db(
-    session: ChatSession, existing_message_count: int
+    session: ChatSession,
+    existing_message_count: int,
+    *,
+    skip_existence_check: bool = False,
 ) -> None:
-    """Save or update a chat session in the database."""
+    """Save or update a chat session in the database.
+
+    Args:
+        skip_existence_check: When True, skip the ``get_chat_session`` query
+            and assume the session row already exists.  Saves one DB round trip
+            for incremental saves during streaming.
+    """
     db = chat_db()
 
-    # Check if session exists in DB
-    existing = await db.get_chat_session(session.session_id)
+    if not skip_existence_check:
+        # Check if session exists in DB
+        existing = await db.get_chat_session(session.session_id)
 
-    if not existing:
-        # Create new session
-        await db.create_chat_session(
-            session_id=session.session_id,
-            user_id=session.user_id,
-        )
-        existing_message_count = 0
+        if not existing:
+            # Create new session
+            await db.create_chat_session(
+                session_id=session.session_id,
+                user_id=session.user_id,
+            )
+            existing_message_count = 0
 
     # Calculate total tokens from usage
     total_prompt = sum(u.prompt_tokens for u in session.usage)
@@ -562,9 +576,7 @@ async def append_and_save_message(session_id: str, message: ChatMessage) -> Chat
             raise ValueError(f"Session {session_id} not found")
 
         session.messages.append(message)
-        existing_message_count = await chat_db().get_chat_session_message_count(
-            session_id
-        )
+        existing_message_count = await chat_db().get_next_sequence(session_id)
 
         try:
             await _save_session_to_db(session, existing_message_count)

autogpt_platform/backend/backend/copilot/model_test.py

@@ -331,3 +331,96 @@ def test_to_openai_messages_merges_split_assistants():
     tc_list = merged.get("tool_calls")
     assert tc_list is not None and len(list(tc_list)) == 1
     assert list(tc_list)[0]["id"] == "tc1"
+
+
+# --------------------------------------------------------------------------- #
+#  Concurrent save collision detection                                        #
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.asyncio(loop_scope="session")
+async def test_concurrent_saves_collision_detection(setup_test_user, test_user_id):
+    """Test that concurrent saves from streaming loop and callback handle collisions correctly.
+
+    Simulates the race condition where:
+    1. Streaming loop starts with saved_msg_count=5
+    2. Long-running callback appends message #5 and saves
+    3. Streaming loop tries to save with stale count=5
+
+    The collision detection should handle this gracefully.
+    """
+    import asyncio
+
+    # Create a session with initial messages
+    session = ChatSession.new(user_id=test_user_id)
+    for i in range(3):
+        session.messages.append(
+            ChatMessage(
+                role="user" if i % 2 == 0 else "assistant", content=f"Message {i}"
+            )
+        )
+
+    # Save initial messages
+    session = await upsert_chat_session(session)
+
+    # Simulate streaming loop and callback saving concurrently
+    async def streaming_loop_save():
+        """Simulates streaming loop saving messages."""
+        # Add 2 messages
+        session.messages.append(ChatMessage(role="user", content="Streaming message 1"))
+        session.messages.append(
+            ChatMessage(role="assistant", content="Streaming message 2")
+        )
+
+        # Wait a bit to let callback potentially save first
+        await asyncio.sleep(0.01)
+
+        # Save (will query DB for existing count)
+        return await upsert_chat_session(session)
+
+    async def callback_save():
+        """Simulates long-running callback saving a message."""
+        # Add 1 message
+        session.messages.append(
+            ChatMessage(role="tool", content="Callback result", tool_call_id="tc1")
+        )
+
+        # Save immediately (will query DB for existing count)
+        return await upsert_chat_session(session)
+
+    # Run both saves concurrently - one will hit collision detection
+    results = await asyncio.gather(streaming_loop_save(), callback_save())
+
+    # Both should succeed
+    assert all(r is not None for r in results)
+
+    # Reload session from DB to verify
+    from backend.data.redis_client import get_redis_async
+
+    redis_key = f"chat:session:{session.session_id}"
+    async_redis = await get_redis_async()
+    await async_redis.delete(redis_key)  # Clear cache to force DB load
+
+    loaded_session = await get_chat_session(session.session_id, test_user_id)
+    assert loaded_session is not None
+
+    # Should have all 6 messages (3 initial + 2 streaming + 1 callback)
+    assert len(loaded_session.messages) == 6
+
+    # Verify no duplicate sequences
+    sequences = []
+    for i, msg in enumerate(loaded_session.messages):
+        # Messages should have sequential sequence numbers starting from 0
+        sequences.append(i)
+
+    # All sequences should be unique and sequential
+    assert sequences == list(range(6))
+
+    # Verify message content is preserved
+    contents = [m.content for m in loaded_session.messages]
+    assert "Message 0" in contents
+    assert "Message 1" in contents
+    assert "Message 2" in contents
+    assert "Streaming message 1" in contents
+    assert "Streaming message 2" in contents
+    assert "Callback result" in contents

autogpt_platform/backend/backend/copilot/sdk/response_adapter.py

@@ -47,8 +47,9 @@ class SDKResponseAdapter:
     text blocks, tool calls, and message lifecycle.
     """
 
-    def __init__(self, message_id: str | None = None):
+    def __init__(self, message_id: str | None = None, session_id: str | None = None):
         self.message_id = message_id or str(uuid.uuid4())
+        self.session_id = session_id
         self.text_block_id = str(uuid.uuid4())
         self.has_started_text = False
         self.has_ended_text = False
@@ -61,6 +62,11 @@ class SDKResponseAdapter:
         """Set the task ID for reconnection support."""
         self.task_id = task_id
 
+    @property
+    def has_unresolved_tool_calls(self) -> bool:
+        """True when there are tool calls that haven't received output yet."""
+        return bool(self.current_tool_calls.keys() - self.resolved_tool_calls)
+
     def convert_message(self, sdk_message: Message) -> list[StreamBaseResponse]:
         """Convert a single SDK message to Vercel AI SDK format."""
         responses: list[StreamBaseResponse] = []
@@ -77,7 +83,12 @@ class SDKResponseAdapter:
         elif isinstance(sdk_message, AssistantMessage):
             # Flush any SDK built-in tool calls that didn't get a UserMessage
             # result (e.g. WebSearch, Read handled internally by the CLI).
-            self._flush_unresolved_tool_calls(responses)
+            # BUT skip flush when this AssistantMessage is a parallel tool
+            # continuation (contains only ToolUseBlocks) — the prior tools
+            # are still executing concurrently and haven't finished yet.
+            is_tool_only = all(isinstance(b, ToolUseBlock) for b in sdk_message.content)
+            if not is_tool_only:
+                self._flush_unresolved_tool_calls(responses)
 
             # After tool results, the SDK sends a new AssistantMessage for the
             # next LLM turn. Open a new step if the previous one was closed.
@@ -118,8 +129,24 @@ class SDKResponseAdapter:
             blocks = content if isinstance(content, list) else []
             resolved_in_blocks: set[str] = set()
 
+            sid = (self.session_id or "?")[:12]
+            parent_id_preview = getattr(sdk_message, "parent_tool_use_id", None)
+            logger.info(
+                "[SDK] [%s] UserMessage: %d blocks, content_type=%s, "
+                "parent_tool_use_id=%s",
+                sid,
+                len(blocks),
+                type(content).__name__,
+                parent_id_preview[:12] if parent_id_preview else "None",
+            )
+
             for block in blocks:
                 if isinstance(block, ToolResultBlock) and block.tool_use_id:
+                    # Skip if already resolved (e.g. by flush) — the real
+                    # result supersedes the empty flush, but re-emitting
+                    # would confuse the frontend's state machine.
+                    if block.tool_use_id in self.resolved_tool_calls:
+                        continue
                     tool_info = self.current_tool_calls.get(block.tool_use_id, {})
                     tool_name = tool_info.get("name", "unknown")
 
@@ -144,7 +171,11 @@ class SDKResponseAdapter:
             # Handle SDK built-in tool results carried via parent_tool_use_id
             # instead of (or in addition to) ToolResultBlock content.
             parent_id = sdk_message.parent_tool_use_id
-            if parent_id and parent_id not in resolved_in_blocks:
+            if (
+                parent_id
+                and parent_id not in resolved_in_blocks
+                and parent_id not in self.resolved_tool_calls
+            ):
                 tool_info = self.current_tool_calls.get(parent_id, {})
                 tool_name = tool_info.get("name", "unknown")
 
@@ -228,11 +259,28 @@ class SDKResponseAdapter:
         output, which we pop and emit here before the next ``AssistantMessage``
         starts.
         """
+        unresolved = [
+            (tid, info.get("name", "unknown"))
+            for tid, info in self.current_tool_calls.items()
+            if tid not in self.resolved_tool_calls
+        ]
+        sid = (self.session_id or "?")[:12]
+        if not unresolved:
+            logger.info(
+                "[SDK] [%s] Flush called but all %d tool(s) already resolved",
+                sid,
+                len(self.current_tool_calls),
+            )
+            return
+        logger.info(
+            "[SDK] [%s] Flushing %d unresolved tool call(s): %s",
+            sid,
+            len(unresolved),
+            ", ".join(f"{name}({tid[:12]})" for tid, name in unresolved),
+        )
+
         flushed = False
-        for tool_id, tool_info in self.current_tool_calls.items():
-            if tool_id in self.resolved_tool_calls:
-                continue
-            tool_name = tool_info.get("name", "unknown")
+        for tool_id, tool_name in unresolved:
             output = pop_pending_tool_output(tool_name)
             if output is not None:
                 responses.append(
@@ -245,9 +293,12 @@ class SDKResponseAdapter:
                 )
                 self.resolved_tool_calls.add(tool_id)
                 flushed = True
-                logger.debug(
-                    f"Flushed pending output for built-in tool {tool_name} "
-                    f"(call {tool_id})"
+                logger.info(
+                    "[SDK] [%s] Flushed stashed output for %s " "(call %s, %d chars)",
+                    sid,
+                    tool_name,
+                    tool_id[:12],
+                    len(output),
                 )
             else:
                 # No output available — emit an empty output so the frontend
@@ -263,9 +314,14 @@ class SDKResponseAdapter:
                 )
                 self.resolved_tool_calls.add(tool_id)
                 flushed = True
-                logger.debug(
-                    f"Flushed empty output for unresolved tool {tool_name} "
-                    f"(call {tool_id})"
+                logger.warning(
+                    "[SDK] [%s] Flushed EMPTY output for unresolved tool %s "
+                    "(call %s) — stash was empty (likely SDK hook race "
+                    "condition: PostToolUse hook hadn't completed before "
+                    "flush was triggered)",
+                    sid,
+                    tool_name,
+                    tool_id[:12],
                 )
 
         if flushed and self.step_open:

autogpt_platform/backend/backend/copilot/sdk/response_adapter_test.py

@@ -1,5 +1,8 @@
 """Unit tests for the SDK response adapter."""
 
+import asyncio
+
+import pytest
 from claude_agent_sdk import (
     AssistantMessage,
     ResultMessage,
@@ -27,6 +30,10 @@ from backend.copilot.response_model import (
 
 from .response_adapter import SDKResponseAdapter
 from .tool_adapter import MCP_TOOL_PREFIX
+from .tool_adapter import _pending_tool_outputs as _pto
+from .tool_adapter import _stash_event
+from .tool_adapter import stash_pending_tool_output as _stash
+from .tool_adapter import wait_for_stash
 
 
 def _adapter() -> SDKResponseAdapter:
@@ -364,3 +371,310 @@ def test_full_conversation_flow():
         "StreamFinishStep",  # step 2 closed
         "StreamFinish",
     ]
+
+
+# -- Flush unresolved tool calls --------------------------------------------
+
+
+def test_flush_unresolved_at_result_message():
+    """Built-in tools (WebSearch) without UserMessage results get flushed at ResultMessage."""
+    adapter = _adapter()
+    all_responses: list[StreamBaseResponse] = []
+
+    # 1. Init
+    all_responses.extend(
+        adapter.convert_message(SystemMessage(subtype="init", data={}))
+    )
+    # 2. Tool use (built-in tool — no MCP prefix)
+    all_responses.extend(
+        adapter.convert_message(
+            AssistantMessage(
+                content=[
+                    ToolUseBlock(id="ws-1", name="WebSearch", input={"query": "test"})
+                ],
+                model="test",
+            )
+        )
+    )
+    # 3. No UserMessage for this tool — go straight to ResultMessage
+    all_responses.extend(
+        adapter.convert_message(
+            ResultMessage(
+                subtype="success",
+                duration_ms=100,
+                duration_api_ms=50,
+                is_error=False,
+                num_turns=1,
+                session_id="s1",
+            )
+        )
+    )
+
+    types = [type(r).__name__ for r in all_responses]
+    assert types == [
+        "StreamStart",
+        "StreamStartStep",
+        "StreamToolInputStart",
+        "StreamToolInputAvailable",
+        "StreamToolOutputAvailable",  # flushed with empty output
+        "StreamFinishStep",  # step closed by flush
+        "StreamFinish",
+    ]
+    # The flushed output should be empty (no stash available)
+    output_event = [
+        r for r in all_responses if isinstance(r, StreamToolOutputAvailable)
+    ][0]
+    assert output_event.toolCallId == "ws-1"
+    assert output_event.toolName == "WebSearch"
+    assert output_event.output == ""
+
+
+def test_flush_unresolved_at_next_assistant_message():
+    """Built-in tools get flushed when the next AssistantMessage arrives."""
+    adapter = _adapter()
+    all_responses: list[StreamBaseResponse] = []
+
+    # 1. Init
+    all_responses.extend(
+        adapter.convert_message(SystemMessage(subtype="init", data={}))
+    )
+    # 2. Tool use (built-in — no UserMessage will come)
+    all_responses.extend(
+        adapter.convert_message(
+            AssistantMessage(
+                content=[
+                    ToolUseBlock(id="ws-1", name="WebSearch", input={"query": "test"})
+                ],
+                model="test",
+            )
+        )
+    )
+    # 3. Next AssistantMessage triggers flush before processing its blocks
+    all_responses.extend(
+        adapter.convert_message(
+            AssistantMessage(
+                content=[TextBlock(text="Here are the results")], model="test"
+            )
+        )
+    )
+
+    types = [type(r).__name__ for r in all_responses]
+    assert types == [
+        "StreamStart",
+        "StreamStartStep",
+        "StreamToolInputStart",
+        "StreamToolInputAvailable",
+        # Flush at next AssistantMessage:
+        "StreamToolOutputAvailable",
+        "StreamFinishStep",  # step closed by flush
+        # New step for continuation text:
+        "StreamStartStep",
+        "StreamTextStart",
+        "StreamTextDelta",
+    ]
+
+
+def test_flush_with_stashed_output():
+    """Stashed output from PostToolUse hook is used when flushing."""
+    adapter = _adapter()
+
+    # Simulate PostToolUse hook stashing output
+    _pto.set({})
+    _stash("WebSearch", "Search result: 5 items found")
+
+    all_responses: list[StreamBaseResponse] = []
+
+    # Tool use
+    all_responses.extend(
+        adapter.convert_message(
+            AssistantMessage(
+                content=[
+                    ToolUseBlock(id="ws-1", name="WebSearch", input={"query": "test"})
+                ],
+                model="test",
+            )
+        )
+    )
+    # ResultMessage triggers flush
+    all_responses.extend(
+        adapter.convert_message(
+            ResultMessage(
+                subtype="success",
+                duration_ms=100,
+                duration_api_ms=50,
+                is_error=False,
+                num_turns=1,
+                session_id="s1",
+            )
+        )
+    )
+
+    output_events = [
+        r for r in all_responses if isinstance(r, StreamToolOutputAvailable)
+    ]
+    assert len(output_events) == 1
+    assert output_events[0].output == "Search result: 5 items found"
+
+    # Cleanup
+    _pto.set({})  # type: ignore[arg-type]
+
+
+# -- wait_for_stash synchronisation tests --
+
+
+@pytest.mark.asyncio
+async def test_wait_for_stash_signaled():
+    """wait_for_stash returns True when stash_pending_tool_output signals."""
+    _pto.set({})
+    event = asyncio.Event()
+    _stash_event.set(event)
+
+    # Simulate a PostToolUse hook that stashes output after a short delay
+    async def delayed_stash():
+        await asyncio.sleep(0.01)
+        _stash("WebSearch", "result data")
+
+    asyncio.create_task(delayed_stash())
+    result = await wait_for_stash(timeout=1.0)
+
+    assert result is True
+    assert _pto.get({}).get("WebSearch") == ["result data"]
+
+    # Cleanup
+    _pto.set({})  # type: ignore[arg-type]
+    _stash_event.set(None)
+
+
+@pytest.mark.asyncio
+async def test_wait_for_stash_timeout():
+    """wait_for_stash returns False on timeout when no stash occurs."""
+    _pto.set({})
+    event = asyncio.Event()
+    _stash_event.set(event)
+
+    result = await wait_for_stash(timeout=0.05)
+    assert result is False
+
+    # Cleanup
+    _pto.set({})  # type: ignore[arg-type]
+    _stash_event.set(None)
+
+
+@pytest.mark.asyncio
+async def test_wait_for_stash_already_stashed():
+    """wait_for_stash picks up a stash that happened just before the wait."""
+    _pto.set({})
+    event = asyncio.Event()
+    _stash_event.set(event)
+
+    # Stash before waiting — simulates hook completing before message arrives
+    _stash("Read", "file contents")
+    # Event is now set; wait_for_stash detects the fast path and returns
+    # immediately without timing out.
+    result = await wait_for_stash(timeout=0.05)
+    assert result is True
+
+    # But the stash itself is populated
+    assert _pto.get({}).get("Read") == ["file contents"]
+
+    # Cleanup
+    _pto.set({})  # type: ignore[arg-type]
+    _stash_event.set(None)
+
+
+# -- Parallel tool call tests --
+
+
+def test_parallel_tool_calls_not_flushed_prematurely():
+    """Parallel tool calls should NOT be flushed when the next AssistantMessage
+    only contains ToolUseBlocks (parallel continuation)."""
+    adapter = SDKResponseAdapter()
+
+    # Init
+    adapter.convert_message(SystemMessage(subtype="init", data={}))
+
+    # First AssistantMessage: tool call #1
+    msg1 = AssistantMessage(
+        content=[ToolUseBlock(id="t1", name="WebSearch", input={"q": "foo"})],
+        model="test",
+    )
+    r1 = adapter.convert_message(msg1)
+    assert any(isinstance(r, StreamToolInputAvailable) for r in r1)
+    assert adapter.has_unresolved_tool_calls
+
+    # Second AssistantMessage: tool call #2 (parallel continuation)
+    msg2 = AssistantMessage(
+        content=[ToolUseBlock(id="t2", name="WebSearch", input={"q": "bar"})],
+        model="test",
+    )
+    r2 = adapter.convert_message(msg2)
+
+    # No flush should have happened — t1 should NOT have StreamToolOutputAvailable
+    output_events = [r for r in r2 if isinstance(r, StreamToolOutputAvailable)]
+    assert len(output_events) == 0, (
+        f"Tool-only AssistantMessage should not flush prior tools, "
+        f"but got {len(output_events)} output events"
+    )
+
+    # Both t1 and t2 should still be unresolved
+    assert "t1" not in adapter.resolved_tool_calls
+    assert "t2" not in adapter.resolved_tool_calls
+
+
+def test_text_assistant_message_flushes_prior_tools():
+    """An AssistantMessage with text (new turn) should flush unresolved tools."""
+    adapter = SDKResponseAdapter()
+
+    # Init
+    adapter.convert_message(SystemMessage(subtype="init", data={}))
+
+    # Tool call
+    msg1 = AssistantMessage(
+        content=[ToolUseBlock(id="t1", name="WebSearch", input={"q": "foo"})],
+        model="test",
+    )
+    adapter.convert_message(msg1)
+    assert adapter.has_unresolved_tool_calls
+
+    # Text AssistantMessage (new turn after tools completed)
+    msg2 = AssistantMessage(
+        content=[TextBlock(text="Here are the results")],
+        model="test",
+    )
+    r2 = adapter.convert_message(msg2)
+
+    # Flush SHOULD have happened — t1 gets empty output
+    output_events = [r for r in r2 if isinstance(r, StreamToolOutputAvailable)]
+    assert len(output_events) == 1
+    assert output_events[0].toolCallId == "t1"
+    assert "t1" in adapter.resolved_tool_calls
+
+
+def test_already_resolved_tool_skipped_in_user_message():
+    """A tool result in UserMessage should be skipped if already resolved by flush."""
+    adapter = SDKResponseAdapter()
+
+    adapter.convert_message(SystemMessage(subtype="init", data={}))
+
+    # Tool call + flush via text message
+    adapter.convert_message(
+        AssistantMessage(
+            content=[ToolUseBlock(id="t1", name="WebSearch", input={})],
+            model="test",
+        )
+    )
+    adapter.convert_message(
+        AssistantMessage(
+            content=[TextBlock(text="Done")],
+            model="test",
+        )
+    )
+    assert "t1" in adapter.resolved_tool_calls
+
+    # Now UserMessage arrives with the real result — should be skipped
+    user_msg = UserMessage(content=[ToolResultBlock(tool_use_id="t1", content="real")])
+    r = adapter.convert_message(user_msg)
+    output_events = [r_ for r_ in r if isinstance(r_, StreamToolOutputAvailable)]
+    assert (
+        len(output_events) == 0
+    ), "Already-resolved tool should not emit duplicate output"

autogpt_platform/backend/backend/copilot/sdk/sdk_compat_test.py

@@ -0,0 +1,194 @@
+"""SDK compatibility tests — verify the claude-agent-sdk public API surface we depend on.
+
+Instead of pinning to a narrow version range, these tests verify that the
+installed SDK exposes every class, function, attribute, and method the copilot
+integration relies on.  If an SDK upgrade removes or renames something these
+tests will catch it immediately.
+"""
+
+import inspect
+
+import pytest
+
+# ---------------------------------------------------------------------------
+# Public types & factories
+# ---------------------------------------------------------------------------
+
+
+def test_sdk_exports_client_and_options():
+    from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient
+
+    assert inspect.isclass(ClaudeSDKClient)
+    assert inspect.isclass(ClaudeAgentOptions)
+
+
+def test_sdk_exports_message_types():
+    from claude_agent_sdk import (
+        AssistantMessage,
+        Message,
+        ResultMessage,
+        SystemMessage,
+        UserMessage,
+    )
+
+    for cls in (AssistantMessage, ResultMessage, SystemMessage, UserMessage):
+        assert inspect.isclass(cls), f"{cls.__name__} is not a class"
+    # Message is a Union type alias, just verify it's importable
+    assert Message is not None
+
+
+def test_sdk_exports_content_block_types():
+    from claude_agent_sdk import TextBlock, ToolResultBlock, ToolUseBlock
+
+    for cls in (TextBlock, ToolResultBlock, ToolUseBlock):
+        assert inspect.isclass(cls), f"{cls.__name__} is not a class"
+
+
+def test_sdk_exports_mcp_helpers():
+    from claude_agent_sdk import create_sdk_mcp_server, tool
+
+    assert callable(create_sdk_mcp_server)
+    assert callable(tool)
+
+
+# ---------------------------------------------------------------------------
+# ClaudeSDKClient interface
+# ---------------------------------------------------------------------------
+
+
+def test_client_has_required_methods():
+    from claude_agent_sdk import ClaudeSDKClient
+
+    required = ["connect", "disconnect", "query", "receive_messages"]
+    for name in required:
+        attr = getattr(ClaudeSDKClient, name, None)
+        assert attr is not None, f"ClaudeSDKClient.{name} missing"
+        assert callable(attr), f"ClaudeSDKClient.{name} is not callable"
+
+
+def test_client_supports_async_context_manager():
+    from claude_agent_sdk import ClaudeSDKClient
+
+    assert hasattr(ClaudeSDKClient, "__aenter__")
+    assert hasattr(ClaudeSDKClient, "__aexit__")
+
+
+# ---------------------------------------------------------------------------
+# ClaudeAgentOptions fields
+# ---------------------------------------------------------------------------
+
+
+def test_agent_options_accepts_required_fields():
+    """Verify ClaudeAgentOptions accepts all kwargs our code passes."""
+    from claude_agent_sdk import ClaudeAgentOptions
+
+    opts = ClaudeAgentOptions(
+        system_prompt="test",
+        cwd="/tmp",
+    )
+    assert opts.system_prompt == "test"
+    assert opts.cwd == "/tmp"
+
+
+def test_agent_options_accepts_all_our_fields():
+    """Comprehensive check of every field we use in service.py."""
+    from claude_agent_sdk import ClaudeAgentOptions
+
+    fields_we_use = [
+        "system_prompt",
+        "mcp_servers",
+        "allowed_tools",
+        "disallowed_tools",
+        "hooks",
+        "cwd",
+        "model",
+        "env",
+        "resume",
+        "max_buffer_size",
+    ]
+    sig = inspect.signature(ClaudeAgentOptions)
+    for field in fields_we_use:
+        assert field in sig.parameters, (
+            f"ClaudeAgentOptions no longer accepts '{field}' — "
+            f"available params: {list(sig.parameters.keys())}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Message attributes
+# ---------------------------------------------------------------------------
+
+
+def test_assistant_message_has_content_and_model():
+    from claude_agent_sdk import AssistantMessage, TextBlock
+
+    msg = AssistantMessage(content=[TextBlock(text="hi")], model="test")
+    assert hasattr(msg, "content")
+    assert hasattr(msg, "model")
+
+
+def test_result_message_has_required_attrs():
+    from claude_agent_sdk import ResultMessage
+
+    msg = ResultMessage(
+        subtype="success",
+        duration_ms=100,
+        duration_api_ms=50,
+        is_error=False,
+        num_turns=1,
+        session_id="s1",
+    )
+    assert msg.subtype == "success"
+    assert hasattr(msg, "result")
+
+
+def test_system_message_has_subtype_and_data():
+    from claude_agent_sdk import SystemMessage
+
+    msg = SystemMessage(subtype="init", data={})
+    assert msg.subtype == "init"
+    assert msg.data == {}
+
+
+def test_user_message_has_parent_tool_use_id():
+    from claude_agent_sdk import UserMessage
+
+    msg = UserMessage(content="test")
+    assert hasattr(msg, "parent_tool_use_id")
+    assert hasattr(msg, "tool_use_result")
+
+
+def test_tool_use_block_has_id_name_input():
+    from claude_agent_sdk import ToolUseBlock
+
+    block = ToolUseBlock(id="t1", name="test", input={"key": "val"})
+    assert block.id == "t1"
+    assert block.name == "test"
+    assert block.input == {"key": "val"}
+
+
+def test_tool_result_block_has_required_attrs():
+    from claude_agent_sdk import ToolResultBlock
+
+    block = ToolResultBlock(tool_use_id="t1", content="result")
+    assert block.tool_use_id == "t1"
+    assert block.content == "result"
+    assert hasattr(block, "is_error")
+
+
+# ---------------------------------------------------------------------------
+# Hook types
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "hook_event",
+    ["PreToolUse", "PostToolUse", "Stop"],
+)
+def test_sdk_exports_hook_event_type(hook_event: str):
+    """Verify HookEvent literal includes the events our security_hooks use."""
+    from claude_agent_sdk.types import HookEvent
+
+    # HookEvent is a Literal type — check that our events are valid values.
+    # We can't easily inspect Literal at runtime, so just verify the type exists.
+    assert HookEvent is not None

autogpt_platform/backend/backend/copilot/sdk/security_hooks.py

@@ -246,15 +246,33 @@ def create_security_hooks(
             """
             _ = context
             tool_name = cast(str, input_data.get("tool_name", ""))
-            logger.debug(f"[SDK] Tool success: {tool_name}, tool_use_id={tool_use_id}")
+            is_builtin = not tool_name.startswith(MCP_TOOL_PREFIX)
+            logger.info(
+                "[SDK] PostToolUse: %s (builtin=%s, tool_use_id=%s)",
+                tool_name,
+                is_builtin,
+                (tool_use_id or "")[:12],
+            )
 
             # Stash output for SDK built-in tools so the response adapter can
             # emit StreamToolOutputAvailable even when the CLI doesn't surface
             # a separate UserMessage with ToolResultBlock content.
-            if not tool_name.startswith(MCP_TOOL_PREFIX):
+            if is_builtin:
                 tool_response = input_data.get("tool_response")
                 if tool_response is not None:
+                    resp_preview = str(tool_response)[:100]
+                    logger.info(
+                        "[SDK] Stashing builtin output for %s (%d chars): %s...",
+                        tool_name,
+                        len(str(tool_response)),
+                        resp_preview,
+                    )
                     stash_pending_tool_output(tool_name, tool_response)
+                else:
+                    logger.warning(
+                        "[SDK] PostToolUse for builtin %s but tool_response is None",
+                        tool_name,
+                    )
 
             return cast(SyncHookJSONOutput, {})
 

autogpt_platform/backend/backend/copilot/sdk/service.py

@@ -7,8 +7,10 @@ import os
 import uuid
 from collections.abc import AsyncGenerator
 from dataclasses import dataclass
-from typing import Any
+from typing import Any, cast
 
+from backend.data.redis_client import get_redis_async
+from backend.executor.cluster_lock import AsyncClusterLock
 from backend.util.exceptions import NotFoundError
 
 from .. import stream_registry
@@ -24,6 +26,7 @@ from ..response_model import (
     StreamBaseResponse,
     StreamError,
     StreamFinish,
+    StreamFinishStep,
     StreamHeartbeat,
     StreamStart,
     StreamTextDelta,
@@ -46,6 +49,7 @@ from .tool_adapter import (
     LongRunningCallback,
     create_copilot_mcp_server,
     set_execution_context,
+    wait_for_stash,
 )
 from .transcript import (
     cleanup_cli_project_dir,
@@ -59,6 +63,7 @@ from .transcript import (
 logger = logging.getLogger(__name__)
 config = ChatConfig()
 
+
 # Set to hold background tasks to prevent garbage collection
 _background_tasks: set[asyncio.Task[Any]] = set()
 
@@ -130,8 +135,12 @@ is delivered to the user via a background stream.
   All tasks must run in the foreground.
 """
 
+STREAM_LOCK_PREFIX = "copilot:stream:lock:"
 
-def _build_long_running_callback(user_id: str | None) -> LongRunningCallback:
+
+def _build_long_running_callback(
+    user_id: str | None,
+) -> LongRunningCallback:
     """Build a callback that delegates long-running tools to the non-SDK infrastructure.
 
     Long-running tools (create_agent, edit_agent, etc.) are delegated to the
@@ -140,6 +149,9 @@ def _build_long_running_callback(user_id: str | None) -> LongRunningCallback:
     page refreshes / pod restarts, and the frontend shows the proper loading
     widget with progress updates.
 
+    Args:
+        user_id: User ID for the session
+
     The returned callback matches the ``LongRunningCallback`` signature:
     ``(tool_name, args, session) -> MCP response dict``.
     """
@@ -205,7 +217,8 @@ def _build_long_running_callback(user_id: str | None) -> LongRunningCallback:
             tool_call_id=tool_call_id,
         )
         session.messages.append(pending_message)
-        await upsert_chat_session(session)
+        # Collision detection happens in add_chat_messages_batch (db.py)
+        session = await upsert_chat_session(session)
 
         # --- Spawn background task (reuses non-SDK infrastructure) ---
         bg_task = asyncio.create_task(
@@ -344,15 +357,15 @@ async def _compress_conversation_history(
 
     Returns the compressed prior messages (everything except the current message).
     """
-    prior = session.messages[:-1]
-    if len(prior) < 2:
-        return prior
+    messages = session.messages[:-1]
+    if len(messages) < 2:
+        return messages
 
     from backend.util.prompt import compress_context
 
     # Convert ChatMessages to dicts for compress_context
     messages_dict = []
-    for msg in prior:
+    for msg in messages:
         msg_dict: dict[str, Any] = {"role": msg.role}
         if msg.content:
             msg_dict["content"] = msg.content
@@ -400,7 +413,7 @@ async def _compress_conversation_history(
             for m in result.messages
         ]
 
-    return prior
+    return messages
 
 
 def _format_conversation_context(messages: list[ChatMessage]) -> str | None:
@@ -442,8 +455,8 @@ def _format_conversation_context(messages: list[ChatMessage]) -> str | None:
 def _is_tool_error_or_denial(content: str | None) -> bool:
     """Check if a tool message content indicates an error or denial.
 
-    We include these in conversation context so the agent doesn't
-    hallucinate success for operations that actually failed.
+    Currently unused — ``_format_conversation_context`` includes all tool
+    results.  Kept as a utility for future selective filtering.
     """
     if not content:
         return False
@@ -458,7 +471,7 @@ def _is_tool_error_or_denial(content: str | None) -> bool:
             "maximum",  # subtask-limit denial
             "denied",
             "blocked",
-            "failed",  # internal tool execution failures
+            "failed to",  # internal tool execution failures
             '"iserror": true',  # MCP protocol error flag
         )
     )
@@ -525,6 +538,9 @@ async def stream_chat_completion_sdk(
             f"Session {session_id} not found. Please create a new session first."
         )
 
+    # Type narrowing: session is guaranteed ChatSession after the check above
+    session = cast(ChatSession, session)
+
     # Append the new message to the session if it's not already there
     new_message_role = "user" if is_user_message else "assistant"
     if message and (
@@ -562,6 +578,29 @@ async def stream_chat_completion_sdk(
     system_prompt += _SDK_TOOL_SUPPLEMENT
     message_id = str(uuid.uuid4())
     task_id = str(uuid.uuid4())
+    stream_id = task_id  # Use task_id as unique stream identifier
+
+    # Acquire stream lock to prevent concurrent streams to the same session
+    lock = AsyncClusterLock(
+        redis=await get_redis_async(),
+        key=f"{STREAM_LOCK_PREFIX}{session_id}",
+        owner_id=stream_id,
+        timeout=config.stream_lock_ttl,
+    )
+
+    lock_owner = await lock.try_acquire()
+    if lock_owner != stream_id:
+        # Another stream is active
+        logger.warning(
+            f"[SDK] Session {session_id} already has an active stream: {lock_owner}"
+        )
+        yield StreamError(
+            errorText="Another stream is already active for this session. "
+            "Please wait or stop it.",
+            code="stream_already_active",
+        )
+        yield StreamFinish()
+        return
 
     yield StreamStart(messageId=message_id, taskId=task_id)
 
@@ -674,7 +713,7 @@ async def stream_chat_completion_sdk(
 
             options = ClaudeAgentOptions(**sdk_options_kwargs)  # type: ignore[arg-type]
 
-            adapter = SDKResponseAdapter(message_id=message_id)
+            adapter = SDKResponseAdapter(message_id=message_id, session_id=session_id)
             adapter.set_task_id(task_id)
 
             async with ClaudeSDKClient(options=options) as client:
@@ -699,10 +738,13 @@ async def stream_chat_completion_sdk(
                     transcript_msg_count,
                     session_id,
                 )
-
                 logger.info(
-                    f"[SDK] Sending query ({len(session.messages)} msgs, "
-                    f"resume={use_resume})"
+                    "[SDK] [%s] Sending query — resume=%s, "
+                    "total_msgs=%d, query_len=%d",
+                    session_id[:12],
+                    use_resume,
+                    len(session.messages),
+                    len(query_message),
                 )
                 await client.query(query_message, session_id=session_id)
 
@@ -711,97 +753,288 @@ async def stream_chat_completion_sdk(
                 has_appended_assistant = False
                 has_tool_results = False
 
-                # Use an explicit async iterator with timeout to send
-                # heartbeats when the CLI is idle (e.g. executing tools).
-                # This prevents proxies/LBs from closing the SSE connection.
-                # asyncio.timeout() is preferred over asyncio.wait_for()
-                # because wait_for wraps in a separate Task whose cancellation
-                # can leave the async generator in a broken state.
+                # Use an explicit async iterator with non-cancelling heartbeats.
+                # CRITICAL: we must NOT cancel __anext__() mid-flight — doing so
+                # (via asyncio.timeout or wait_for) corrupts the SDK's internal
+                # anyio memory stream, causing StopAsyncIteration on the next
+                # call and silently dropping all in-flight tool results.
+                # Instead, wrap __anext__() in a Task and use asyncio.wait()
+                # with a timeout.  On timeout we emit a heartbeat but keep the
+                # Task alive so it can deliver the next message.
                 msg_iter = client.receive_messages().__aiter__()
-                while not stream_completed:
-                    try:
-                        async with asyncio.timeout(_HEARTBEAT_INTERVAL):
-                            sdk_msg = await msg_iter.__anext__()
-                    except TimeoutError:
-                        yield StreamHeartbeat()
-                        continue
-                    except StopAsyncIteration:
-                        break
+                pending_task: asyncio.Task[Any] | None = None
+                try:
+                    while not stream_completed:
+                        if pending_task is None:
 
-                    logger.debug(
-                        f"[SDK] Received: {type(sdk_msg).__name__} "
-                        f"{getattr(sdk_msg, 'subtype', '')}"
-                    )
-                    for response in adapter.convert_message(sdk_msg):
-                        if isinstance(response, StreamStart):
+                            async def _next_msg() -> Any:
+                                return await msg_iter.__anext__()
+
+                            pending_task = asyncio.create_task(_next_msg())
+
+                        done, _ = await asyncio.wait(
+                            {pending_task}, timeout=_HEARTBEAT_INTERVAL
+                        )
+
+                        if not done:
+                            # Timeout — emit heartbeat but keep the task alive
+                            # Also refresh lock TTL to keep it alive
+                            await lock.refresh()
+                            yield StreamHeartbeat()
                             continue
 
-                        # Log tool events for debugging visibility issues
+                        # Task completed — get result
+                        pending_task = None
+                        try:
+                            sdk_msg = done.pop().result()
+                        except StopAsyncIteration:
+                            logger.info(
+                                "[SDK] [%s] Stream ended normally "
+                                "(StopAsyncIteration)",
+                                session_id[:12],
+                            )
+                            break
+                        except Exception as stream_err:
+                            # SDK sends {"type": "error"} which raises
+                            # Exception in receive_messages() — capture it
+                            # so the session can still be saved and the
+                            # frontend gets a clean finish.
+                            logger.error(
+                                "[SDK] [%s] Stream error from SDK: %s",
+                                session_id[:12],
+                                stream_err,
+                                exc_info=True,
+                            )
+                            yield StreamError(
+                                errorText=f"SDK stream error: {stream_err}",
+                                code="sdk_stream_error",
+                            )
+                            break
+
+                        logger.info(
+                            "[SDK] [%s] Received: %s %s "
+                            "(unresolved=%d, current=%d, resolved=%d)",
+                            session_id[:12],
+                            type(sdk_msg).__name__,
+                            getattr(sdk_msg, "subtype", ""),
+                            len(adapter.current_tool_calls)
+                            - len(adapter.resolved_tool_calls),
+                            len(adapter.current_tool_calls),
+                            len(adapter.resolved_tool_calls),
+                        )
+
+                        # Race-condition fix: SDK hooks (PostToolUse) are
+                        # executed asynchronously via start_soon() — the next
+                        # message can arrive before the hook stashes output.
+                        # wait_for_stash() awaits an asyncio.Event signaled by
+                        # stash_pending_tool_output(), completing as soon as
+                        # the hook finishes (typically <1ms).  The sleep(0)
+                        # after lets any remaining concurrent hooks complete.
+                        #
+                        # Skip for parallel tool continuations: when the SDK
+                        # sends parallel tool calls as separate
+                        # AssistantMessages (each containing only
+                        # ToolUseBlocks), we must NOT wait/flush — the prior
+                        # tools are still executing concurrently.
+                        from claude_agent_sdk import (
+                            AssistantMessage,
+                            ResultMessage,
+                            ToolUseBlock,
+                        )
+
+                        is_parallel_continuation = isinstance(
+                            sdk_msg, AssistantMessage
+                        ) and all(isinstance(b, ToolUseBlock) for b in sdk_msg.content)
+
+                        if (
+                            adapter.has_unresolved_tool_calls
+                            and isinstance(sdk_msg, (AssistantMessage, ResultMessage))
+                            and not is_parallel_continuation
+                        ):
+                            if await wait_for_stash(timeout=0.5):
+                                await asyncio.sleep(0)
+                            else:
+                                logger.warning(
+                                    "[SDK] [%s] Timed out waiting for "
+                                    "PostToolUse hook stash "
+                                    "(%d unresolved tool calls)",
+                                    session_id[:12],
+                                    len(adapter.current_tool_calls)
+                                    - len(adapter.resolved_tool_calls),
+                                )
+
+                        for response in adapter.convert_message(sdk_msg):
+                            if isinstance(response, StreamStart):
+                                continue
+
+                            # Log tool events for debugging
+                            if isinstance(
+                                response,
+                                (
+                                    StreamToolInputAvailable,
+                                    StreamToolOutputAvailable,
+                                ),
+                            ):
+                                extra = ""
+                                if isinstance(response, StreamToolOutputAvailable):
+                                    out_len = len(str(response.output))
+                                    extra = f", output_len={out_len}"
+                                logger.info(
+                                    "[SDK] [%s] Tool event: %s, tool=%s%s",
+                                    session_id[:12],
+                                    type(response).__name__,
+                                    getattr(response, "toolName", "N/A"),
+                                    extra,
+                                )
+
+                            yield response
+
+                            if isinstance(response, StreamTextDelta):
+                                delta = response.delta or ""
+                                # After tool results, start a new assistant
+                                # message for the post-tool text.
+                                if has_tool_results and has_appended_assistant:
+                                    assistant_response = ChatMessage(
+                                        role="assistant", content=delta
+                                    )
+                                    accumulated_tool_calls = []
+                                    has_appended_assistant = False
+                                    has_tool_results = False
+                                    session.messages.append(assistant_response)
+                                    has_appended_assistant = True
+                                else:
+                                    assistant_response.content = (
+                                        assistant_response.content or ""
+                                    ) + delta
+                                    if not has_appended_assistant:
+                                        session.messages.append(assistant_response)
+                                        has_appended_assistant = True
+
+                            elif isinstance(response, StreamToolInputAvailable):
+                                accumulated_tool_calls.append(
+                                    {
+                                        "id": response.toolCallId,
+                                        "type": "function",
+                                        "function": {
+                                            "name": response.toolName,
+                                            "arguments": json.dumps(
+                                                response.input or {}
+                                            ),
+                                        },
+                                    }
+                                )
+                                assistant_response.tool_calls = accumulated_tool_calls
+                                if not has_appended_assistant:
+                                    session.messages.append(assistant_response)
+                                    has_appended_assistant = True
+                                # Save before tool execution starts so the
+                                # pending tool call is visible on refresh /
+                                # other devices. Collision detection happens
+                                # in add_chat_messages_batch (db.py).
+                                try:
+                                    session = await upsert_chat_session(session)
+                                except Exception as save_err:
+                                    logger.warning(
+                                        "[SDK] [%s] Incremental save " "failed: %s",
+                                        session_id[:12],
+                                        save_err,
+                                    )
+
+                            elif isinstance(response, StreamToolOutputAvailable):
+                                session.messages.append(
+                                    ChatMessage(
+                                        role="tool",
+                                        content=(
+                                            response.output
+                                            if isinstance(response.output, str)
+                                            else str(response.output)
+                                        ),
+                                        tool_call_id=response.toolCallId,
+                                    )
+                                )
+                                has_tool_results = True
+                                # Save after tool completes so the result is
+                                # visible on refresh / other devices.
+                                # Collision detection happens in add_chat_messages_batch (db.py).
+                                try:
+                                    session = await upsert_chat_session(session)
+                                except Exception as save_err:
+                                    logger.warning(
+                                        "[SDK] [%s] Incremental save " "failed: %s",
+                                        session_id[:12],
+                                        save_err,
+                                    )
+
+                            elif isinstance(response, StreamFinish):
+                                stream_completed = True
+
+                except asyncio.CancelledError:
+                    # Task/generator was cancelled (e.g. client disconnect,
+                    # server shutdown).  Log and let the safety-net / finally
+                    # blocks handle cleanup.
+                    logger.warning(
+                        "[SDK] [%s] Streaming loop cancelled "
+                        "(asyncio.CancelledError)",
+                        session_id[:12],
+                    )
+                    raise
+                finally:
+                    # Cancel the pending __anext__ task to avoid a leaked
+                    # coroutine.  This is safe even if the task already
+                    # completed.
+                    if pending_task is not None and not pending_task.done():
+                        pending_task.cancel()
+                        try:
+                            await pending_task
+                        except (asyncio.CancelledError, StopAsyncIteration):
+                            pass
+
+                # Safety net: if tools are still unresolved after the
+                # streaming loop (e.g. StopAsyncIteration before ResultMessage,
+                # or SDK not sending UserMessages for built-in tools), flush
+                # them now so the frontend stops showing spinners.
+                if adapter.has_unresolved_tool_calls:
+                    logger.warning(
+                        "[SDK] [%s] %d unresolved tool(s) after stream loop — "
+                        "flushing as safety net",
+                        session_id[:12],
+                        len(adapter.current_tool_calls)
+                        - len(adapter.resolved_tool_calls),
+                    )
+                    safety_responses: list[StreamBaseResponse] = []
+                    adapter._flush_unresolved_tool_calls(safety_responses)
+                    for response in safety_responses:
                         if isinstance(
                             response,
                             (StreamToolInputAvailable, StreamToolOutputAvailable),
                         ):
                             logger.info(
-                                "[SDK] Tool event: %s, tool=%s",
+                                "[SDK] [%s] Safety flush: %s, tool=%s",
+                                session_id[:12],
                                 type(response).__name__,
                                 getattr(response, "toolName", "N/A"),
                             )
-
                         yield response
 
-                        if isinstance(response, StreamTextDelta):
-                            delta = response.delta or ""
-                            # After tool results, start a new assistant
-                            # message for the post-tool text.
-                            if has_tool_results and has_appended_assistant:
-                                assistant_response = ChatMessage(
-                                    role="assistant", content=delta
-                                )
-                                accumulated_tool_calls = []
-                                has_appended_assistant = False
-                                has_tool_results = False
-                                session.messages.append(assistant_response)
-                                has_appended_assistant = True
-                            else:
-                                assistant_response.content = (
-                                    assistant_response.content or ""
-                                ) + delta
-                                if not has_appended_assistant:
-                                    session.messages.append(assistant_response)
-                                    has_appended_assistant = True
-
-                        elif isinstance(response, StreamToolInputAvailable):
-                            accumulated_tool_calls.append(
-                                {
-                                    "id": response.toolCallId,
-                                    "type": "function",
-                                    "function": {
-                                        "name": response.toolName,
-                                        "arguments": json.dumps(response.input or {}),
-                                    },
-                                }
-                            )
-                            assistant_response.tool_calls = accumulated_tool_calls
-                            if not has_appended_assistant:
-                                session.messages.append(assistant_response)
-                                has_appended_assistant = True
-
-                        elif isinstance(response, StreamToolOutputAvailable):
-                            session.messages.append(
-                                ChatMessage(
-                                    role="tool",
-                                    content=(
-                                        response.output
-                                        if isinstance(response.output, str)
-                                        else str(response.output)
-                                    ),
-                                    tool_call_id=response.toolCallId,
-                                )
-                            )
-                            has_tool_results = True
-
-                        elif isinstance(response, StreamFinish):
-                            stream_completed = True
+                # If the stream ended without a ResultMessage (no
+                # StreamFinish), the SDK CLI exited unexpectedly.  Close
+                # the open step and emit StreamFinish so the frontend
+                # transitions to the "ready" state.
+                if not stream_completed:
+                    logger.warning(
+                        "[SDK] [%s] Stream ended without ResultMessage "
+                        "(StopAsyncIteration) — emitting StreamFinish",
+                        session_id[:12],
+                    )
+                    if adapter.step_open:
+                        yield StreamFinishStep()
+                        adapter.step_open = False
+                    closing_responses: list[StreamBaseResponse] = []
+                    adapter._end_text_if_open(closing_responses)
+                    for r in closing_responses:
+                        yield r
+                    yield StreamFinish()
+                    stream_completed = True
 
                 if (
                     assistant_response.content or assistant_response.tool_calls
@@ -856,19 +1089,28 @@ async def stream_chat_completion_sdk(
                 "to use the OpenAI-compatible fallback."
             )
 
-        await asyncio.shield(upsert_chat_session(session))
-        logger.debug(
-            f"[SDK] Session {session_id} saved with {len(session.messages)} messages"
+        session = cast(ChatSession, await asyncio.shield(upsert_chat_session(session)))
+        logger.info(
+            "[SDK] [%s] Session saved with %d messages",
+            session_id[:12],
+            len(session.messages),
         )
         if not stream_completed:
             yield StreamFinish()
 
+    except asyncio.CancelledError:
+        # Client disconnect / server shutdown — log but re-raise so
+        # the framework can clean up.  The finally block still runs
+        # for transcript upload.
+        logger.warning("[SDK] [%s] Session cancelled (CancelledError)", session_id[:12])
+        raise
     except Exception as e:
         logger.error(f"[SDK] Error: {e}", exc_info=True)
-        try:
-            await asyncio.shield(upsert_chat_session(session))
-        except Exception as save_err:
-            logger.error(f"[SDK] Failed to save session on error: {save_err}")
+        if session:
+            try:
+                await asyncio.shield(upsert_chat_session(session))
+            except Exception as save_err:
+                logger.error(f"[SDK] Failed to save session on error: {save_err}")
         yield StreamError(
             errorText="An error occurred. Please try again.",
             code="sdk_error",
@@ -890,7 +1132,7 @@ async def stream_chat_completion_sdk(
                 if not raw_transcript and use_resume and resume_file:
                     raw_transcript = read_transcript_file(resume_file)
 
-                if raw_transcript:
+                if raw_transcript and session is not None:
                     await asyncio.shield(
                         _try_upload_transcript(
                             user_id,
@@ -910,6 +1152,9 @@ async def stream_chat_completion_sdk(
         if sdk_cwd:
             _cleanup_sdk_tool_results(sdk_cwd)
 
+        # Release stream lock to allow new streams for this session
+        await lock.release()
+
 
 async def _try_upload_transcript(
     user_id: str,

autogpt_platform/backend/backend/copilot/sdk/tool_adapter.py

@@ -9,6 +9,7 @@ via a callback provided by the service layer.  This avoids wasteful SDK polling
 and makes results survive page refreshes.
 """
 
+import asyncio
 import itertools
 import json
 import logging
@@ -44,6 +45,14 @@ _current_session: ContextVar[ChatSession | None] = ContextVar(
 _pending_tool_outputs: ContextVar[dict[str, list[str]]] = ContextVar(
     "pending_tool_outputs", default=None  # type: ignore[arg-type]
 )
+# Event signaled whenever stash_pending_tool_output() adds a new entry.
+# Used by the streaming loop to wait for PostToolUse hooks to complete
+# instead of sleeping an arbitrary duration.  The SDK fires hooks via
+# start_soon (fire-and-forget) so the next message can arrive before
+# the hook stashes its output — this event bridges that gap.
+_stash_event: ContextVar[asyncio.Event | None] = ContextVar(
+    "_stash_event", default=None
+)
 
 # Callback type for delegating long-running tools to the non-SDK infrastructure.
 # Args: (tool_name, arguments, session) → MCP-formatted response dict.
@@ -76,6 +85,7 @@ def set_execution_context(
     _current_user_id.set(user_id)
     _current_session.set(session)
     _pending_tool_outputs.set({})
+    _stash_event.set(asyncio.Event())
     _long_running_callback.set(long_running_callback)
 
 
@@ -134,6 +144,43 @@ def stash_pending_tool_output(tool_name: str, output: Any) -> None:
         except (TypeError, ValueError):
             text = str(output)
     pending.setdefault(tool_name, []).append(text)
+    # Signal any waiters that new output is available.
+    event = _stash_event.get(None)
+    if event is not None:
+        event.set()
+
+
+async def wait_for_stash(timeout: float = 0.5) -> bool:
+    """Wait for a PostToolUse hook to stash tool output.
+
+    The SDK fires PostToolUse hooks asynchronously via ``start_soon()`` —
+    the next message (AssistantMessage/ResultMessage) can arrive before the
+    hook completes and stashes its output.  This function bridges that gap
+    by waiting on the ``_stash_event``, which is signaled by
+    :func:`stash_pending_tool_output`.
+
+    After the event fires, callers should ``await asyncio.sleep(0)`` to
+    give any remaining concurrent hooks a chance to complete.
+
+    Returns ``True`` if a stash signal was received, ``False`` on timeout.
+    The timeout is a safety net — normally the stash happens within
+    microseconds of yielding to the event loop.
+    """
+    event = _stash_event.get(None)
+    if event is None:
+        return False
+    # Fast path: hook already completed before we got here.
+    if event.is_set():
+        event.clear()
+        return True
+    # Slow path: wait for the hook to signal.
+    try:
+        async with asyncio.timeout(timeout):
+            await event.wait()
+        event.clear()
+        return True
+    except TimeoutError:
+        return False
 
 
 async def _execute_tool_sync(

autogpt_platform/backend/backend/copilot/service.py

@@ -352,7 +352,8 @@ async def assign_user_to_session(
     if not session:
         raise NotFoundError(f"Session {session_id} not found")
     session.user_id = user_id
-    return await upsert_chat_session(session)
+    session = await upsert_chat_session(session)
+    return session
 
 
 async def stream_chat_completion(
@@ -1563,7 +1564,11 @@ async def _yield_tool_call(
             await _mark_operation_completed(tool_call_id)
             # Mark stream registry task as failed if it was created
             try:
-                await stream_registry.mark_task_completed(task_id, status="failed")
+                await stream_registry.mark_task_completed(
+                    task_id,
+                    status="failed",
+                    error_message=f"Failed to setup tool {tool_name}: {e}",
+                )
             except Exception as mark_err:
                 logger.warning(f"Failed to mark task {task_id} as failed: {mark_err}")
             logger.error(
@@ -1731,7 +1736,11 @@ async def _execute_long_running_tool_with_streaming(
         session = await get_chat_session(session_id, user_id)
         if not session:
             logger.error(f"Session {session_id} not found for background tool")
-            await stream_registry.mark_task_completed(task_id, status="failed")
+            await stream_registry.mark_task_completed(
+                task_id,
+                status="failed",
+                error_message=f"Session {session_id} not found",
+            )
             return
 
         # Pass operation_id and task_id to the tool for async processing

autogpt_platform/backend/backend/copilot/stream_registry.py

@@ -644,6 +644,8 @@ async def _stream_listener(
 async def mark_task_completed(
     task_id: str,
     status: Literal["completed", "failed"] = "completed",
+    *,
+    error_message: str | None = None,
 ) -> bool:
     """Mark a task as completed and publish finish event.
 
@@ -654,6 +656,10 @@ async def mark_task_completed(
     Args:
         task_id: Task ID to mark as completed
         status: Final status ("completed" or "failed")
+        error_message: If provided and status="failed", publish a StreamError
+            before StreamFinish so connected clients see why the task ended.
+            If not provided, no StreamError is published (caller should publish
+            manually if needed to avoid duplicates).
 
     Returns:
         True if task was newly marked completed, False if already completed/failed
@@ -669,6 +675,17 @@ async def mark_task_completed(
         logger.debug(f"Task {task_id} already completed/failed, skipping")
         return False
 
+    # Publish error event before finish so connected clients know WHY the
+    # task ended. Only publish if caller provided an explicit error message
+    # to avoid duplicates with code paths that manually publish StreamError.
+    # This is best-effort — if it fails, the StreamFinish still ensures
+    # listeners clean up.
+    if status == "failed" and error_message:
+        try:
+            await publish_chunk(task_id, StreamError(errorText=error_message))
+        except Exception as e:
+            logger.warning(f"Failed to publish error event for task {task_id}: {e}")
+
     # THEN publish finish event (best-effort - listeners can detect via status polling)
     try:
         await publish_chunk(task_id, StreamFinish())
@@ -821,27 +838,6 @@ async def get_active_task_for_session(
                 if task_user_id and user_id != task_user_id:
                     continue
 
-                # Auto-expire stale tasks that exceeded stream_timeout
-                created_at_str = meta.get("created_at", "")
-                if created_at_str:
-                    try:
-                        created_at = datetime.fromisoformat(created_at_str)
-                        age_seconds = (
-                            datetime.now(timezone.utc) - created_at
-                        ).total_seconds()
-                        if age_seconds > config.stream_timeout:
-                            logger.warning(
-                                f"[TASK_LOOKUP] Auto-expiring stale task {task_id[:8]}... "
-                                f"(age={age_seconds:.0f}s > timeout={config.stream_timeout}s)"
-                            )
-                            await mark_task_completed(task_id, "failed")
-                            continue
-                    except (ValueError, TypeError) as exc:
-                        logger.warning(
-                            f"[TASK_LOOKUP] Failed to parse created_at "
-                            f"for task {task_id[:8]}...: {exc}"
-                        )
-
                 logger.info(
                     f"[TASK_LOOKUP] Found running task {task_id[:8]}... for session {session_id[:8]}..."
                 )

autogpt_platform/backend/backend/data/db_manager.py

@@ -303,7 +303,7 @@ class DatabaseManager(AppService):
     get_user_chat_sessions = _(chat_db.get_user_chat_sessions)
     get_user_session_count = _(chat_db.get_user_session_count)
     delete_chat_session = _(chat_db.delete_chat_session)
-    get_chat_session_message_count = _(chat_db.get_chat_session_message_count)
+    get_next_sequence = _(chat_db.get_next_sequence)
     update_tool_message_content = _(chat_db.update_tool_message_content)
 
 
@@ -473,5 +473,5 @@ class DatabaseManagerAsyncClient(AppServiceClient):
     get_user_chat_sessions = d.get_user_chat_sessions
     get_user_session_count = d.get_user_session_count
     delete_chat_session = d.delete_chat_session
-    get_chat_session_message_count = d.get_chat_session_message_count
+    get_next_sequence = d.get_next_sequence
     update_tool_message_content = d.update_tool_message_content

autogpt_platform/backend/backend/data/includes.py

@@ -79,6 +79,12 @@ INTEGRATION_WEBHOOK_INCLUDE: prisma.types.IntegrationWebhookInclude = {
 }
 
 
+LIBRARY_FOLDER_INCLUDE: prisma.types.LibraryFolderInclude = {
+    "LibraryAgents": {"where": {"isDeleted": False}},
+    "Children": {"where": {"isDeleted": False}},
+}
+
+
 def library_agent_include(
     user_id: str,
     include_nodes: bool = True,
@@ -105,6 +111,7 @@ def library_agent_include(
     """
     result: prisma.types.LibraryAgentInclude = {
         "Creator": True,  # Always needed for creator info
+        "Folder": True,  # Always needed for folder info
     }
 
     # Build AgentGraph include based on requested options

autogpt_platform/backend/backend/executor/cluster_lock.py

@@ -1,5 +1,6 @@
 """Redis-based distributed locking for cluster coordination."""
 
+import asyncio
 import logging
 import threading
 import time
@@ -7,6 +8,7 @@ from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from redis import Redis
+    from redis.asyncio import Redis as AsyncRedis
 
 logger = logging.getLogger(__name__)
 
@@ -126,3 +128,124 @@ class ClusterLock:
 
         with self._refresh_lock:
             self._last_refresh = 0.0
+
+
+class AsyncClusterLock:
+    """Async Redis-based distributed lock for preventing duplicate execution."""
+
+    def __init__(
+        self, redis: "AsyncRedis", key: str, owner_id: str, timeout: int = 300
+    ):
+        self.redis = redis
+        self.key = key
+        self.owner_id = owner_id
+        self.timeout = timeout
+        self._last_refresh = 0.0
+        self._refresh_lock = asyncio.Lock()
+
+    async def try_acquire(self) -> str | None:
+        """Try to acquire the lock.
+
+        Returns:
+            - owner_id (self.owner_id) if successfully acquired
+            - different owner_id if someone else holds the lock
+            - None if Redis is unavailable or other error
+        """
+        try:
+            success = await self.redis.set(
+                self.key, self.owner_id, nx=True, ex=self.timeout
+            )
+            if success:
+                async with self._refresh_lock:
+                    self._last_refresh = time.time()
+                return self.owner_id  # Successfully acquired
+
+            # Failed to acquire, get current owner
+            current_value = await self.redis.get(self.key)
+            if current_value:
+                current_owner = (
+                    current_value.decode("utf-8")
+                    if isinstance(current_value, bytes)
+                    else str(current_value)
+                )
+                return current_owner
+
+            # Key doesn't exist but we failed to set it - race condition or Redis issue
+            return None
+
+        except Exception as e:
+            logger.error(f"AsyncClusterLock.try_acquire failed for key {self.key}: {e}")
+            return None
+
+    async def refresh(self) -> bool:
+        """Refresh lock TTL if we still own it.
+
+        Rate limited to at most once every timeout/10 seconds (minimum 1 second).
+        During rate limiting, still verifies lock existence but skips TTL extension.
+        Setting _last_refresh to 0 bypasses rate limiting for testing.
+
+        Async-safe: uses asyncio.Lock to protect _last_refresh access.
+        """
+        # Calculate refresh interval: max(timeout // 10, 1)
+        refresh_interval = max(self.timeout // 10, 1)
+        current_time = time.time()
+
+        # Check if we're within the rate limit period (async-safe read)
+        # _last_refresh == 0 forces a refresh (bypasses rate limiting for testing)
+        async with self._refresh_lock:
+            last_refresh = self._last_refresh
+        is_rate_limited = (
+            last_refresh > 0 and (current_time - last_refresh) < refresh_interval
+        )
+
+        try:
+            # Always verify lock existence, even during rate limiting
+            current_value = await self.redis.get(self.key)
+            if not current_value:
+                async with self._refresh_lock:
+                    self._last_refresh = 0
+                return False
+
+            stored_owner = (
+                current_value.decode("utf-8")
+                if isinstance(current_value, bytes)
+                else str(current_value)
+            )
+            if stored_owner != self.owner_id:
+                async with self._refresh_lock:
+                    self._last_refresh = 0
+                return False
+
+            # If rate limited, return True but don't update TTL or timestamp
+            if is_rate_limited:
+                return True
+
+            # Perform actual refresh
+            if await self.redis.expire(self.key, self.timeout):
+                async with self._refresh_lock:
+                    self._last_refresh = current_time
+                return True
+
+            async with self._refresh_lock:
+                self._last_refresh = 0
+            return False
+
+        except Exception as e:
+            logger.error(f"AsyncClusterLock.refresh failed for key {self.key}: {e}")
+            async with self._refresh_lock:
+                self._last_refresh = 0
+            return False
+
+    async def release(self):
+        """Release the lock."""
+        async with self._refresh_lock:
+            if self._last_refresh == 0:
+                return
+
+        try:
+            await self.redis.delete(self.key)
+        except Exception:
+            pass
+
+        async with self._refresh_lock:
+            self._last_refresh = 0.0

autogpt_platform/backend/migrations/20260123110033_add_folders_in_library/migration.sql

@@ -0,0 +1,33 @@
+-- AlterTable
+ALTER TABLE "LibraryAgent" ADD COLUMN     "folderId" TEXT;
+
+-- CreateTable
+CREATE TABLE "LibraryFolder" (
+    "id" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "userId" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "icon" TEXT,
+    "color" TEXT,
+    "parentId" TEXT,
+    "isDeleted" BOOLEAN NOT NULL DEFAULT false,
+
+    CONSTRAINT "LibraryFolder_pkey" PRIMARY KEY ("id")
+);
+
+
+-- CreateIndex
+CREATE UNIQUE INDEX "LibraryFolder_userId_parentId_name_key" ON "LibraryFolder"("userId", "parentId", "name");
+
+-- CreateIndex
+CREATE INDEX "LibraryAgent_folderId_idx" ON "LibraryAgent"("folderId");
+
+-- AddForeignKey
+ALTER TABLE "LibraryAgent" ADD CONSTRAINT "LibraryAgent_folderId_fkey" FOREIGN KEY ("folderId") REFERENCES "LibraryFolder"("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "LibraryFolder" ADD CONSTRAINT "LibraryFolder_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "LibraryFolder" ADD CONSTRAINT "LibraryFolder_parentId_fkey" FOREIGN KEY ("parentId") REFERENCES "LibraryFolder"("id") ON DELETE CASCADE ON UPDATE CASCADE;

autogpt_platform/backend/poetry.lock

@@ -899,17 +899,17 @@ files = [
 
 [[package]]
 name = "claude-agent-sdk"
-version = "0.1.35"
+version = "0.1.39"
 description = "Python SDK for Claude Code"
 optional = false
 python-versions = ">=3.10"
 groups = ["main"]
 files = [
-    {file = "claude_agent_sdk-0.1.35-py3-none-macosx_11_0_arm64.whl", hash = "sha256:df67f4deade77b16a9678b3a626c176498e40417f33b04beda9628287f375591"},
-    {file = "claude_agent_sdk-0.1.35-py3-none-manylinux_2_17_aarch64.whl", hash = "sha256:14963944f55ded7c8ed518feebfa5b4284aa6dd8d81aeff2e5b21a962ce65097"},
-    {file = "claude_agent_sdk-0.1.35-py3-none-manylinux_2_17_x86_64.whl", hash = "sha256:84344dcc535d179c1fc8a11c6f34c37c3b583447bdf09d869effb26514fd7a65"},
-    {file = "claude_agent_sdk-0.1.35-py3-none-win_amd64.whl", hash = "sha256:1b3d54b47448c93f6f372acd4d1757f047c3c1e8ef5804be7a1e3e53e2c79a5f"},
-    {file = "claude_agent_sdk-0.1.35.tar.gz", hash = "sha256:0f98e2b3c71ca85abfc042e7a35c648df88e87fda41c52e6779ef7b038dcbb52"},
+    {file = "claude_agent_sdk-0.1.39-py3-none-macosx_11_0_arm64.whl", hash = "sha256:6ed6a79781f545b761b9fe467bc5ae213a103c9d3f0fe7a9dad3c01790ed58fa"},
+    {file = "claude_agent_sdk-0.1.39-py3-none-manylinux_2_17_aarch64.whl", hash = "sha256:0c03b5a3772eaec42e29ea39240c7d24b760358082f2e36336db9e71dde3dda4"},
+    {file = "claude_agent_sdk-0.1.39-py3-none-manylinux_2_17_x86_64.whl", hash = "sha256:d2665c9e87b6ffece590bcdd6eb9def47cde4809b0d2f66e0a61a719189be7c9"},
+    {file = "claude_agent_sdk-0.1.39-py3-none-win_amd64.whl", hash = "sha256:d03324daf7076be79d2dd05944559aabf4cc11c98d3a574b992a442a7c7a26d6"},
+    {file = "claude_agent_sdk-0.1.39.tar.gz", hash = "sha256:dcf0ebd5a638c9a7d9f3af7640932a9212b2705b7056e4f08bd3968a865b4268"},
 ]
 
 [package.dependencies]
@@ -8530,4 +8530,4 @@ cffi = ["cffi (>=1.17,<2.0) ; platform_python_implementation != \"PyPy\" and pyt
 [metadata]
 lock-version = "2.1"
 python-versions = ">=3.10,<3.14"
-content-hash = "55e095de555482f0fe47de7695f390fe93e7bcf739b31c391b2e5e3c3d938ae3"
+content-hash = "3ef62836d8321b9a3b8e897dade8dc6ca9022fd9468c53f384b0871b521ab343"

autogpt_platform/backend/pyproject.toml

@@ -16,7 +16,7 @@ anthropic = "^0.79.0"
 apscheduler = "^3.11.1"
 autogpt-libs = { path = "../autogpt_libs", develop = true }
 bleach = { extras = ["css"], version = "^6.2.0" }
-claude-agent-sdk = "^0.1.0"
+claude-agent-sdk = "^0.1.39"  # see copilot/sdk/sdk_compat_test.py for capability checks
 click = "^8.2.0"
 cryptography = "^46.0"
 discord-py = "^2.5.2"

autogpt_platform/backend/schema.prisma

@@ -51,6 +51,7 @@ model User {
   ChatSessions         ChatSession[]
   AgentPresets         AgentPreset[]
   LibraryAgents        LibraryAgent[]
+  LibraryFolders       LibraryFolder[]
 
   Profile               Profile[]
   UserOnboarding        UserOnboarding?
@@ -395,6 +396,9 @@ model LibraryAgent {
   creatorId String?
   Creator   Profile? @relation(fields: [creatorId], references: [id])
 
+  folderId String?
+  Folder   LibraryFolder? @relation(fields: [folderId], references: [id], onDelete: Restrict)
+
   useGraphIsActiveVersion Boolean @default(false)
 
   isFavorite      Boolean @default(false)
@@ -407,6 +411,30 @@ model LibraryAgent {
   @@unique([userId, agentGraphId, agentGraphVersion])
   @@index([agentGraphId, agentGraphVersion])
   @@index([creatorId])
+  @@index([folderId])
+}
+
+model LibraryFolder {
+  id        String   @id @default(uuid())
+  createdAt DateTime @default(now())
+  updatedAt DateTime @default(now()) @updatedAt
+
+  userId String
+  User   User   @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  name  String
+  icon  String?
+  color String?
+
+  parentId String?
+  Parent   LibraryFolder?  @relation("FolderHierarchy", fields: [parentId], references: [id], onDelete: Cascade)
+  Children LibraryFolder[] @relation("FolderHierarchy")
+
+  isDeleted Boolean @default(false)
+
+  LibraryAgents LibraryAgent[]
+
+  @@unique([userId, parentId, name]) // Name unique per parent per user
 }
 
 ////////////////////////////////////////////////////////////

autogpt_platform/backend/snapshots/lib_agts_search

@@ -38,6 +38,8 @@
       "can_access_graph": true,
       "is_latest_version": true,
       "is_favorite": false,
+      "folder_id": null,
+      "folder_name": null,
       "recommended_schedule_cron": null,
       "settings": {
         "human_in_the_loop_safe_mode": true,
@@ -83,6 +85,8 @@
       "can_access_graph": false,
       "is_latest_version": true,
       "is_favorite": false,
+      "folder_id": null,
+      "folder_name": null,
       "recommended_schedule_cron": null,
       "settings": {
         "human_in_the_loop_safe_mode": true,

autogpt_platform/frontend/package.json

@@ -32,6 +32,7 @@
   "dependencies": {
     "@ai-sdk/react": "3.0.61",
     "@faker-js/faker": "10.0.0",
+    "@ferrucc-io/emoji-picker": "0.0.48",
     "@hookform/resolvers": "5.2.2",
     "@next/third-parties": "15.4.6",
     "@phosphor-icons/react": "2.1.10",

autogpt_platform/frontend/pnpm-lock.yaml

@@ -18,6 +18,9 @@ importers:
       '@faker-js/faker':
         specifier: 10.0.0
         version: 10.0.0
+      '@ferrucc-io/emoji-picker':
+        specifier: 0.0.48
+        version: 0.0.48(@babel/core@7.28.5)(@babel/template@7.27.2)(@types/react@18.3.17)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(tailwindcss@3.4.17)
       '@hookform/resolvers':
         specifier: 5.2.2
         version: 5.2.2(react-hook-form@7.66.0(react@18.3.1))
@@ -1507,6 +1510,14 @@ packages:
     resolution: {integrity: sha512-UollFEUkVXutsaP+Vndjxar40Gs5JL2HeLcl8xO1QAjJgOdhc3OmBFWyEylS+RddWaaBiAzH+5/17PLQJwDiLw==}
     engines: {node: ^20.19.0 || ^22.13.0 || ^23.5.0 || >=24.0.0, npm: '>=10'}
 
+  '@ferrucc-io/emoji-picker@0.0.48':
+    resolution: {integrity: sha512-DJ5u+6VLF9OK7x+S/luwrVb5CHC6W16jL5b8vBUYNpxKWSuFgyliDHVtw1SGe6+dr5RUbf8WQwPJdKZmU3Ittg==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      react: ^18.2.0 || ^19.0.0
+      react-dom: ^18.2.0 || ^19.0.0
+      tailwindcss: '>=3.0.0'
+
   '@floating-ui/core@1.7.3':
     resolution: {integrity: sha512-sGnvb5dmrJaKEZ+LDIpguvdX3bDlEllmv4/ClQ9awcmCZrlx5jQyyMWFM5kBI+EyNOCDDiKk8il0zeuX3Zlg/w==}
 
@@ -3114,6 +3125,10 @@ packages:
   '@shikijs/vscode-textmate@10.0.2':
     resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==}
 
+  '@sindresorhus/is@4.6.0':
+    resolution: {integrity: sha512-t09vSN3MdfsyCHoFcTRCH/iUtG7OJ0CsjzB8cjAmKc/va/kIgeDI/TxsigdncE/4be734m0cvIYwNaV4i2XqAw==}
+    engines: {node: '>=10'}
+
   '@standard-schema/spec@1.0.0':
     resolution: {integrity: sha512-m2bOd0f2RT9k8QJx1JN85cZYyH1RqFBdlwtkSlf4tBDYLCiiZnv1fIIwacK6cqwXavOydf0NPToMQgpKq+dVlA==}
 
@@ -3376,10 +3391,19 @@ packages:
       react: '>=16.8'
       react-dom: '>=16.8'
 
+  '@tanstack/react-virtual@3.13.18':
+    resolution: {integrity: sha512-dZkhyfahpvlaV0rIKnvQiVoWPyURppl6w4m9IwMDpuIjcJ1sD9YGWrt0wISvgU7ewACXx2Ct46WPgI6qAD4v6A==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
   '@tanstack/table-core@8.21.3':
     resolution: {integrity: sha512-ldZXEhOBb8Is7xLs01fR3YEc3DERiz5silj8tnGkFZytt1abEvl/GhUmCE0PMLaMPTa3Jk4HbKmRlHmu+gCftg==}
     engines: {node: '>=12'}
 
+  '@tanstack/virtual-core@3.13.18':
+    resolution: {integrity: sha512-Mx86Hqu1k39icq2Zusq+Ey2J6dDWTjDvEv43PJtRCoEYTLyfaPnxIQ6iy7YAOK0NV/qOEmZQ/uCufrppZxTgcg==}
+
   '@testing-library/dom@10.4.1':
     resolution: {integrity: sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==}
     engines: {node: '>=18'}
@@ -4373,6 +4397,10 @@ packages:
     resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
     engines: {node: '>=10'}
 
+  char-regex@1.0.2:
+    resolution: {integrity: sha512-kWWXztvZ5SBQV+eRgKFeh8q5sLuZY2+8WUIzlxWVTg+oGwY14qylx1KbKzHd8P6ZYkAg0xyIDU9JMHhyJMZ1jw==}
+    engines: {node: '>=10'}
+
   character-entities-html4@2.1.0:
     resolution: {integrity: sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==}
 
@@ -4990,6 +5018,9 @@ packages:
   emoji-regex@9.2.2:
     resolution: {integrity: sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==}
 
+  emojilib@2.4.0:
+    resolution: {integrity: sha512-5U0rVMU5Y2n2+ykNLQqMoqklN9ICBT/KsvC1Gz6vqHbz2AXXGkG+Pm5rMWk/8Vjrr/mY9985Hi8DYzn1F09Nyw==}
+
   emojis-list@3.0.0:
     resolution: {integrity: sha512-/kyM18EfinwXZbno9FyUGeFh87KC8HRQBQGildHZbEuRyWFOmv1U10o9BBp8XVZDVNNuQKyIGIu5ZYAAXJ0V2Q==}
     engines: {node: '>= 4'}
@@ -5970,6 +6001,24 @@ packages:
     resolution: {integrity: sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==}
     hasBin: true
 
+  jotai@2.17.1:
+    resolution: {integrity: sha512-TFNZZDa/0ewCLQyRC/Sq9crtixNj/Xdf/wmj9631xxMuKToVJZDbqcHIYN0OboH+7kh6P6tpIK7uKWClj86PKw==}
+    engines: {node: '>=12.20.0'}
+    peerDependencies:
+      '@babel/core': '>=7.0.0'
+      '@babel/template': '>=7.0.0'
+      '@types/react': '>=17.0.0'
+      react: '>=17.0.0'
+    peerDependenciesMeta:
+      '@babel/core':
+        optional: true
+      '@babel/template':
+        optional: true
+      '@types/react':
+        optional: true
+      react:
+        optional: true
+
   js-tokens@4.0.0:
     resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
 
@@ -6588,6 +6637,10 @@ packages:
   node-abort-controller@3.1.1:
     resolution: {integrity: sha512-AGK2yQKIjRuqnc6VkX2Xj5d+QW8xZ87pa1UK6yA6ouUyuxfHuMP6umE5QK7UmTeOAymo+Zx1Fxiuw9rVx8taHQ==}
 
+  node-emoji@2.2.0:
+    resolution: {integrity: sha512-Z3lTE9pLaJF47NyMhd4ww1yFTAP8YhYI8SleJiHzM46Fgpm5cnNzSl9XfzFNqbaz+VlJrIj3fXQ4DeN1Rjm6cw==}
+    engines: {node: '>=18'}
+
   node-fetch-h2@2.3.0:
     resolution: {integrity: sha512-ofRW94Ab0T4AOh5Fk8t0h8OBWrmjb0SSB20xh1H8YnPV9EJ+f5AMoYSUQ2zgJ4Iq2HAK0I2l5/Nequ8YzFS3Hg==}
     engines: {node: 4.x || >=6.0.0}
@@ -7686,6 +7739,10 @@ packages:
     resolution: {integrity: sha512-LH7FpTAkeD+y5xQC4fzS+tFtaNlvt3Ib1zKzvhjv/Y+cioV4zIuw4IZr2yhRLu67CWL7FR9/6KXKnjRoZTvGGQ==}
     engines: {node: '>=12'}
 
+  skin-tone@2.0.0:
+    resolution: {integrity: sha512-kUMbT1oBJCpgrnKoSr0o6wPtvRWT9W9UKvGLwfJYO2WuahZRHOpEyL1ckyMGgMWh0UdpmaoFqKKD29WTomNEGA==}
+    engines: {node: '>=8'}
+
   slash@3.0.0:
     resolution: {integrity: sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==}
     engines: {node: '>=8'}
@@ -8163,6 +8220,13 @@ packages:
     resolution: {integrity: sha512-dA8WbNeb2a6oQzAQ55YlT5vQAWGV9WXOsi3SskE3bcCdM0P4SDd+24zS/OCacdRq5BkdsRj9q3Pg6YyQoxIGqg==}
     engines: {node: '>=4'}
 
+  unicode-emoji-json@0.8.0:
+    resolution: {integrity: sha512-3wDXXvp6YGoKGhS2O2H7+V+bYduOBydN1lnI0uVfr1cIdY02uFFiEH1i3kE5CCE4l6UqbLKVmEFW9USxTAMD1g==}
+
+  unicode-emoji-modifier-base@1.0.0:
+    resolution: {integrity: sha512-yLSH4py7oFH3oG/9K+XWrz1pSi3dfUrWEnInbxMfArOfc1+33BlGPQtLsOYwvdMy11AwUBetYuaRxSPqgkq+8g==}
+    engines: {node: '>=4'}
+
   unicode-match-property-ecmascript@2.0.0:
     resolution: {integrity: sha512-5kaZCrbp5mmbz5ulBkDkbY0SsPOjKqVS35VpL9ulMPfSl0J0Xsm+9Evphv9CoIZFwre7aJoa94AY6seMKGVN5Q==}
     engines: {node: '>=4'}
@@ -9772,6 +9836,22 @@ snapshots:
 
   '@faker-js/faker@10.0.0': {}
 
+  '@ferrucc-io/emoji-picker@0.0.48(@babel/core@7.28.5)(@babel/template@7.27.2)(@types/react@18.3.17)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(tailwindcss@3.4.17)':
+    dependencies:
+      '@tanstack/react-virtual': 3.13.18(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      clsx: 2.1.1
+      jotai: 2.17.1(@babel/core@7.28.5)(@babel/template@7.27.2)(@types/react@18.3.17)(react@18.3.1)
+      node-emoji: 2.2.0
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      tailwind-merge: 2.6.0
+      tailwindcss: 3.4.17
+      unicode-emoji-json: 0.8.0
+    transitivePeerDependencies:
+      - '@babel/core'
+      - '@babel/template'
+      - '@types/react'
+
   '@floating-ui/core@1.7.3':
     dependencies:
       '@floating-ui/utils': 0.2.10
@@ -11533,6 +11613,8 @@ snapshots:
 
   '@shikijs/vscode-textmate@10.0.2': {}
 
+  '@sindresorhus/is@4.6.0': {}
+
   '@standard-schema/spec@1.0.0': {}
 
   '@standard-schema/spec@1.1.0': {}
@@ -12001,8 +12083,16 @@ snapshots:
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
 
+  '@tanstack/react-virtual@3.13.18(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@tanstack/virtual-core': 3.13.18
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
   '@tanstack/table-core@8.21.3': {}
 
+  '@tanstack/virtual-core@3.13.18': {}
+
   '@testing-library/dom@10.4.1':
     dependencies:
       '@babel/code-frame': 7.27.1
@@ -13094,6 +13184,8 @@ snapshots:
       ansi-styles: 4.3.0
       supports-color: 7.2.0
 
+  char-regex@1.0.2: {}
+
   character-entities-html4@2.1.0: {}
 
   character-entities-legacy@3.0.0: {}
@@ -13737,6 +13829,8 @@ snapshots:
 
   emoji-regex@9.2.2: {}
 
+  emojilib@2.4.0: {}
+
   emojis-list@3.0.0: {}
 
   endent@2.1.0:
@@ -15018,6 +15112,13 @@ snapshots:
 
   jiti@2.6.1: {}
 
+  jotai@2.17.1(@babel/core@7.28.5)(@babel/template@7.27.2)(@types/react@18.3.17)(react@18.3.1):
+    optionalDependencies:
+      '@babel/core': 7.28.5
+      '@babel/template': 7.27.2
+      '@types/react': 18.3.17
+      react: 18.3.1
+
   js-tokens@4.0.0: {}
 
   js-yaml@4.1.0:
@@ -15886,6 +15987,13 @@ snapshots:
 
   node-abort-controller@3.1.1: {}
 
+  node-emoji@2.2.0:
+    dependencies:
+      '@sindresorhus/is': 4.6.0
+      char-regex: 1.0.2
+      emojilib: 2.4.0
+      skin-tone: 2.0.0
+
   node-fetch-h2@2.3.0:
     dependencies:
       http2-client: 1.3.5
@@ -17186,6 +17294,10 @@ snapshots:
     dependencies:
       jsep: 1.4.0
 
+  skin-tone@2.0.0:
+    dependencies:
+      unicode-emoji-modifier-base: 1.0.0
+
   slash@3.0.0: {}
 
   sonner@2.0.7(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
@@ -17701,6 +17813,10 @@ snapshots:
 
   unicode-canonical-property-names-ecmascript@2.0.1: {}
 
+  unicode-emoji-json@0.8.0: {}
+
+  unicode-emoji-modifier-base@1.0.0: {}
+
   unicode-match-property-ecmascript@2.0.0:
     dependencies:
       unicode-canonical-property-names-ecmascript: 2.0.1

autogpt_platform/frontend/src/app/(platform)/copilot/helpers/convertChatSessionToUiMessages.ts

@@ -58,6 +58,7 @@ function toToolInput(rawArguments: unknown): unknown {
 export function convertChatSessionMessagesToUiMessages(
   sessionId: string,
   rawMessages: unknown[],
+  options?: { isComplete?: boolean },
 ): UIMessage<unknown, UIDataTypes, UITools>[] {
   const messages = coerceSessionChatMessages(rawMessages);
   const toolOutputsByCallId = new Map<string, unknown>();
@@ -104,6 +105,16 @@ export function convertChatSessionMessagesToUiMessages(
             input,
             output: typeof output === "string" ? safeJsonParse(output) : output,
           });
+        } else if (options?.isComplete) {
+          // Session is complete (no active stream) but this tool call has
+          // no output in the DB — mark as completed to stop stale spinners.
+          parts.push({
+            type: `tool-${toolName}`,
+            toolCallId,
+            state: "output-available",
+            input,
+            output: "",
+          });
         } else {
           parts.push({
             type: `tool-${toolName}`,

autogpt_platform/frontend/src/app/(platform)/copilot/styleguide/page.tsx

@@ -11,6 +11,11 @@ import {
   MessageResponse,
 } from "@/components/ai-elements/message";
 import { Text } from "@/components/atoms/Text/Text";
+import {
+  CredentialsProvidersContext,
+  type CredentialsProviderData,
+  type CredentialsProvidersContextType,
+} from "@/providers/agent-credentials/credentials-provider";
 import { CopilotChatActionsProvider } from "../components/CopilotChatActionsProvider/CopilotChatActionsProvider";
 import { CreateAgentTool } from "../tools/CreateAgent/CreateAgent";
 import { EditAgentTool } from "../tools/EditAgent/EditAgent";
@@ -97,6 +102,65 @@ function uid() {
   return `sg-${++_id}`;
 }
 
+// ---------------------------------------------------------------------------
+// Mock credential providers for setup-requirements demos
+// ---------------------------------------------------------------------------
+
+const noop = () => Promise.reject(new Error("Styleguide mock"));
+
+function makeMockProvider(
+  provider: string,
+  providerName: string,
+  savedCredentials: CredentialsProviderData["savedCredentials"] = [],
+): CredentialsProviderData {
+  return {
+    provider,
+    providerName,
+    savedCredentials,
+    isSystemProvider: false,
+    oAuthCallback: noop as CredentialsProviderData["oAuthCallback"],
+    mcpOAuthCallback: noop as CredentialsProviderData["mcpOAuthCallback"],
+    createAPIKeyCredentials:
+      noop as CredentialsProviderData["createAPIKeyCredentials"],
+    createUserPasswordCredentials:
+      noop as CredentialsProviderData["createUserPasswordCredentials"],
+    createHostScopedCredentials:
+      noop as CredentialsProviderData["createHostScopedCredentials"],
+    deleteCredentials: noop as CredentialsProviderData["deleteCredentials"],
+  };
+}
+
+/**
+ * Provider context where the user already has saved credentials
+ * so the credential picker shows a selection list.
+ */
+const MOCK_PROVIDERS_WITH_CREDENTIALS: CredentialsProvidersContextType = {
+  google: makeMockProvider("google", "Google", [
+    {
+      id: "cred-google-1",
+      provider: "google",
+      type: "oauth2",
+      title: "work@company.com",
+      scopes: ["email", "calendar"],
+    },
+    {
+      id: "cred-google-2",
+      provider: "google",
+      type: "oauth2",
+      title: "personal@gmail.com",
+      scopes: ["email", "calendar"],
+    },
+  ]),
+};
+
+/**
+ * Provider context where the user has NO saved credentials,
+ * so the credential picker shows an "add new" flow.
+ */
+const MOCK_PROVIDERS_WITHOUT_CREDENTIALS: CredentialsProvidersContextType = {
+  openweathermap: makeMockProvider("openweathermap", "OpenWeatherMap"),
+};
+
 // ---------------------------------------------------------------------------
 // Page
 // ---------------------------------------------------------------------------
@@ -554,45 +618,80 @@ export default function StyleguidePage() {
                 />
               </SubSection>
 
-              <SubSection label="Output available (setup requirements)">
-                <RunBlockTool
-                  part={{
-                    type: "tool-run_block",
-                    toolCallId: uid(),
-                    state: "output-available",
-                    input: { block_id: "weather-block-123" },
-                    output: {
-                      type: ResponseType.setup_requirements,
-                      message:
-                        "This block requires API credentials to run. Please configure them below.",
-                      setup_info: {
-                        agent_name: "Weather Agent",
-                        requirements: {
-                          inputs: [
-                            {
-                              name: "city",
-                              title: "City",
-                              type: "string",
-                              required: true,
-                              description: "The city to get weather for",
-                            },
-                          ],
-                        },
-                        user_readiness: {
-                          missing_credentials: {
-                            openweathermap: {
-                              provider: "openweathermap",
-                              credentials_type: "api_key",
-                              title: "OpenWeatherMap API Key",
-                              description:
-                                "Required to access weather data. Get your key at openweathermap.org",
+              <SubSection label="Setup requirements — no credentials (add new)">
+                <CredentialsProvidersContext.Provider
+                  value={MOCK_PROVIDERS_WITHOUT_CREDENTIALS}
+                >
+                  <RunBlockTool
+                    part={{
+                      type: "tool-run_block",
+                      toolCallId: uid(),
+                      state: "output-available",
+                      input: { block_id: "weather-block-123" },
+                      output: {
+                        type: ResponseType.setup_requirements,
+                        message:
+                          "This block requires API credentials to run. Please configure them below.",
+                        setup_info: {
+                          agent_id: "agent-weather-1",
+                          agent_name: "Weather Agent",
+                          requirements: {
+                            inputs: [
+                              {
+                                name: "city",
+                                title: "City",
+                                type: "string",
+                                required: true,
+                                description: "The city to get weather for",
+                              },
+                            ],
+                          },
+                          user_readiness: {
+                            missing_credentials: {
+                              openweathermap_key: {
+                                provider: "openweathermap",
+                                types: ["api_key"],
+                              },
                             },
                           },
                         },
                       },
-                    },
-                  }}
-                />
+                    }}
+                  />
+                </CredentialsProvidersContext.Provider>
+              </SubSection>
+
+              <SubSection label="Setup requirements — has credentials (pick from list)">
+                <CredentialsProvidersContext.Provider
+                  value={MOCK_PROVIDERS_WITH_CREDENTIALS}
+                >
+                  <RunBlockTool
+                    part={{
+                      type: "tool-run_block",
+                      toolCallId: uid(),
+                      state: "output-available",
+                      input: { block_id: "calendar-block-456" },
+                      output: {
+                        type: ResponseType.setup_requirements,
+                        message:
+                          "This block requires Google credentials. Pick an account below or connect a new one.",
+                        setup_info: {
+                          agent_id: "agent-calendar-1",
+                          agent_name: "Calendar Agent",
+                          user_readiness: {
+                            missing_credentials: {
+                              google_oauth: {
+                                provider: "google",
+                                types: ["oauth2"],
+                                scopes: ["email", "calendar"],
+                              },
+                            },
+                          },
+                        },
+                      },
+                    }}
+                  />
+                </CredentialsProvidersContext.Provider>
               </SubSection>
 
               <SubSection label="Output available (error)">
@@ -849,34 +948,71 @@ export default function StyleguidePage() {
                 />
               </SubSection>
 
-              <SubSection label="Output available (setup requirements)">
-                <RunAgentTool
-                  part={{
-                    type: "tool-run_agent",
-                    toolCallId: uid(),
-                    state: "output-available",
-                    input: { username_agent_slug: "creator/my-agent" },
-                    output: {
-                      type: ResponseType.setup_requirements,
-                      message: "This agent requires additional setup.",
-                      setup_info: {
-                        agent_name: "YouTube Summarizer",
-                        requirements: {},
-                        user_readiness: {
-                          missing_credentials: {
-                            youtube_api: {
-                              provider: "youtube",
-                              credentials_type: "api_key",
-                              title: "YouTube Data API Key",
-                              description:
-                                "Required to access YouTube video data.",
+              <SubSection label="Setup requirements — no credentials (add new)">
+                <CredentialsProvidersContext.Provider
+                  value={MOCK_PROVIDERS_WITHOUT_CREDENTIALS}
+                >
+                  <RunAgentTool
+                    part={{
+                      type: "tool-run_agent",
+                      toolCallId: uid(),
+                      state: "output-available",
+                      input: { username_agent_slug: "creator/weather-agent" },
+                      output: {
+                        type: ResponseType.setup_requirements,
+                        message:
+                          "This agent requires an API key. Add your credentials below.",
+                        setup_info: {
+                          agent_id: "agent-weather-1",
+                          agent_name: "Weather Agent",
+                          requirements: {},
+                          user_readiness: {
+                            missing_credentials: {
+                              openweathermap_key: {
+                                provider: "openweathermap",
+                                types: ["api_key"],
+                              },
                             },
                           },
                         },
                       },
-                    },
-                  }}
-                />
+                    }}
+                  />
+                </CredentialsProvidersContext.Provider>
+              </SubSection>
+
+              <SubSection label="Setup requirements — has credentials (pick from list)">
+                <CredentialsProvidersContext.Provider
+                  value={MOCK_PROVIDERS_WITH_CREDENTIALS}
+                >
+                  <RunAgentTool
+                    part={{
+                      type: "tool-run_agent",
+                      toolCallId: uid(),
+                      state: "output-available",
+                      input: { username_agent_slug: "creator/calendar-agent" },
+                      output: {
+                        type: ResponseType.setup_requirements,
+                        message:
+                          "This agent needs Google credentials. Pick an account or connect a new one.",
+                        setup_info: {
+                          agent_id: "agent-calendar-1",
+                          agent_name: "Google Calendar Agent",
+                          requirements: {},
+                          user_readiness: {
+                            missing_credentials: {
+                              google_oauth: {
+                                provider: "google",
+                                types: ["oauth2"],
+                                scopes: ["email", "calendar"],
+                              },
+                            },
+                          },
+                        },
+                      },
+                    }}
+                  />
+                </CredentialsProvidersContext.Provider>
               </SubSection>
 
               <SubSection label="Output available (need login)">

autogpt_platform/frontend/src/app/(platform)/copilot/tools/CreateAgent/CreateAgent.tsx

@@ -16,7 +16,6 @@ import {
   ContentCardDescription,
   ContentCodeBlock,
   ContentGrid,
-  ContentHint,
   ContentMessage,
 } from "../../components/ToolAccordion/AccordionContent";
 import { ToolAccordion } from "../../components/ToolAccordion/ToolAccordion";
@@ -24,8 +23,8 @@ import {
   ClarificationQuestionsCard,
   ClarifyingQuestion,
 } from "./components/ClarificationQuestionsCard";
-import sparklesImg from "./components/MiniGame/assets/sparkles.png";
-import { MiniGame } from "./components/MiniGame/MiniGame";
+import sparklesImg from "../../components/MiniGame/assets/sparkles.png";
+import { MiniGame } from "../../components/MiniGame/MiniGame";
 import { SuggestedGoalCard } from "./components/SuggestedGoalCard";
 import {
   AccordionIcon,
@@ -93,9 +92,7 @@ function getAccordionMeta(output: CreateAgentToolOutput) {
   ) {
     return {
       icon,
-      title:
-        "Creating agent, this may take a few minutes. Play while you wait.",
-      expanded: true,
+      title: output.message || "Agent creation started",
     };
   }
   return {
@@ -169,15 +166,22 @@ export function CreateAgentTool({ part }: Props) {
         />
       </div>
 
+      {isStreaming && (
+        <ToolAccordion
+          icon={<AccordionIcon />}
+          title="Creating agent, this may take a few minutes. Play while you wait."
+          expanded
+        >
+          <ContentGrid>
+            <MiniGame />
+          </ContentGrid>
+        </ToolAccordion>
+      )}
+
       {hasExpandableContent && output && (
         <ToolAccordion {...getAccordionMeta(output)}>
-          {isOperating && (
-            <ContentGrid>
-              <MiniGame />
-              <ContentHint>
-                This could take a few minutes — play while you wait!
-              </ContentHint>
-            </ContentGrid>
+          {isOperating && output.message && (
+            <ContentMessage>{output.message}</ContentMessage>
           )}
 
           {isAgentSavedOutput(output) && (

autogpt_platform/frontend/src/app/(platform)/copilot/tools/EditAgent/EditAgent.tsx

@@ -4,17 +4,15 @@ import { WarningDiamondIcon } from "@phosphor-icons/react";
 import type { ToolUIPart } from "ai";
 import { useCopilotChatActions } from "../../components/CopilotChatActionsProvider/useCopilotChatActions";
 import { MorphingTextAnimation } from "../../components/MorphingTextAnimation/MorphingTextAnimation";
-import { OrbitLoader } from "../../components/OrbitLoader/OrbitLoader";
 import {
   ContentCardDescription,
   ContentCodeBlock,
   ContentGrid,
-  ContentHint,
   ContentLink,
   ContentMessage,
 } from "../../components/ToolAccordion/AccordionContent";
 import { ToolAccordion } from "../../components/ToolAccordion/ToolAccordion";
-import { MiniGame } from "../CreateAgent/components/MiniGame/MiniGame";
+import { MiniGame } from "../../components/MiniGame/MiniGame";
 import {
   ClarificationQuestionsCard,
   ClarifyingQuestion,
@@ -81,9 +79,8 @@ function getAccordionMeta(output: EditAgentToolOutput): {
     isOperationInProgressOutput(output)
   ) {
     return {
-      icon: <OrbitLoader size={32} />,
-      title: "Editing agent, this may take a few minutes. Play while you wait.",
-      expanded: true,
+      icon,
+      title: output.message || "Agent editing started",
     };
   }
   return {
@@ -148,15 +145,22 @@ export function EditAgentTool({ part }: Props) {
         />
       </div>
 
+      {isStreaming && (
+        <ToolAccordion
+          icon={<AccordionIcon />}
+          title="Editing agent, this may take a few minutes. Play while you wait."
+          expanded
+        >
+          <ContentGrid>
+            <MiniGame />
+          </ContentGrid>
+        </ToolAccordion>
+      )}
+
       {hasExpandableContent && output && (
         <ToolAccordion {...getAccordionMeta(output)}>
-          {isOperating && (
-            <ContentGrid>
-              <MiniGame />
-              <ContentHint>
-                This could take a few minutes — play while you wait!
-              </ContentHint>
-            </ContentGrid>
+          {isOperating && output.message && (
+            <ContentMessage>{output.message}</ContentMessage>
           )}
 
           {isAgentSavedOutput(output) && (

autogpt_platform/frontend/src/app/(platform)/copilot/tools/RunAgent/RunAgent.tsx

@@ -9,7 +9,7 @@ import {
   ContentHint,
   ContentMessage,
 } from "../../components/ToolAccordion/AccordionContent";
-import { MiniGame } from "../CreateAgent/components/MiniGame/MiniGame";
+import { MiniGame } from "../../components/MiniGame/MiniGame";
 import {
   getAccordionMeta,
   getAnimationText,
@@ -47,14 +47,25 @@ export function RunAgentTool({ part }: Props) {
   const isError =
     part.state === "output-error" ||
     (!!output && isRunAgentErrorOutput(output));
+  const isOutputAvailable = part.state === "output-available" && !!output;
+
+  const setupRequirementsOutput =
+    isOutputAvailable && isRunAgentSetupRequirementsOutput(output)
+      ? output
+      : null;
+
+  const agentDetailsOutput =
+    isOutputAvailable && isRunAgentAgentDetailsOutput(output) ? output : null;
+
+  const needLoginOutput =
+    isOutputAvailable && isRunAgentNeedLoginOutput(output) ? output : null;
+
   const hasExpandableContent =
-    part.state === "output-available" &&
-    !!output &&
-    (isRunAgentExecutionStartedOutput(output) ||
-      isRunAgentAgentDetailsOutput(output) ||
-      isRunAgentSetupRequirementsOutput(output) ||
-      isRunAgentNeedLoginOutput(output) ||
-      isRunAgentErrorOutput(output));
+    isOutputAvailable &&
+    !setupRequirementsOutput &&
+    !agentDetailsOutput &&
+    !needLoginOutput &&
+    (isRunAgentExecutionStartedOutput(output) || isRunAgentErrorOutput(output));
 
   return (
     <div className="py-2">
@@ -81,24 +92,30 @@ export function RunAgentTool({ part }: Props) {
         </ToolAccordion>
       )}
 
+      {setupRequirementsOutput && (
+        <div className="mt-2">
+          <SetupRequirementsCard output={setupRequirementsOutput} />
+        </div>
+      )}
+
+      {agentDetailsOutput && (
+        <div className="mt-2">
+          <AgentDetailsCard output={agentDetailsOutput} />
+        </div>
+      )}
+
+      {needLoginOutput && (
+        <div className="mt-2">
+          <ContentMessage>{needLoginOutput.message}</ContentMessage>
+        </div>
+      )}
+
       {hasExpandableContent && output && (
         <ToolAccordion {...getAccordionMeta(output)}>
           {isRunAgentExecutionStartedOutput(output) && (
             <ExecutionStartedCard output={output} />
           )}
 
-          {isRunAgentAgentDetailsOutput(output) && (
-            <AgentDetailsCard output={output} />
-          )}
-
-          {isRunAgentSetupRequirementsOutput(output) && (
-            <SetupRequirementsCard output={output} />
-          )}
-
-          {isRunAgentNeedLoginOutput(output) && (
-            <ContentMessage>{output.message}</ContentMessage>
-          )}
-
           {isRunAgentErrorOutput(output) && <ErrorCard output={output} />}
         </ToolAccordion>
       )}

autogpt_platform/frontend/src/app/(platform)/copilot/tools/RunAgent/components/SetupRequirementsCard/SetupRequirementsCard.tsx

@@ -1,10 +1,11 @@
 "use client";
 
-import { useState } from "react";
-import { CredentialsGroupedView } from "@/components/contextual/CredentialsInput/components/CredentialsGroupedView/CredentialsGroupedView";
-import { Button } from "@/components/atoms/Button/Button";
-import type { CredentialsMetaInput } from "@/lib/autogpt-server-api/types";
 import type { SetupRequirementsResponse } from "@/app/api/__generated__/models/setupRequirementsResponse";
+import { Button } from "@/components/atoms/Button/Button";
+import { Text } from "@/components/atoms/Text/Text";
+import { CredentialsGroupedView } from "@/components/contextual/CredentialsInput/components/CredentialsGroupedView/CredentialsGroupedView";
+import type { CredentialsMetaInput } from "@/lib/autogpt-server-api/types";
+import { useState } from "react";
 import { useCopilotChatActions } from "../../../../components/CopilotChatActionsProvider/useCopilotChatActions";
 import {
   ContentBadge,
@@ -38,40 +39,40 @@ export function SetupRequirementsCard({ output }: Props) {
     setInputCredentials((prev) => ({ ...prev, [key]: value }));
   }
 
-  const isAllComplete =
-    credentialFields.length > 0 &&
+  const needsCredentials = credentialFields.length > 0;
+  const isAllCredentialsComplete =
+    needsCredentials &&
     [...requiredCredentials].every((key) => !!inputCredentials[key]);
 
+  const canProceed =
+    !hasSent && (!needsCredentials || isAllCredentialsComplete);
+
   function handleProceed() {
     setHasSent(true);
-    onSend(
-      "I've configured the required credentials. Please check if everything is ready and proceed with running the agent.",
-    );
+    const message = needsCredentials
+      ? "I've configured the required credentials. Please check if everything is ready and proceed with running the agent."
+      : "Please proceed with running the agent.";
+    onSend(message);
   }
 
   return (
     <div className="grid gap-2">
       <ContentMessage>{output.message}</ContentMessage>
 
-      {credentialFields.length > 0 && (
+      {needsCredentials && (
         <div className="rounded-2xl border bg-background p-3">
-          <CredentialsGroupedView
-            credentialFields={credentialFields}
-            requiredCredentials={requiredCredentials}
-            inputCredentials={inputCredentials}
-            inputValues={{}}
-            onCredentialChange={handleCredentialChange}
-          />
-          {isAllComplete && !hasSent && (
-            <Button
-              variant="primary"
-              size="small"
-              className="mt-3 w-full"
-              onClick={handleProceed}
-            >
-              Proceed
-            </Button>
-          )}
+          <Text variant="small" className="w-fit border-b text-zinc-500">
+            Agent credentials
+          </Text>
+          <div className="mt-6">
+            <CredentialsGroupedView
+              credentialFields={credentialFields}
+              requiredCredentials={requiredCredentials}
+              inputCredentials={inputCredentials}
+              inputValues={{}}
+              onCredentialChange={handleCredentialChange}
+            />
+          </div>
         </div>
       )}
 
@@ -100,6 +101,18 @@ export function SetupRequirementsCard({ output }: Props) {
           </div>
         </div>
       )}
+
+      {(needsCredentials || expectedInputs.length > 0) && (
+        <Button
+          variant="primary"
+          size="small"
+          className="mt-4 w-fit"
+          disabled={!canProceed}
+          onClick={handleProceed}
+        >
+          Proceed
+        </Button>
+      )}
     </div>
   );
 }

autogpt_platform/frontend/src/app/(platform)/copilot/tools/RunBlock/RunBlock.tsx

@@ -39,12 +39,19 @@ export function RunBlockTool({ part }: Props) {
   const isError =
     part.state === "output-error" ||
     (!!output && isRunBlockErrorOutput(output));
+  const setupRequirementsOutput =
+    part.state === "output-available" &&
+    output &&
+    isRunBlockSetupRequirementsOutput(output)
+      ? output
+      : null;
+
   const hasExpandableContent =
     part.state === "output-available" &&
     !!output &&
+    !setupRequirementsOutput &&
     (isRunBlockBlockOutput(output) ||
       isRunBlockDetailsOutput(output) ||
-      isRunBlockSetupRequirementsOutput(output) ||
       isRunBlockErrorOutput(output));
 
   return (
@@ -57,6 +64,12 @@ export function RunBlockTool({ part }: Props) {
         />
       </div>
 
+      {setupRequirementsOutput && (
+        <div className="mt-2">
+          <SetupRequirementsCard output={setupRequirementsOutput} />
+        </div>
+      )}
+
       {hasExpandableContent && output && (
         <ToolAccordion {...getAccordionMeta(output)}>
           {isRunBlockBlockOutput(output) && <BlockOutputCard output={output} />}
@@ -65,10 +78,6 @@ export function RunBlockTool({ part }: Props) {
             <BlockDetailsCard output={output} />
           )}
 
-          {isRunBlockSetupRequirementsOutput(output) && (
-            <SetupRequirementsCard output={output} />
-          )}
-
           {isRunBlockErrorOutput(output) && <ErrorCard output={output} />}
         </ToolAccordion>
       )}

autogpt_platform/frontend/src/app/(platform)/copilot/tools/RunBlock/components/SetupRequirementsCard/SetupRequirementsCard.tsx

@@ -6,15 +6,9 @@ import { Text } from "@/components/atoms/Text/Text";
 import { CredentialsGroupedView } from "@/components/contextual/CredentialsInput/components/CredentialsGroupedView/CredentialsGroupedView";
 import { FormRenderer } from "@/components/renderers/InputRenderer/FormRenderer";
 import type { CredentialsMetaInput } from "@/lib/autogpt-server-api/types";
-import { AnimatePresence, motion } from "framer-motion";
 import { useState } from "react";
 import { useCopilotChatActions } from "../../../../components/CopilotChatActionsProvider/useCopilotChatActions";
-import {
-  ContentBadge,
-  ContentCardDescription,
-  ContentCardTitle,
-  ContentMessage,
-} from "../../../../components/ToolAccordion/AccordionContent";
+import { ContentMessage } from "../../../../components/ToolAccordion/AccordionContent";
 import {
   buildExpectedInputsSchema,
   coerceCredentialFields,
@@ -31,10 +25,8 @@ export function SetupRequirementsCard({ output }: Props) {
   const [inputCredentials, setInputCredentials] = useState<
     Record<string, CredentialsMetaInput | undefined>
   >({});
-  const [hasSentCredentials, setHasSentCredentials] = useState(false);
-
-  const [showInputForm, setShowInputForm] = useState(false);
   const [inputValues, setInputValues] = useState<Record<string, unknown>>({});
+  const [hasSent, setHasSent] = useState(false);
 
   const { credentialFields, requiredCredentials } = coerceCredentialFields(
     output.setup_info.user_readiness?.missing_credentials,
@@ -50,27 +42,49 @@ export function SetupRequirementsCard({ output }: Props) {
     setInputCredentials((prev) => ({ ...prev, [key]: value }));
   }
 
+  const needsCredentials = credentialFields.length > 0;
   const isAllCredentialsComplete =
-    credentialFields.length > 0 &&
+    needsCredentials &&
     [...requiredCredentials].every((key) => !!inputCredentials[key]);
 
-  function handleProceedCredentials() {
-    setHasSentCredentials(true);
-    onSend(
-      "I've configured the required credentials. Please re-run the block now.",
-    );
-  }
+  const needsInputs = inputSchema !== null;
+  const requiredInputNames = expectedInputs
+    .filter((i) => i.required)
+    .map((i) => i.name);
+  const isAllInputsComplete =
+    needsInputs &&
+    requiredInputNames.every((name) => {
+      const v = inputValues[name];
+      return v !== undefined && v !== null && v !== "";
+    });
 
-  function handleRunWithInputs() {
-    const nonEmpty = Object.fromEntries(
-      Object.entries(inputValues).filter(
-        ([, v]) => v !== undefined && v !== null && v !== "",
-      ),
-    );
-    onSend(
-      `Run the block with these inputs: ${JSON.stringify(nonEmpty, null, 2)}`,
-    );
-    setShowInputForm(false);
+  const canRun =
+    !hasSent &&
+    (!needsCredentials || isAllCredentialsComplete) &&
+    (!needsInputs || isAllInputsComplete);
+
+  function handleRun() {
+    setHasSent(true);
+
+    const parts: string[] = [];
+    if (needsCredentials) {
+      parts.push("I've configured the required credentials.");
+    }
+
+    if (needsInputs) {
+      const nonEmpty = Object.fromEntries(
+        Object.entries(inputValues).filter(
+          ([, v]) => v !== undefined && v !== null && v !== "",
+        ),
+      );
+      parts.push(
+        `Run the block with these inputs: ${JSON.stringify(nonEmpty, null, 2)}`,
+      );
+    } else {
+      parts.push("Please re-run the block now.");
+    }
+
+    onSend(parts.join(" "));
     setInputValues({});
   }
 
@@ -78,119 +92,54 @@ export function SetupRequirementsCard({ output }: Props) {
     <div className="grid gap-2">
       <ContentMessage>{output.message}</ContentMessage>
 
-      {credentialFields.length > 0 && (
+      {needsCredentials && (
         <div className="rounded-2xl border bg-background p-3">
-          <CredentialsGroupedView
-            credentialFields={credentialFields}
-            requiredCredentials={requiredCredentials}
-            inputCredentials={inputCredentials}
-            inputValues={{}}
-            onCredentialChange={handleCredentialChange}
-          />
-          {isAllCredentialsComplete && !hasSentCredentials && (
-            <Button
-              variant="primary"
-              size="small"
-              className="mt-3 w-full"
-              onClick={handleProceedCredentials}
-            >
-              Proceed
-            </Button>
-          )}
+          <Text variant="small" className="w-fit border-b text-zinc-500">
+            Block credentials
+          </Text>
+          <div className="mt-6">
+            <CredentialsGroupedView
+              credentialFields={credentialFields}
+              requiredCredentials={requiredCredentials}
+              inputCredentials={inputCredentials}
+              inputValues={{}}
+              onCredentialChange={handleCredentialChange}
+            />
+          </div>
         </div>
       )}
 
       {inputSchema && (
-        <div className="flex gap-2 pt-2">
-          <Button
-            variant="outline"
-            size="small"
-            className="w-fit"
-            onClick={() => setShowInputForm((prev) => !prev)}
-          >
-            {showInputForm ? "Hide inputs" : "Fill in inputs"}
-          </Button>
+        <div className="rounded-2xl border bg-background p-3 pt-4">
+          <Text variant="small" className="w-fit border-b text-zinc-500">
+            Block inputs
+          </Text>
+          <FormRenderer
+            jsonSchema={inputSchema}
+            className="mb-3 mt-3"
+            handleChange={(v) => setInputValues(v.formData ?? {})}
+            uiSchema={{
+              "ui:submitButtonOptions": { norender: true },
+            }}
+            initialValues={inputValues}
+            formContext={{
+              showHandles: false,
+              size: "small",
+            }}
+          />
         </div>
       )}
 
-      <AnimatePresence initial={false}>
-        {showInputForm && inputSchema && (
-          <motion.div
-            initial={{ height: 0, opacity: 0, filter: "blur(6px)" }}
-            animate={{ height: "auto", opacity: 1, filter: "blur(0px)" }}
-            exit={{ height: 0, opacity: 0, filter: "blur(6px)" }}
-            transition={{
-              height: { type: "spring", bounce: 0.15, duration: 0.5 },
-              opacity: { duration: 0.25 },
-              filter: { duration: 0.2 },
-            }}
-            className="overflow-hidden"
-            style={{ willChange: "height, opacity, filter" }}
-          >
-            <div className="rounded-2xl border bg-background p-3 pt-4">
-              <Text variant="body-medium">Block inputs</Text>
-              <FormRenderer
-                jsonSchema={inputSchema}
-                handleChange={(v) => setInputValues(v.formData ?? {})}
-                uiSchema={{
-                  "ui:submitButtonOptions": { norender: true },
-                }}
-                initialValues={inputValues}
-                formContext={{
-                  showHandles: false,
-                  size: "small",
-                }}
-              />
-              <div className="-mt-8 flex gap-2">
-                <Button
-                  variant="primary"
-                  size="small"
-                  className="w-fit"
-                  onClick={handleRunWithInputs}
-                >
-                  Run
-                </Button>
-                <Button
-                  variant="secondary"
-                  size="small"
-                  className="w-fit"
-                  onClick={() => {
-                    setShowInputForm(false);
-                    setInputValues({});
-                  }}
-                >
-                  Cancel
-                </Button>
-              </div>
-            </div>
-          </motion.div>
-        )}
-      </AnimatePresence>
-
-      {expectedInputs.length > 0 && !inputSchema && (
-        <div className="rounded-2xl border bg-background p-3">
-          <ContentCardTitle className="text-xs">
-            Expected inputs
-          </ContentCardTitle>
-          <div className="mt-2 grid gap-2">
-            {expectedInputs.map((input) => (
-              <div key={input.name} className="rounded-xl border p-2">
-                <div className="flex items-center justify-between gap-2">
-                  <ContentCardTitle className="text-xs">
-                    {input.title}
-                  </ContentCardTitle>
-                  <ContentBadge>
-                    {input.required ? "Required" : "Optional"}
-                  </ContentBadge>
-                </div>
-                <ContentCardDescription className="mt-1">
-                  {input.name} &bull; {input.type}
-                  {input.description ? ` \u2022 ${input.description}` : ""}
-                </ContentCardDescription>
-              </div>
-            ))}
-          </div>
-        </div>
+      {(needsCredentials || needsInputs) && (
+        <Button
+          variant="primary"
+          size="small"
+          className="w-fit"
+          disabled={!canRun}
+          onClick={handleRun}
+        >
+          Proceed
+        </Button>
       )}
     </div>
   );

autogpt_platform/frontend/src/app/(platform)/copilot/useChatSession.ts

@@ -40,16 +40,6 @@ export function useChatSession() {
     }
   }, [sessionId, queryClient]);
 
-  // Memoize so the effect in useCopilotPage doesn't infinite-loop on a new
-  // array reference every render. Re-derives only when query data changes.
-  const hydratedMessages = useMemo(() => {
-    if (sessionQuery.data?.status !== 200 || !sessionId) return undefined;
-    return convertChatSessionMessagesToUiMessages(
-      sessionId,
-      sessionQuery.data.data.messages ?? [],
-    );
-  }, [sessionQuery.data, sessionId]);
-
   // Expose active_stream info so the caller can trigger manual resume
   // after hydration completes (rather than relying on AI SDK's built-in
   // resume which fires before hydration).
@@ -58,6 +48,19 @@ export function useChatSession() {
     return !!sessionQuery.data.data.active_stream;
   }, [sessionQuery.data]);
 
+  // Memoize so the effect in useCopilotPage doesn't infinite-loop on a new
+  // array reference every render. Re-derives only when query data changes.
+  // When the session is complete (no active stream), mark dangling tool
+  // calls as completed so stale spinners don't persist after refresh.
+  const hydratedMessages = useMemo(() => {
+    if (sessionQuery.data?.status !== 200 || !sessionId) return undefined;
+    return convertChatSessionMessagesToUiMessages(
+      sessionId,
+      sessionQuery.data.data.messages ?? [],
+      { isComplete: !hasActiveStream },
+    );
+  }, [sessionQuery.data, sessionId, hasActiveStream]);
+
   const { mutateAsync: createSessionMutation, isPending: isCreatingSession } =
     usePostV2CreateSession({
       mutation: {

autogpt_platform/frontend/src/app/(platform)/copilot/useCopilotPage.ts

@@ -1,4 +1,5 @@
 import {
+  getGetV2GetSessionQueryKey,
   getGetV2ListSessionsQueryKey,
   postV2CancelSessionTask,
   useDeleteV2DeleteSession,
@@ -187,11 +188,35 @@ export function useCopilotPage() {
     });
   }, [hydratedMessages, setMessages, status]);
 
+  // Ref: tracks whether we've already resumed for a given session.
+  // Reset when the stream ends so re-resume is possible if the backend
+  // task is still running (SSE dropped but executor didn't finish).
+  const hasResumedRef = useRef<string | null>(null);
+
+  // When the stream ends (or drops), invalidate the session cache so the
+  // next hydration fetches fresh messages from the backend.  Without this,
+  // staleTime: Infinity means the cache keeps the pre-stream data forever,
+  // and any messages added during streaming are lost on remount/navigation.
+  const prevStatusRef = useRef(status);
+  useEffect(() => {
+    const prev = prevStatusRef.current;
+    prevStatusRef.current = status;
+
+    const wasActive = prev === "streaming" || prev === "submitted";
+    const isIdle = status === "ready" || status === "error";
+    if (wasActive && isIdle && sessionId) {
+      queryClient.invalidateQueries({
+        queryKey: getGetV2GetSessionQueryKey(sessionId),
+      });
+      // Allow re-resume if the backend task is still running.
+      hasResumedRef.current = null;
+    }
+  }, [status, sessionId, queryClient]);
+
   // Resume an active stream AFTER hydration completes.
   // The backend returns active_stream info when a task is still running.
   // We wait for hydration so the AI SDK has the conversation history
   // before the resumed stream appends the in-progress assistant message.
-  const hasResumedRef = useRef<string | null>(null);
   useEffect(() => {
     if (!hasActiveStream || !sessionId) return;
     if (!hydratedMessages || hydratedMessages.length === 0) return;
@@ -202,18 +227,6 @@ export function useCopilotPage() {
     resumeStream();
   }, [hasActiveStream, sessionId, hydratedMessages, status, resumeStream]);
 
-  // When the stream finishes, resolve any tool parts still showing spinners.
-  // This can happen if the backend didn't emit StreamToolOutputAvailable for
-  // a tool call before sending StreamFinish (e.g. SDK built-in tools).
-  const prevStatusRef = useRef(status);
-  useEffect(() => {
-    const prev = prevStatusRef.current;
-    prevStatusRef.current = status;
-    if (prev === "streaming" && status === "ready") {
-      setMessages((msgs) => resolveInProgressTools(msgs, "completed"));
-    }
-  }, [status, setMessages]);
-
   // Poll session endpoint when a long-running tool (create_agent, edit_agent)
   // is in progress. When the backend completes, the session data will contain
   // the final tool output — this hook detects the change and updates messages.

autogpt_platform/frontend/src/app/(platform)/library/components/FavoritesSection/FavoritesSection.tsx

@@ -1,17 +1,31 @@
 "use client";
 
 import { LibraryAgent } from "@/app/api/__generated__/models/libraryAgent";
+import { LibraryAgentSort } from "@/app/api/__generated__/models/libraryAgentSort";
 import { Text } from "@/components/atoms/Text/Text";
+import { LoadingSpinner } from "@/components/atoms/LoadingSpinner/LoadingSpinner";
 import { InfiniteScroll } from "@/components/contextual/InfiniteScroll/InfiniteScroll";
 import { HeartIcon } from "@phosphor-icons/react";
 import { useFavoriteAgents } from "../../hooks/useFavoriteAgents";
 import { LibraryAgentCard } from "../LibraryAgentCard/LibraryAgentCard";
+import { LibraryTabs, Tab } from "../LibraryTabs/LibraryTabs";
+import { LibraryActionSubHeader } from "../LibraryActionSubHeader/LibraryActionSubHeader";
 
 interface Props {
   searchTerm: string;
+  tabs: Tab[];
+  activeTab: string;
+  onTabChange: (tabId: string) => void;
+  setLibrarySort: (value: LibraryAgentSort) => void;
 }
 
-export function FavoritesSection({ searchTerm }: Props) {
+export function FavoritesSection({
+  searchTerm,
+  tabs,
+  activeTab,
+  onTabChange,
+  setLibrarySort,
+}: Props) {
   const {
     allAgents: favoriteAgents,
     agentLoading: isLoading,
@@ -21,38 +35,33 @@ export function FavoritesSection({ searchTerm }: Props) {
     isFetchingNextPage,
   } = useFavoriteAgents({ searchTerm });
 
-  if (isLoading || favoriteAgents.length === 0) {
-    return null;
-  }
-
   return (
-    <div className="!mb-8">
-      <div className="mb-3 flex items-center gap-2 p-2">
-        <HeartIcon className="h-5 w-5" weight="fill" />
-        <div className="flex items-baseline gap-2">
-          <Text variant="h4">Favorites</Text>
-          {!isLoading && (
-            <Text
-              variant="body"
-              data-testid="agents-count"
-              className="relative bottom-px text-zinc-500"
-            >
-              {agentCount}
-            </Text>
-          )}
-        </div>
-      </div>
+    <>
+      <LibraryActionSubHeader
+        agentCount={agentCount}
+        setLibrarySort={setLibrarySort}
+      />
+      <LibraryTabs
+        tabs={tabs}
+        activeTab={activeTab}
+        onTabChange={onTabChange}
+      />
 
-      <div className="relative">
+      {isLoading ? (
+        <div className="flex h-[200px] items-center justify-center">
+          <LoadingSpinner size="large" />
+        </div>
+      ) : favoriteAgents.length === 0 ? (
+        <div className="flex h-[200px] flex-col items-center justify-center gap-2 text-zinc-500">
+          <HeartIcon className="h-10 w-10" />
+          <Text variant="body">No favorite agents yet</Text>
+        </div>
+      ) : (
         <InfiniteScroll
           isFetchingNextPage={isFetchingNextPage}
           fetchNextPage={fetchNextPage}
           hasNextPage={hasNextPage}
-          loader={
-            <div className="flex h-8 w-full items-center justify-center">
-              <div className="h-6 w-6 animate-spin rounded-full border-b-2 border-t-2 border-neutral-800" />
-            </div>
-          }
+          loader={<LoadingSpinner size="medium" />}
         >
           <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
             {favoriteAgents.map((agent: LibraryAgent) => (
@@ -60,9 +69,7 @@ export function FavoritesSection({ searchTerm }: Props) {
             ))}
           </div>
         </InfiniteScroll>
-      </div>
-
-      {favoriteAgents.length > 0 && <div className="!mt-10 border-t" />}
-    </div>
+      )}
+    </>
   );
 }

autogpt_platform/frontend/src/app/(platform)/library/components/FlyingHeart/FlyingHeart.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+import { motion, AnimatePresence } from "framer-motion";
+import { HeartIcon } from "@phosphor-icons/react";
+import { useEffect, useState } from "react";
+
+interface FlyingHeartProps {
+  startPosition: { x: number; y: number } | null;
+  targetPosition: { x: number; y: number } | null;
+  onAnimationComplete: () => void;
+}
+
+export function FlyingHeart({
+  startPosition,
+  targetPosition,
+  onAnimationComplete,
+}: FlyingHeartProps) {
+  const [isVisible, setIsVisible] = useState(false);
+
+  useEffect(() => {
+    if (startPosition && targetPosition) {
+      setIsVisible(true);
+    }
+  }, [startPosition, targetPosition]);
+
+  if (!startPosition || !targetPosition) return null;
+
+  return (
+    <AnimatePresence>
+      {isVisible && (
+        <motion.div
+          className="pointer-events-none fixed z-50"
+          initial={{
+            x: startPosition.x,
+            y: startPosition.y,
+            scale: 1,
+            opacity: 1,
+          }}
+          animate={{
+            x: targetPosition.x,
+            y: targetPosition.y,
+            scale: 0.5,
+            opacity: 0,
+          }}
+          exit={{ opacity: 0 }}
+          transition={{
+            type: "spring",
+            damping: 20,
+            stiffness: 200,
+            duration: 0.5,
+          }}
+          onAnimationComplete={() => {
+            setIsVisible(false);
+            onAnimationComplete();
+          }}
+        >
+          <HeartIcon
+            size={24}
+            weight="fill"
+            className="text-red-500 drop-shadow-md"
+          />
+        </motion.div>
+      )}
+    </AnimatePresence>
+  );
+}

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryActionSubHeader/LibraryActionSubHeader.tsx

@@ -13,7 +13,7 @@ export function LibraryActionSubHeader({ agentCount, setLibrarySort }: Props) {
   return (
     <div className="flex items-baseline justify-between">
       <div className="flex items-baseline gap-4">
-        <Text variant="h4">My agents</Text>
+        <Text variant="h5">My agents</Text>
         <Text
           variant="body"
           data-testid="agents-count"

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryAgentCard/LibraryAgentCard.tsx

@@ -4,6 +4,7 @@ import { Text } from "@/components/atoms/Text/Text";
 import { CaretCircleRightIcon } from "@phosphor-icons/react";
 import Image from "next/image";
 import NextLink from "next/link";
+import { motion } from "framer-motion";
 
 import { LibraryAgent } from "@/app/api/__generated__/models/libraryAgent";
 import Avatar, {
@@ -14,13 +15,21 @@ import { Link } from "@/components/atoms/Link/Link";
 import { AgentCardMenu } from "./components/AgentCardMenu";
 import { FavoriteButton } from "./components/FavoriteButton";
 import { useLibraryAgentCard } from "./useLibraryAgentCard";
+import { useFavoriteAnimation } from "../../context/FavoriteAnimationContext";
 
 interface Props {
   agent: LibraryAgent;
+  draggable?: boolean;
 }
 
-export function LibraryAgentCard({ agent }: Props) {
+export function LibraryAgentCard({ agent, draggable = true }: Props) {
   const { id, name, graph_id, can_access_graph, image_url } = agent;
+  const { triggerFavoriteAnimation } = useFavoriteAnimation();
+
+  function handleDragStart(e: React.DragEvent<HTMLDivElement>) {
+    e.dataTransfer.setData("application/agent-id", id);
+    e.dataTransfer.effectAllowed = "move";
+  }
 
   const {
     isFromMarketplace,
@@ -28,103 +37,119 @@ export function LibraryAgentCard({ agent }: Props) {
     profile,
     creator_image_url,
     handleToggleFavorite,
-  } = useLibraryAgentCard({ agent });
+  } = useLibraryAgentCard({
+    agent,
+    onFavoriteAdd: triggerFavoriteAnimation,
+  });
 
   return (
     <div
-      data-testid="library-agent-card"
-      data-agent-id={id}
-      className="group relative inline-flex h-[10.625rem] w-full max-w-[25rem] flex-col items-start justify-start gap-2.5 rounded-medium border border-zinc-100 bg-white transition-all duration-300 hover:shadow-md"
+      draggable={draggable}
+      onDragStart={handleDragStart}
+      className="cursor-grab active:cursor-grabbing"
     >
-      <NextLink href={`/library/agents/${id}`} className="flex-shrink-0">
-        <div className="relative flex items-center gap-2 px-4 pt-3">
-          <Avatar className="h-4 w-4 rounded-full">
-            <AvatarImage
-              src={
-                isFromMarketplace
-                  ? creator_image_url || "/avatar-placeholder.png"
-                  : profile?.avatar_url || "/avatar-placeholder.png"
-              }
-              alt={`${name} creator avatar`}
-            />
-            <AvatarFallback size={48}>{name.charAt(0)}</AvatarFallback>
-          </Avatar>
-          <Text
-            variant="small-medium"
-            className="uppercase tracking-wide text-zinc-400"
-          >
-            {isFromMarketplace ? "FROM MARKETPLACE" : "Built by you"}
-          </Text>
-        </div>
-      </NextLink>
-      <FavoriteButton
-        isFavorite={isFavorite}
-        onClick={handleToggleFavorite}
-        className="absolute right-10 top-0"
-      />
-      <AgentCardMenu agent={agent} />
+      <motion.div
+        layoutId={`agent-card-${id}`}
+        data-testid="library-agent-card"
+        data-agent-id={id}
+        className="group relative inline-flex h-[10.625rem] w-full max-w-[25rem] flex-col items-start justify-start gap-2.5 rounded-medium border border-zinc-100 bg-white hover:shadow-md"
+        transition={{
+          type: "spring",
+          damping: 25,
+          stiffness: 300,
+        }}
+        style={{ willChange: "transform" }}
+      >
+        <NextLink href={`/library/agents/${id}`} className="flex-shrink-0">
+          <div className="relative flex items-center gap-2 px-4 pt-3">
+            <Avatar className="h-4 w-4 rounded-full">
+              <AvatarImage
+                src={
+                  isFromMarketplace
+                    ? creator_image_url || "/avatar-placeholder.png"
+                    : profile?.avatar_url || "/avatar-placeholder.png"
+                }
+                alt={`${name} creator avatar`}
+              />
+              <AvatarFallback size={48}>{name.charAt(0)}</AvatarFallback>
+            </Avatar>
+            <Text
+              variant="small-medium"
+              className="uppercase tracking-wide text-zinc-400"
+            >
+              {isFromMarketplace ? "FROM MARKETPLACE" : "Built by you"}
+            </Text>
+          </div>
+        </NextLink>
+        <FavoriteButton
+          isFavorite={isFavorite}
+          onClick={handleToggleFavorite}
+          className="absolute right-10 top-0"
+        />
+        <AgentCardMenu agent={agent} />
 
-      <div className="flex w-full flex-1 flex-col px-4 pb-2">
-        <Link
-          href={`/library/agents/${id}`}
-          className="flex w-full items-start justify-between gap-2 no-underline hover:no-underline"
-        >
-          <Text
-            variant="h5"
-            data-testid="library-agent-card-name"
-            className="line-clamp-3 hyphens-auto break-words no-underline hover:no-underline"
-          >
-            {name}
-          </Text>
-
-          {!image_url ? (
-            <div
-              className={`h-[3.64rem] w-[6.70rem] flex-shrink-0 rounded-small ${
-                [
-                  "bg-gradient-to-r from-green-200 to-blue-200",
-                  "bg-gradient-to-r from-pink-200 to-purple-200",
-                  "bg-gradient-to-r from-yellow-200 to-orange-200",
-                  "bg-gradient-to-r from-blue-200 to-cyan-200",
-                  "bg-gradient-to-r from-indigo-200 to-purple-200",
-                ][parseInt(id.slice(0, 8), 16) % 5]
-              }`}
-              style={{
-                backgroundSize: "200% 200%",
-                animation: "gradient 15s ease infinite",
-              }}
-            />
-          ) : (
-            <Image
-              src={image_url}
-              alt={`${name} preview image`}
-              width={107}
-              height={58}
-              className="flex-shrink-0 rounded-small object-cover"
-            />
-          )}
-        </Link>
-
-        <div className="mt-auto flex w-full justify-start gap-6 border-t border-zinc-100 pb-1 pt-3">
+        <div className="flex w-full flex-1 flex-col px-4 pb-2">
           <Link
             href={`/library/agents/${id}`}
-            data-testid="library-agent-card-see-runs-link"
-            className="flex items-center gap-1 text-[13px]"
+            className="flex w-full items-start justify-between gap-2 no-underline hover:no-underline focus:ring-0"
           >
-            See runs <CaretCircleRightIcon size={20} />
+            <Text
+              variant="h5"
+              data-testid="library-agent-card-name"
+              className="line-clamp-3 hyphens-auto break-words no-underline hover:no-underline"
+            >
+              {name}
+            </Text>
+
+            {!image_url ? (
+              <div
+                className={`h-[3.64rem] w-[6.70rem] flex-shrink-0 rounded-small ${
+                  [
+                    "bg-gradient-to-r from-green-200 to-blue-200",
+                    "bg-gradient-to-r from-pink-200 to-purple-200",
+                    "bg-gradient-to-r from-yellow-200 to-orange-200",
+                    "bg-gradient-to-r from-blue-200 to-cyan-200",
+                    "bg-gradient-to-r from-indigo-200 to-purple-200",
+                  ][parseInt(id.slice(0, 8), 16) % 5]
+                }`}
+                style={{
+                  backgroundSize: "200% 200%",
+                  animation: "gradient 15s ease infinite",
+                }}
+              />
+            ) : (
+              <Image
+                src={image_url}
+                alt={`${name} preview image`}
+                width={107}
+                height={58}
+                className="flex-shrink-0 rounded-small object-cover"
+              />
+            )}
           </Link>
 
-          {can_access_graph && (
+          <div className="mt-auto flex w-full justify-start gap-6 border-t border-zinc-100 pb-1 pt-3">
             <Link
-              href={`/build?flowID=${graph_id}`}
-              data-testid="library-agent-card-open-in-builder-link"
+              href={`/library/agents/${id}`}
+              data-testid="library-agent-card-see-runs-link"
               className="flex items-center gap-1 text-[13px]"
-              isExternal
             >
-              Open in builder <CaretCircleRightIcon size={20} />
+              See runs <CaretCircleRightIcon size={20} />
             </Link>
-          )}
+
+            {can_access_graph && (
+              <Link
+                href={`/build?flowID=${graph_id}`}
+                data-testid="library-agent-card-open-in-builder-link"
+                className="flex items-center gap-1 text-[13px]"
+                isExternal
+              >
+                Open in builder <CaretCircleRightIcon size={20} />
+              </Link>
+            )}
+          </div>
         </div>
-      </div>
+      </motion.div>
     </div>
   );
 }

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryAgentCard/components/AgentCardMenu.tsx

@@ -5,6 +5,10 @@ import {
   useDeleteV2DeleteLibraryAgent,
   usePostV2ForkLibraryAgent,
 } from "@/app/api/__generated__/endpoints/library/library";
+import {
+  usePostV2BulkMoveAgents,
+  getGetV2ListLibraryFoldersQueryKey,
+} from "@/app/api/__generated__/endpoints/folders/folders";
 import { LibraryAgent } from "@/app/api/__generated__/models/libraryAgent";
 import { Button } from "@/components/atoms/Button/Button";
 import { Text } from "@/components/atoms/Text/Text";
@@ -22,6 +26,7 @@ import { useQueryClient } from "@tanstack/react-query";
 import Link from "next/link";
 import { useRouter } from "next/navigation";
 import { useState } from "react";
+import { MoveToFolderDialog } from "../../MoveToFolderDialog/MoveToFolderDialog";
 
 interface AgentCardMenuProps {
   agent: LibraryAgent;
@@ -32,11 +37,25 @@ export function AgentCardMenu({ agent }: AgentCardMenuProps) {
   const queryClient = useQueryClient();
   const router = useRouter();
   const [showDeleteDialog, setShowDeleteDialog] = useState(false);
+  const [showMoveDialog, setShowMoveDialog] = useState(false);
   const [isDeletingAgent, setIsDeletingAgent] = useState(false);
   const [isDuplicatingAgent, setIsDuplicatingAgent] = useState(false);
+  const [isRemovingFromFolder, setIsRemovingFromFolder] = useState(false);
 
   const { mutateAsync: deleteAgent } = useDeleteV2DeleteLibraryAgent();
   const { mutateAsync: forkAgent } = usePostV2ForkLibraryAgent();
+  const { mutateAsync: bulkMoveAgents } = usePostV2BulkMoveAgents({
+    mutation: {
+      onSuccess: () => {
+        queryClient.invalidateQueries({
+          queryKey: getGetV2ListLibraryAgentsQueryKey(),
+        });
+        queryClient.invalidateQueries({
+          queryKey: getGetV2ListLibraryFoldersQueryKey(),
+        });
+      },
+    },
+  });
 
   async function handleDuplicateAgent() {
     if (!agent.id) return;
@@ -70,6 +89,37 @@ export function AgentCardMenu({ agent }: AgentCardMenuProps) {
     }
   }
 
+  async function handleRemoveFromFolder() {
+    if (!agent.id) return;
+
+    setIsRemovingFromFolder(true);
+
+    try {
+      await bulkMoveAgents({
+        data: {
+          agent_ids: [agent.id],
+          folder_id: undefined,
+        },
+      });
+
+      toast({
+        title: "Removed from folder",
+        description: "Agent has been moved back to your library.",
+      });
+    } catch (error: unknown) {
+      toast({
+        title: "Failed to remove from folder",
+        description:
+          error instanceof Error
+            ? error.message
+            : "An unexpected error occurred.",
+        variant: "destructive",
+      });
+    } finally {
+      setIsRemovingFromFolder(false);
+    }
+  }
+
   async function handleDeleteAgent() {
     if (!agent.id) return;
 
@@ -138,6 +188,31 @@ export function AgentCardMenu({ agent }: AgentCardMenuProps) {
             Duplicate agent
           </DropdownMenuItem>
           <DropdownMenuSeparator />
+          <DropdownMenuItem
+            onClick={(e) => {
+              e.stopPropagation();
+              setShowMoveDialog(true);
+            }}
+            className="flex items-center gap-2"
+          >
+            Move to folder
+          </DropdownMenuItem>
+          {agent.folder_id && (
+            <>
+              <DropdownMenuSeparator />
+              <DropdownMenuItem
+                onClick={(e) => {
+                  e.stopPropagation();
+                  handleRemoveFromFolder();
+                }}
+                disabled={isRemovingFromFolder}
+                className="flex items-center gap-2"
+              >
+                Remove from folder
+              </DropdownMenuItem>
+            </>
+          )}
+          <DropdownMenuSeparator />
           <DropdownMenuItem
             onClick={(e) => {
               e.stopPropagation();
@@ -183,6 +258,14 @@ export function AgentCardMenu({ agent }: AgentCardMenuProps) {
           </div>
         </Dialog.Content>
       </Dialog>
+
+      <MoveToFolderDialog
+        agentId={agent.id}
+        agentName={agent.name}
+        currentFolderId={agent.folder_id}
+        isOpen={showMoveDialog}
+        setIsOpen={setShowMoveDialog}
+      />
     </>
   );
 }

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryAgentCard/components/FavoriteButton.tsx

@@ -3,10 +3,15 @@
 import { cn } from "@/lib/utils";
 import { HeartIcon } from "@phosphor-icons/react";
 import type { MouseEvent } from "react";
+import { useRef } from "react";
+import { motion, AnimatePresence } from "framer-motion";
 
 interface FavoriteButtonProps {
   isFavorite: boolean;
-  onClick: (e: MouseEvent<HTMLButtonElement>) => void;
+  onClick: (
+    e: MouseEvent<HTMLButtonElement>,
+    position: { x: number; y: number },
+  ) => void;
   className?: string;
 }
 
@@ -15,25 +20,49 @@ export function FavoriteButton({
   onClick,
   className,
 }: FavoriteButtonProps) {
+  const buttonRef = useRef<HTMLButtonElement>(null);
+
+  function handleClick(e: MouseEvent<HTMLButtonElement>) {
+    const rect = buttonRef.current?.getBoundingClientRect();
+    const position = rect
+      ? {
+          x: rect.left + rect.width / 2 - 12,
+          y: rect.top + rect.height / 2 - 12,
+        }
+      : { x: 0, y: 0 };
+    onClick(e, position);
+  }
+
   return (
     <button
-      onClick={onClick}
+      ref={buttonRef}
+      onClick={handleClick}
       className={cn(
         "rounded-full p-2 transition-all duration-200",
-        "hover:scale-110",
+        "hover:scale-110 active:scale-95",
         !isFavorite && "opacity-0 group-hover:opacity-100",
         className,
       )}
       aria-label={isFavorite ? "Remove from favorites" : "Add to favorites"}
     >
-      <HeartIcon
-        size={20}
-        weight={isFavorite ? "fill" : "regular"}
-        className={cn(
-          "transition-colors duration-200",
-          isFavorite ? "text-red-500" : "text-gray-600 hover:text-red-500",
-        )}
-      />
+      <AnimatePresence mode="wait" initial={false}>
+        <motion.div
+          key={isFavorite ? "filled" : "empty"}
+          initial={{ scale: 0.5, opacity: 0 }}
+          animate={{ scale: 1, opacity: 1 }}
+          exit={{ scale: 0.5, opacity: 0 }}
+          transition={{ type: "spring", damping: 15, stiffness: 300 }}
+        >
+          <HeartIcon
+            size={20}
+            weight={isFavorite ? "fill" : "regular"}
+            className={cn(
+              "transition-colors duration-200",
+              isFavorite ? "text-red-500" : "text-gray-600 hover:text-red-500",
+            )}
+          />
+        </motion.div>
+      </AnimatePresence>
     </button>
   );
 }

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryAgentCard/useLibraryAgentCard.ts

@@ -14,11 +14,11 @@ import { updateFavoriteInQueries } from "./helpers";
 
 interface Props {
   agent: LibraryAgent;
+  onFavoriteAdd?: (position: { x: number; y: number }) => void;
 }
 
-export function useLibraryAgentCard({ agent }: Props) {
-  const { id, name, is_favorite, creator_image_url, marketplace_listing } =
-    agent;
+export function useLibraryAgentCard({ agent, onFavoriteAdd }: Props) {
+  const { id, is_favorite, creator_image_url, marketplace_listing } = agent;
 
   const isFromMarketplace = Boolean(marketplace_listing);
   const [isFavorite, setIsFavorite] = useState(is_favorite);
@@ -49,26 +49,31 @@ export function useLibraryAgentCard({ agent }: Props) {
     });
   }
 
-  async function handleToggleFavorite(e: React.MouseEvent) {
+  async function handleToggleFavorite(
+    e: React.MouseEvent,
+    position: { x: number; y: number },
+  ) {
     e.preventDefault();
     e.stopPropagation();
 
     const newIsFavorite = !isFavorite;
 
+    // Optimistic update - update UI immediately
     setIsFavorite(newIsFavorite);
     updateQueryData(newIsFavorite);
 
+    // Trigger animation immediately for adding to favorites
+    if (newIsFavorite && onFavoriteAdd) {
+      onFavoriteAdd(position);
+    }
+
     try {
       await updateLibraryAgent({
         libraryAgentId: id,
         data: { is_favorite: newIsFavorite },
       });
-
-      toast({
-        title: newIsFavorite ? "Added to favorites" : "Removed from favorites",
-        description: `${name} has been ${newIsFavorite ? "added to" : "removed from"} your favorites.`,
-      });
     } catch {
+      // Revert on failure
       setIsFavorite(!newIsFavorite);
       updateQueryData(!newIsFavorite);
 

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryAgentList/LibraryAgentList.tsx

@@ -1,30 +1,124 @@
 "use client";
+
 import { LibraryAgentSort } from "@/app/api/__generated__/models/libraryAgentSort";
 import { LoadingSpinner } from "@/components/atoms/LoadingSpinner/LoadingSpinner";
 import { InfiniteScroll } from "@/components/contextual/InfiniteScroll/InfiniteScroll";
 import { LibraryActionSubHeader } from "../LibraryActionSubHeader/LibraryActionSubHeader";
 import { LibraryAgentCard } from "../LibraryAgentCard/LibraryAgentCard";
+import { LibraryFolder } from "../LibraryFolder/LibraryFolder";
+import { LibrarySubSection } from "../LibrarySubSection/LibrarySubSection";
+import { Button } from "@/components/atoms/Button/Button";
+import { ArrowLeftIcon, HeartIcon } from "@phosphor-icons/react";
+import { Text } from "@/components/atoms/Text/Text";
+import { Tab } from "../LibraryTabs/LibraryTabs";
+import {
+  AnimatePresence,
+  LayoutGroup,
+  motion,
+  useReducedMotion,
+} from "framer-motion";
+import { LibraryFolderEditDialog } from "../LibraryFolderEditDialog/LibraryFolderEditDialog";
+import { LibraryFolderDeleteDialog } from "../LibraryFolderDeleteDialog/LibraryFolderDeleteDialog";
 import { useLibraryAgentList } from "./useLibraryAgentList";
 
+// cancels the current spring and starts a new one from current state.
+const containerVariants = {
+  hidden: {},
+  show: {},
+  exit: {
+    opacity: 0,
+    filter: "blur(4px)",
+    transition: { duration: 0.12 },
+  },
+};
+
+// Reduced motion fallback
+const reducedContainerVariants = {
+  hidden: {},
+  show: {},
+  exit: {
+    opacity: 0,
+    transition: { duration: 0.12 },
+  },
+};
+
+const itemInitial = {
+  opacity: 0,
+  filter: "blur(4px)",
+};
+
+const itemAnimate = {
+  opacity: 1,
+  filter: "blur(0px)",
+};
+
+const itemTransition = {
+  type: "spring" as const,
+  stiffness: 300,
+  damping: 25,
+  opacity: { duration: 0.2 },
+  filter: { duration: 0.15 },
+};
+
+const reducedItemInitial = { opacity: 0 };
+const reducedItemAnimate = { opacity: 1 };
+const reducedItemTransition = { duration: 0.15 };
+
 interface Props {
   searchTerm: string;
   librarySort: LibraryAgentSort;
   setLibrarySort: (value: LibraryAgentSort) => void;
+  selectedFolderId: string | null;
+  onFolderSelect: (folderId: string | null) => void;
+  tabs: Tab[];
+  activeTab: string;
+  onTabChange: (tabId: string) => void;
 }
 
 export function LibraryAgentList({
   searchTerm,
   librarySort,
   setLibrarySort,
+  selectedFolderId,
+  onFolderSelect,
+  tabs,
+  activeTab,
+  onTabChange,
 }: Props) {
+  const shouldReduceMotion = useReducedMotion();
+  const activeContainerVariants = shouldReduceMotion
+    ? reducedContainerVariants
+    : containerVariants;
+  const activeInitial = shouldReduceMotion ? reducedItemInitial : itemInitial;
+  const activeAnimate = shouldReduceMotion ? reducedItemAnimate : itemAnimate;
+  const activeTransition = shouldReduceMotion
+    ? reducedItemTransition
+    : itemTransition;
+
   const {
+    isFavoritesTab,
     agentLoading,
     agentCount,
-    allAgents: agents,
+    agents,
     hasNextPage,
     isFetchingNextPage,
     fetchNextPage,
-  } = useLibraryAgentList({ searchTerm, librarySort });
+    foldersData,
+    currentFolder,
+    showFolders,
+    editingFolder,
+    setEditingFolder,
+    deletingFolder,
+    setDeletingFolder,
+    handleAgentDrop,
+    handleFolderDeleted,
+  } = useLibraryAgentList({
+    searchTerm,
+    librarySort,
+    selectedFolderId,
+    onFolderSelect,
+    activeTab,
+  });
 
   return (
     <>
@@ -32,11 +126,42 @@ export function LibraryAgentList({
         agentCount={agentCount}
         setLibrarySort={setLibrarySort}
       />
-      <div className="px-2">
+      {!selectedFolderId && (
+        <LibrarySubSection
+          tabs={tabs}
+          activeTab={activeTab}
+          onTabChange={onTabChange}
+        />
+      )}
+
+      <div>
+        {selectedFolderId && (
+          <div className="mb-4 flex items-center gap-3">
+            <Button
+              variant="ghost"
+              size="small"
+              onClick={() => onFolderSelect(null)}
+              className="gap-2"
+            >
+              <ArrowLeftIcon className="h-4 w-4" />
+              Back to Library
+            </Button>
+            {currentFolder && (
+              <Text variant="h4" className="text-zinc-700">
+                {currentFolder.icon} {currentFolder.name}
+              </Text>
+            )}
+          </div>
+        )}
         {agentLoading ? (
           <div className="flex h-[200px] items-center justify-center">
             <LoadingSpinner size="large" />
           </div>
+        ) : isFavoritesTab && agents.length === 0 ? (
+          <div className="flex h-[200px] flex-col items-center justify-center gap-2 text-zinc-500">
+            <HeartIcon className="h-10 w-10" />
+            <Text variant="body">No favorite agents yet</Text>
+          </div>
         ) : (
           <InfiniteScroll
             isFetchingNextPage={isFetchingNextPage}
@@ -44,14 +169,85 @@ export function LibraryAgentList({
             hasNextPage={hasNextPage}
             loader={<LoadingSpinner size="medium" />}
           >
-            <div className="grid grid-cols-1 gap-6 sm:grid-cols-2 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
-              {agents.map((agent) => (
-                <LibraryAgentCard key={agent.id} agent={agent} />
-              ))}
-            </div>
+            <LayoutGroup>
+              <AnimatePresence mode="popLayout">
+                <motion.div
+                  key={`${activeTab}-${selectedFolderId || "all"}`}
+                  className="grid grid-cols-1 gap-6 sm:grid-cols-2 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4"
+                  variants={activeContainerVariants}
+                  initial="hidden"
+                  animate="show"
+                  exit="exit"
+                >
+                  {showFolders &&
+                    foldersData?.folders.map((folder, i) => (
+                      <motion.div
+                        key={folder.id}
+                        initial={activeInitial}
+                        animate={activeAnimate}
+                        transition={{
+                          ...activeTransition,
+                          delay: i * 0.04,
+                        }}
+                      >
+                        <LibraryFolder
+                          id={folder.id}
+                          name={folder.name}
+                          agentCount={folder.agent_count ?? 0}
+                          color={folder.color ?? undefined}
+                          icon={folder.icon ?? "📁"}
+                          onAgentDrop={handleAgentDrop}
+                          onClick={() => onFolderSelect(folder.id)}
+                          onEdit={() => setEditingFolder(folder)}
+                          onDelete={() => setDeletingFolder(folder)}
+                        />
+                      </motion.div>
+                    ))}
+                  {agents.map((agent, i) => (
+                    <motion.div
+                      key={agent.id}
+                      initial={activeInitial}
+                      animate={activeAnimate}
+                      transition={{
+                        ...activeTransition,
+                        delay:
+                          ((showFolders
+                            ? (foldersData?.folders.length ?? 0)
+                            : 0) +
+                            i) *
+                          0.04,
+                      }}
+                    >
+                      <LibraryAgentCard agent={agent} />
+                    </motion.div>
+                  ))}
+                </motion.div>
+              </AnimatePresence>
+            </LayoutGroup>
           </InfiniteScroll>
         )}
       </div>
+
+      {editingFolder && (
+        <LibraryFolderEditDialog
+          folder={editingFolder}
+          isOpen={!!editingFolder}
+          setIsOpen={(open) => {
+            if (!open) setEditingFolder(null);
+          }}
+        />
+      )}
+
+      {deletingFolder && (
+        <LibraryFolderDeleteDialog
+          folder={deletingFolder}
+          isOpen={!!deletingFolder}
+          setIsOpen={(open) => {
+            if (!open) setDeletingFolder(null);
+          }}
+          onDeleted={handleFolderDeleted}
+        />
+      )}
     </>
   );
 }

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryAgentList/useLibraryAgentList.ts

@@ -1,36 +1,69 @@
 "use client";
 
 import { useGetV2ListLibraryAgentsInfinite } from "@/app/api/__generated__/endpoints/library/library";
+import { getGetV2ListLibraryAgentsQueryKey } from "@/app/api/__generated__/endpoints/library/library";
+import {
+  useGetV2ListLibraryFolders,
+  usePostV2BulkMoveAgents,
+  getGetV2ListLibraryFoldersQueryKey,
+} from "@/app/api/__generated__/endpoints/folders/folders";
+import type { getV2ListLibraryFoldersResponseSuccess } from "@/app/api/__generated__/endpoints/folders/folders";
+import type { LibraryFolder } from "@/app/api/__generated__/models/libraryFolder";
 import { LibraryAgentSort } from "@/app/api/__generated__/models/libraryAgentSort";
 import {
+  okData,
   getPaginatedTotalCount,
   getPaginationNextPageNumber,
   unpaginate,
 } from "@/app/api/helpers";
+import { useToast } from "@/components/molecules/Toast/use-toast";
+import { useFavoriteAgents } from "../../hooks/useFavoriteAgents";
 import { getQueryClient } from "@/lib/react-query/queryClient";
-import { useEffect, useRef } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { useEffect, useRef, useState } from "react";
 
 interface Props {
   searchTerm: string;
   librarySort: LibraryAgentSort;
+  selectedFolderId: string | null;
+  onFolderSelect: (folderId: string | null) => void;
+  activeTab: string;
 }
 
-export function useLibraryAgentList({ searchTerm, librarySort }: Props) {
-  const queryClient = getQueryClient();
+export function useLibraryAgentList({
+  searchTerm,
+  librarySort,
+  selectedFolderId,
+  onFolderSelect,
+  activeTab,
+}: Props) {
+  const isFavoritesTab = activeTab === "favorites";
+  const { toast } = useToast();
+  const stableQueryClient = getQueryClient();
+  const queryClient = useQueryClient();
   const prevSortRef = useRef<LibraryAgentSort | null>(null);
 
+  const [editingFolder, setEditingFolder] = useState<LibraryFolder | null>(
+    null,
+  );
+  const [deletingFolder, setDeletingFolder] = useState<LibraryFolder | null>(
+    null,
+  );
+
   const {
     data: agentsQueryData,
     fetchNextPage,
     hasNextPage,
     isFetchingNextPage,
-    isLoading: agentLoading,
+    isLoading: allAgentsLoading,
   } = useGetV2ListLibraryAgentsInfinite(
     {
       page: 1,
       page_size: 20,
       search_term: searchTerm || undefined,
       sort_by: librarySort,
+      folder_id: selectedFolderId ?? undefined,
+      include_root_only: selectedFolderId === null ? true : undefined,
     },
     {
       query: {
@@ -39,28 +72,147 @@ export function useLibraryAgentList({ searchTerm, librarySort }: Props) {
     },
   );
 
-  // Reset queries when sort changes to ensure fresh data with correct sorting
   useEffect(() => {
     if (prevSortRef.current !== null && prevSortRef.current !== librarySort) {
-      // Reset all library agent queries to ensure fresh fetch with new sort
-      queryClient.resetQueries({
+      stableQueryClient.resetQueries({
         queryKey: ["/api/library/agents"],
       });
     }
     prevSortRef.current = librarySort;
-  }, [librarySort, queryClient]);
+  }, [librarySort, stableQueryClient]);
 
-  const allAgents = agentsQueryData
+  const allAgentsList = agentsQueryData
     ? unpaginate(agentsQueryData, "agents")
     : [];
-  const agentCount = getPaginatedTotalCount(agentsQueryData);
+  const allAgentsCount = getPaginatedTotalCount(agentsQueryData);
+
+  const favoriteAgentsData = useFavoriteAgents({ searchTerm });
+
+  const {
+    agentLoading,
+    agentCount,
+    allAgents: agents,
+    hasNextPage: agentsHasNextPage,
+    isFetchingNextPage: agentsIsFetchingNextPage,
+    fetchNextPage: agentsFetchNextPage,
+  } = isFavoritesTab
+    ? favoriteAgentsData
+    : {
+        agentLoading: allAgentsLoading,
+        agentCount: allAgentsCount,
+        allAgents: allAgentsList,
+        hasNextPage: hasNextPage,
+        isFetchingNextPage: isFetchingNextPage,
+        fetchNextPage: fetchNextPage,
+      };
+
+  const { data: rawFoldersData } = useGetV2ListLibraryFolders(undefined, {
+    query: { select: okData },
+  });
+
+  const foldersData = searchTerm ? undefined : rawFoldersData;
+
+  const { mutate: moveAgentToFolder } = usePostV2BulkMoveAgents({
+    mutation: {
+      onMutate: async ({ data }) => {
+        await queryClient.cancelQueries({
+          queryKey: getGetV2ListLibraryFoldersQueryKey(),
+        });
+        await queryClient.cancelQueries({
+          queryKey: getGetV2ListLibraryAgentsQueryKey(),
+        });
+
+        const previousFolders =
+          queryClient.getQueriesData<getV2ListLibraryFoldersResponseSuccess>({
+            queryKey: getGetV2ListLibraryFoldersQueryKey(),
+          });
+
+        if (data.folder_id) {
+          queryClient.setQueriesData<getV2ListLibraryFoldersResponseSuccess>(
+            { queryKey: getGetV2ListLibraryFoldersQueryKey() },
+            (old) => {
+              if (!old?.data?.folders) return old;
+              return {
+                ...old,
+                data: {
+                  ...old.data,
+                  folders: old.data.folders.map((f) =>
+                    f.id === data.folder_id
+                      ? {
+                          ...f,
+                          agent_count:
+                            (f.agent_count ?? 0) + data.agent_ids.length,
+                        }
+                      : f,
+                  ),
+                },
+              };
+            },
+          );
+        }
+
+        return { previousFolders };
+      },
+      onError: (_error, _variables, context) => {
+        if (context?.previousFolders) {
+          for (const [queryKey, data] of context.previousFolders) {
+            queryClient.setQueryData(queryKey, data);
+          }
+        }
+        toast({
+          title: "Error",
+          description: "Failed to move agent. Please try again.",
+          variant: "destructive",
+        });
+      },
+      onSettled: () => {
+        queryClient.invalidateQueries({
+          queryKey: getGetV2ListLibraryFoldersQueryKey(),
+        });
+        queryClient.invalidateQueries({
+          queryKey: getGetV2ListLibraryAgentsQueryKey(),
+        });
+      },
+    },
+  });
+
+  function handleAgentDrop(agentId: string, folderId: string) {
+    moveAgentToFolder({
+      data: {
+        agent_ids: [agentId],
+        folder_id: folderId,
+      },
+    });
+  }
+
+  const currentFolder = selectedFolderId
+    ? foldersData?.folders.find((f) => f.id === selectedFolderId)
+    : null;
+
+  const showFolders = !isFavoritesTab && !selectedFolderId;
+
+  function handleFolderDeleted() {
+    if (selectedFolderId === deletingFolder?.id) {
+      onFolderSelect(null);
+    }
+  }
 
   return {
-    allAgents,
+    isFavoritesTab,
     agentLoading,
-    hasNextPage,
     agentCount,
-    isFetchingNextPage,
-    fetchNextPage,
+    agents,
+    hasNextPage: agentsHasNextPage,
+    isFetchingNextPage: agentsIsFetchingNextPage,
+    fetchNextPage: agentsFetchNextPage,
+    foldersData,
+    currentFolder,
+    showFolders,
+    editingFolder,
+    setEditingFolder,
+    deletingFolder,
+    setDeletingFolder,
+    handleAgentDrop,
+    handleFolderDeleted,
   };
 }

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryFolder/FolderIcon.tsx

@@ -0,0 +1,255 @@
+import { motion } from "framer-motion";
+import { Text } from "@/components/atoms/Text/Text";
+
+type FolderSize = "xs" | "sm" | "md" | "lg" | "xl";
+export type FolderColorName = "blue" | "purple" | "emerald" | "orange" | "pink";
+
+export type FolderColor = FolderColorName | (string & {});
+
+const hexToColorName: Record<string, FolderColorName> = {
+  "#3B82F6": "blue",
+  "#3b82f6": "blue",
+  "#A855F7": "purple",
+  "#a855f7": "purple",
+  "#10B981": "emerald",
+  "#10b981": "emerald",
+  "#F97316": "orange",
+  "#f97316": "orange",
+  "#EC4899": "pink",
+  "#ec4899": "pink",
+};
+
+export function resolveColor(color: FolderColor | undefined): FolderColorName {
+  if (!color) return "blue";
+  if (color in hexToColorName) return hexToColorName[color];
+  if (color in colorMap) return color as FolderColorName;
+  return "blue";
+}
+
+interface Props {
+  className?: string;
+  size?: FolderSize | number;
+  color?: FolderColor;
+  icon?: string;
+  isOpen?: boolean;
+}
+
+const sizeMap: Record<FolderSize, number> = {
+  xs: 0.4,
+  sm: 0.75,
+  md: 1,
+  lg: 1.25,
+  xl: 1.5,
+};
+
+const colorMap: Record<
+  FolderColorName,
+  {
+    bg: string;
+    border: string;
+    borderLight: string;
+    fill: string;
+    stroke: string;
+  }
+> = {
+  blue: {
+    bg: "bg-blue-300",
+    border: "border-blue-300",
+    borderLight: "border-blue-200",
+    fill: "fill-blue-300",
+    stroke: "stroke-blue-400",
+  },
+  purple: {
+    bg: "bg-purple-200",
+    border: "border-purple-200",
+    borderLight: "border-purple-200",
+    fill: "fill-purple-200",
+    stroke: "stroke-purple-400",
+  },
+  emerald: {
+    bg: "bg-emerald-300",
+    border: "border-emerald-300",
+    borderLight: "border-emerald-200",
+    fill: "fill-emerald-300",
+    stroke: "stroke-emerald-400",
+  },
+  orange: {
+    bg: "bg-orange-200",
+    border: "border-orange-200",
+    borderLight: "border-orange-200",
+    fill: "fill-orange-200",
+    stroke: "stroke-orange-400",
+  },
+  pink: {
+    bg: "bg-pink-300",
+    border: "border-pink-300",
+    borderLight: "border-pink-200",
+    fill: "fill-pink-300",
+    stroke: "stroke-pink-400",
+  },
+};
+
+export const folderCardStyles: Record<
+  FolderColorName,
+  { bg: string; border: string; buttonBase: string; buttonHover: string }
+> = {
+  blue: {
+    bg: "bg-blue-50",
+    border: "border-blue-200",
+    buttonBase: "border-zinc-600 text-black",
+    buttonHover: "hover:bg-blue-200",
+  },
+  purple: {
+    bg: "bg-purple-50",
+    border: "border-purple-200",
+    buttonBase: "border-zinc-600 text-black ",
+    buttonHover: "hover:bg-purple-200",
+  },
+  emerald: {
+    bg: "bg-emerald-50",
+    border: "border-emerald-200",
+    buttonBase: "border-zinc-600 text-black",
+    buttonHover: "hover:bg-emerald-200",
+  },
+  orange: {
+    bg: "bg-orange-50",
+    border: "border-orange-200",
+    buttonBase: "border-zinc-600 text-black",
+    buttonHover: "hover:bg-orange-200",
+  },
+  pink: {
+    bg: "bg-pink-50",
+    border: "border-pink-200",
+    buttonBase: "border-zinc-600 text-black",
+    buttonHover: "hover:bg-pink-200",
+  },
+};
+
+export function FolderIcon({
+  className = "",
+  size = "xs",
+  color = "blue",
+  icon,
+  isOpen = false,
+}: Props) {
+  const scale = typeof size === "number" ? size : sizeMap[size];
+  const resolvedColor = resolveColor(color);
+  const colors = colorMap[resolvedColor];
+
+  return (
+    <div
+      className={`group relative cursor-pointer ${className}`}
+      style={{
+        width: 320 * scale,
+        height: 208 * scale,
+      }}
+    >
+      <div
+        className="h-52 w-80 origin-top-left"
+        style={{ transform: `scale(${scale})`, perspective: "500px" }}
+      >
+        <div
+          className={`folder-back relative mx-auto flex h-full w-[87.5%] justify-center overflow-visible rounded-3xl ${colors.bg} ${colors.border}`}
+        >
+          {[
+            {
+              initial: { rotate: -3, x: -38, y: 2 },
+              open: { rotate: -8, x: -70, y: -75 },
+              transition: {
+                type: "spring" as const,
+                bounce: 0.15,
+                stiffness: 160,
+                damping: 22,
+              },
+              className: "z-10",
+            },
+            {
+              initial: { rotate: 0, x: 0, y: 0 },
+              open: { rotate: 1, x: 2, y: -95 },
+              transition: {
+                type: "spring" as const,
+                duration: 0.55,
+                bounce: 0.12,
+                stiffness: 190,
+                damping: 24,
+              },
+              className: "z-20",
+            },
+            {
+              initial: { rotate: 3.5, x: 42, y: 1 },
+              open: { rotate: 9, x: 75, y: -80 },
+              transition: {
+                type: "spring" as const,
+                duration: 0.58,
+                bounce: 0.17,
+                stiffness: 170,
+                damping: 21,
+              },
+              className: "z-10",
+            },
+          ].map((page, i) => (
+            <motion.div
+              key={i}
+              initial={page.initial}
+              animate={isOpen ? page.open : page.initial}
+              transition={page.transition}
+              className={`absolute top-2 h-fit w-32 rounded-xl shadow-lg ${page.className}`}
+            >
+              <Page color={resolvedColor} />
+            </motion.div>
+          ))}
+        </div>
+
+        <motion.div
+          animate={{
+            rotateX: isOpen ? -15 : 0,
+          }}
+          transition={{ type: "spring", duration: 0.5, bounce: 0.25 }}
+          className="absolute inset-x-0 -bottom-px z-30 mx-auto flex h-44 w-[87.5%] origin-bottom items-end justify-center overflow-visible"
+          style={{ transformStyle: "preserve-3d" }}
+        >
+          <svg
+            className="h-auto w-full"
+            viewBox="0 0 173 109"
+            fill="none"
+            xmlns="http://www.w3.org/2000/svg"
+            preserveAspectRatio="none"
+          >
+            <path
+              className={`${colors.fill} ${colors.stroke}`}
+              d="M15.0423 0.500003C0.5 0.500009 0.5 14.2547 0.5 14.2547V92.5C0.5 101.337 7.66344 108.5 16.5 108.5H156.5C165.337 108.5 172.5 101.337 172.5 92.5V34.3302C172.5 25.4936 165.355 18.3302 156.519 18.3302H108.211C98.1341 18.3302 91.2921 5.57144 82.0156 1.63525C80.3338 0.921645 78.2634 0.500002 75.7187 0.500003H15.0423Z"
+            />
+          </svg>
+          <div className="absolute inset-0 flex items-center justify-center text-7xl">
+            {icon}
+          </div>
+        </motion.div>
+      </div>
+    </div>
+  );
+}
+
+interface PageProps {
+  color: FolderColorName;
+}
+
+function Page({ color = "blue" }: PageProps) {
+  const colors = colorMap[color];
+  return (
+    <div
+      className={`h-full w-full rounded-xl border bg-white p-4 ${colors.borderLight}`}
+    >
+      <div className="flex flex-col gap-2">
+        <Text variant="h5" className="text-black">
+          agent.json
+        </Text>
+        {Array.from({ length: 8 }).map((_, i) => (
+          <div key={i} className="flex gap-2">
+            <div className="h-1.5 flex-1 rounded-full bg-neutral-100" />
+            <div className="h-1.5 flex-1 rounded-full bg-neutral-100" />
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryFolder/LibraryFolder.tsx

@@ -0,0 +1,136 @@
+"use client";
+
+import { Text } from "@/components/atoms/Text/Text";
+import { Button } from "@/components/atoms/Button/Button";
+import {
+  FolderIcon,
+  FolderColor,
+  folderCardStyles,
+  resolveColor,
+} from "./FolderIcon";
+import { useState } from "react";
+import { PencilSimpleIcon, TrashIcon } from "@phosphor-icons/react";
+
+interface Props {
+  id: string;
+  name: string;
+  agentCount: number;
+  color?: FolderColor;
+  icon: string;
+  onEdit?: () => void;
+  onDelete?: () => void;
+  onAgentDrop?: (agentId: string, folderId: string) => void;
+  onClick?: () => void;
+}
+
+export function LibraryFolder({
+  id,
+  name,
+  agentCount,
+  color,
+  icon,
+  onEdit,
+  onDelete,
+  onAgentDrop,
+  onClick,
+}: Props) {
+  const [isHovered, setIsHovered] = useState(false);
+  const [isDragOver, setIsDragOver] = useState(false);
+  const resolvedColor = resolveColor(color);
+  const cardStyle = folderCardStyles[resolvedColor];
+
+  function handleDragOver(e: React.DragEvent<HTMLDivElement>) {
+    if (e.dataTransfer.types.includes("application/agent-id")) {
+      e.preventDefault();
+      e.dataTransfer.dropEffect = "move";
+      setIsDragOver(true);
+    }
+  }
+
+  function handleDragLeave() {
+    setIsDragOver(false);
+  }
+
+  function handleDrop(e: React.DragEvent<HTMLDivElement>) {
+    e.preventDefault();
+    setIsDragOver(false);
+    const agentId = e.dataTransfer.getData("application/agent-id");
+    if (agentId && onAgentDrop) {
+      onAgentDrop(agentId, id);
+    }
+  }
+
+  return (
+    <div
+      data-testid="library-folder"
+      data-folder-id={id}
+      className={`group relative inline-flex h-[10.625rem] w-full max-w-[25rem] cursor-pointer flex-col items-start justify-between gap-2.5 rounded-medium border p-4 transition-all duration-200 hover:shadow-md ${
+        isDragOver
+          ? "border-blue-400 bg-blue-50 ring-2 ring-blue-200"
+          : `${cardStyle.border} ${cardStyle.bg}`
+      }`}
+      onMouseEnter={() => setIsHovered(true)}
+      onMouseLeave={() => setIsHovered(false)}
+      onDragOver={handleDragOver}
+      onDragLeave={handleDragLeave}
+      onDrop={handleDrop}
+      onClick={onClick}
+    >
+      <div className="flex w-full items-start justify-between gap-4">
+        {/* Left side - Folder name and agent count */}
+        <div className="flex flex-1 flex-col gap-2">
+          <Text
+            variant="h5"
+            data-testid="library-folder-name"
+            className="line-clamp-2 hyphens-auto break-words"
+          >
+            {name}
+          </Text>
+          <Text
+            variant="small"
+            className="text-zinc-500"
+            data-testid="library-folder-agent-count"
+          >
+            {agentCount} {agentCount === 1 ? "agent" : "agents"}
+          </Text>
+        </div>
+
+        {/* Right side - Custom folder icon */}
+        <div className="flex-shrink-0">
+          <FolderIcon isOpen={isHovered} color={color} icon={icon} />
+        </div>
+      </div>
+
+      {/* Action buttons - visible on hover */}
+      <div
+        className="flex items-center justify-end gap-2"
+        data-testid="library-folder-actions"
+      >
+        <Button
+          variant="icon"
+          size="icon"
+          aria-label="Edit folder"
+          onClick={(e) => {
+            e.stopPropagation();
+            onEdit?.();
+          }}
+          className={`h-8 w-8 border p-2 ${cardStyle.buttonBase} ${cardStyle.buttonHover}`}
+        >
+          <PencilSimpleIcon className="h-4 w-4" />
+        </Button>
+        <Button
+          variant="icon"
+          size="icon"
+          aria-label="Delete folder"
+          onClick={(e) => {
+            e.stopPropagation();
+            onDelete?.();
+          }}
+          className={`h-8 w-8 border p-2 ${cardStyle.buttonBase} ${cardStyle.buttonHover}`}
+        >
+          <TrashIcon className="h-4 w-4" />
+        </Button>
+      </div>
+    </div>
+  );
+}

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryFolderCreationDialog/LibraryFolderCreationDialog.tsx

@@ -0,0 +1,229 @@
+"use client";
+import { Button } from "@/components/atoms/Button/Button";
+import { Input } from "@/components/atoms/Input/Input";
+import { Select } from "@/components/atoms/Select/Select";
+import { Text } from "@/components/atoms/Text/Text";
+import { Dialog } from "@/components/molecules/Dialog/Dialog";
+import {
+  Form,
+  FormControl,
+  FormField,
+  FormItem,
+  FormMessage,
+} from "@/components/molecules/Form/Form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { FolderSimpleIcon } from "@phosphor-icons/react";
+import { useState } from "react";
+import { useForm } from "react-hook-form";
+import { z } from "zod";
+import { EmojiPicker } from "@ferrucc-io/emoji-picker";
+import {
+  usePostV2CreateFolder,
+  getGetV2ListLibraryFoldersQueryKey,
+} from "@/app/api/__generated__/endpoints/folders/folders";
+import { useToast } from "@/components/molecules/Toast/use-toast";
+import { useQueryClient } from "@tanstack/react-query";
+
+const FOLDER_COLORS = [
+  { value: "#3B82F6", label: "Blue" },
+  { value: "#A855F7", label: "Purple" },
+  { value: "#10B981", label: "Green" },
+  { value: "#F97316", label: "Orange" },
+  { value: "#EC4899", label: "Pink" },
+];
+
+export const libraryFolderCreationFormSchema = z.object({
+  folderName: z.string().min(1, "Folder name is required"),
+  folderColor: z.string().min(1, "Folder color is required"),
+  folderIcon: z.string().min(1, "Folder icon is required"),
+});
+
+export default function LibraryFolderCreationDialog() {
+  const [isOpen, setIsOpen] = useState(false);
+  const queryClient = useQueryClient();
+  const { toast } = useToast();
+
+  const { mutate: createFolder, isPending } = usePostV2CreateFolder({
+    mutation: {
+      onSuccess: () => {
+        queryClient.invalidateQueries({
+          queryKey: getGetV2ListLibraryFoldersQueryKey(),
+        });
+        setIsOpen(false);
+        form.reset();
+        toast({
+          title: "Folder created",
+          description: "Your folder has been created successfully.",
+        });
+      },
+      onError: () => {
+        toast({
+          title: "Error",
+          description: "Failed to create folder. Please try again.",
+          variant: "destructive",
+        });
+      },
+    },
+  });
+
+  const form = useForm<z.infer<typeof libraryFolderCreationFormSchema>>({
+    resolver: zodResolver(libraryFolderCreationFormSchema),
+    defaultValues: {
+      folderName: "",
+      folderColor: "",
+      folderIcon: "",
+    },
+  });
+
+  function onSubmit(values: z.infer<typeof libraryFolderCreationFormSchema>) {
+    createFolder({
+      data: {
+        name: values.folderName.trim(),
+        color: values.folderColor,
+        icon: values.folderIcon,
+      },
+    });
+  }
+
+  return (
+    <Dialog
+      title="Create Folder"
+      styling={{ maxWidth: "30rem" }}
+      controlled={{
+        isOpen,
+        set: setIsOpen,
+      }}
+      onClose={() => {
+        setIsOpen(false);
+      }}
+    >
+      <Dialog.Trigger>
+        <Button
+          data-testid="upload-agent-button"
+          variant="secondary"
+          className="h-fit w-fit"
+          size="small"
+        >
+          <FolderSimpleIcon width={18} height={18} />
+          <span className="create-folder">Create folder</span>
+        </Button>
+      </Dialog.Trigger>
+      <Dialog.Content>
+        <Form
+          form={form}
+          onSubmit={(values) => onSubmit(values)}
+          className="flex flex-col justify-center gap-2 px-1"
+        >
+          <FormField
+            control={form.control}
+            name="folderName"
+            render={({ field }) => (
+              <FormItem>
+                <FormControl>
+                  <Input
+                    {...field}
+                    id={field.name}
+                    label="Folder name"
+                    placeholder="Enter folder name"
+                    className="!mb-0 w-full"
+                    wrapperClassName="!mb-0"
+                  />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+
+          <FormField
+            control={form.control}
+            name="folderColor"
+            render={({ field }) => (
+              <FormItem>
+                <FormControl>
+                  <Select
+                    id="folderColor"
+                    label="Folder color"
+                    placeholder="Select a color"
+                    value={field.value}
+                    onValueChange={field.onChange}
+                    options={FOLDER_COLORS.map((color) => ({
+                      value: color.value,
+                      label: color.label,
+                      icon: (
+                        <div
+                          className="h-4 w-4 rounded-full"
+                          style={{ backgroundColor: color.value }}
+                        />
+                      ),
+                    }))}
+                    wrapperClassName="!mb-0"
+                    renderItem={(option) => (
+                      <div className="flex items-center gap-2">
+                        {option.icon}
+                        <span>{option.label}</span>
+                      </div>
+                    )}
+                  />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+
+          <FormField
+            control={form.control}
+            name="folderIcon"
+            render={({ field }) => (
+              <FormItem>
+                <div className="flex flex-col gap-2">
+                  <Text variant="large-medium" as="span" className="text-black">
+                    Folder icon
+                  </Text>
+                  <div className="flex flex-col gap-3">
+                    <div className="flex items-center gap-3">
+                      <Text variant="small" className="text-zinc-500">
+                        Selected:
+                      </Text>
+                      <div className="flex h-10 w-10 items-center justify-center rounded-lg border border-zinc-200 bg-zinc-50 text-2xl">
+                        {form.watch("folderIcon") || (
+                          <span className="text-sm text-zinc-400">—</span>
+                        )}
+                      </div>
+                    </div>
+                    <div className="h-[295px] w-full overflow-hidden">
+                      <EmojiPicker
+                        onEmojiSelect={(emoji) => {
+                          field.onChange(emoji);
+                        }}
+                        emojiSize={32}
+                        className="w-full rounded-2xl px-2"
+                      >
+                        <EmojiPicker.Group>
+                          <EmojiPicker.List
+                            hideStickyHeader
+                            containerHeight={295}
+                          />
+                        </EmojiPicker.Group>
+                      </EmojiPicker>
+                    </div>
+                  </div>
+                  <FormMessage />
+                </div>
+              </FormItem>
+            )}
+          />
+
+          <Button
+            type="submit"
+            variant="primary"
+            className="mt-2 min-w-[18rem]"
+            disabled={!form.formState.isValid || isPending}
+            loading={isPending}
+          >
+            Create
+          </Button>
+        </Form>
+      </Dialog.Content>
+    </Dialog>
+  );
+}

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryFolderDeleteDialog/LibraryFolderDeleteDialog.tsx

@@ -0,0 +1,96 @@
+"use client";
+
+import { Button } from "@/components/atoms/Button/Button";
+import { Text } from "@/components/atoms/Text/Text";
+import { Dialog } from "@/components/molecules/Dialog/Dialog";
+import { useToast } from "@/components/molecules/Toast/use-toast";
+import {
+  useDeleteV2DeleteFolder,
+  getGetV2ListLibraryFoldersQueryKey,
+} from "@/app/api/__generated__/endpoints/folders/folders";
+import { getGetV2ListLibraryAgentsQueryKey } from "@/app/api/__generated__/endpoints/library/library";
+import { useQueryClient } from "@tanstack/react-query";
+import type { LibraryFolder } from "@/app/api/__generated__/models/libraryFolder";
+
+interface Props {
+  folder: LibraryFolder;
+  isOpen: boolean;
+  setIsOpen: (open: boolean) => void;
+  onDeleted?: () => void;
+}
+
+export function LibraryFolderDeleteDialog({
+  folder,
+  isOpen,
+  setIsOpen,
+  onDeleted,
+}: Props) {
+  const queryClient = useQueryClient();
+  const { toast } = useToast();
+
+  const { mutate: deleteFolder, isPending } = useDeleteV2DeleteFolder({
+    mutation: {
+      onSuccess: () => {
+        queryClient.invalidateQueries({
+          queryKey: getGetV2ListLibraryFoldersQueryKey(),
+        });
+        queryClient.invalidateQueries({
+          queryKey: getGetV2ListLibraryAgentsQueryKey(),
+        });
+        toast({
+          title: "Folder deleted",
+          description: `"${folder.name}" has been deleted.`,
+        });
+        setIsOpen(false);
+        onDeleted?.();
+      },
+      onError: () => {
+        toast({
+          title: "Error",
+          description: "Failed to delete folder. Please try again.",
+          variant: "destructive",
+        });
+      },
+    },
+  });
+
+  function handleDelete() {
+    deleteFolder({ folderId: folder.id });
+  }
+
+  return (
+    <Dialog
+      controlled={{
+        isOpen,
+        set: setIsOpen,
+      }}
+      styling={{ maxWidth: "32rem" }}
+      title="Delete folder"
+    >
+      <Dialog.Content>
+        <div>
+          <Text variant="large">
+            Are you sure you want to delete &ldquo;{folder.name}&rdquo;? Agents
+            inside this folder will be moved back to your library.
+          </Text>
+          <Dialog.Footer>
+            <Button
+              variant="secondary"
+              disabled={isPending}
+              onClick={() => setIsOpen(false)}
+            >
+              Cancel
+            </Button>
+            <Button
+              variant="destructive"
+              onClick={handleDelete}
+              loading={isPending}
+            >
+              Delete Folder
+            </Button>
+          </Dialog.Footer>
+        </div>
+      </Dialog.Content>
+    </Dialog>
+  );
+}

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryFolderEditDialog/LibraryFolderEditDialog.tsx

@@ -0,0 +1,287 @@
+"use client";
+
+import { Button } from "@/components/atoms/Button/Button";
+import { Input } from "@/components/atoms/Input/Input";
+import { Select } from "@/components/atoms/Select/Select";
+import { Text } from "@/components/atoms/Text/Text";
+import { Dialog } from "@/components/molecules/Dialog/Dialog";
+import {
+  Form,
+  FormControl,
+  FormField,
+  FormItem,
+  FormMessage,
+} from "@/components/molecules/Form/Form";
+import { useToast } from "@/components/molecules/Toast/use-toast";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { useEffect } from "react";
+import { useForm } from "react-hook-form";
+import { z } from "zod";
+import { EmojiPicker } from "@ferrucc-io/emoji-picker";
+import {
+  usePatchV2UpdateFolder,
+  getGetV2ListLibraryFoldersQueryKey,
+} from "@/app/api/__generated__/endpoints/folders/folders";
+import { useQueryClient } from "@tanstack/react-query";
+import type { LibraryFolder } from "@/app/api/__generated__/models/libraryFolder";
+import type { getV2ListLibraryFoldersResponseSuccess } from "@/app/api/__generated__/endpoints/folders/folders";
+import { ApiError } from "@/lib/autogpt-server-api/helpers";
+
+const FOLDER_COLORS = [
+  { value: "#3B82F6", label: "Blue" },
+  { value: "#A855F7", label: "Purple" },
+  { value: "#10B981", label: "Green" },
+  { value: "#F97316", label: "Orange" },
+  { value: "#EC4899", label: "Pink" },
+];
+
+const editFolderSchema = z.object({
+  folderName: z.string().min(1, "Folder name is required"),
+  folderColor: z.string().min(1, "Folder color is required"),
+  folderIcon: z.string().min(1, "Folder icon is required"),
+});
+
+interface Props {
+  folder: LibraryFolder;
+  isOpen: boolean;
+  setIsOpen: (open: boolean) => void;
+}
+
+export function LibraryFolderEditDialog({ folder, isOpen, setIsOpen }: Props) {
+  const queryClient = useQueryClient();
+  const { toast } = useToast();
+
+  const form = useForm<z.infer<typeof editFolderSchema>>({
+    resolver: zodResolver(editFolderSchema),
+    defaultValues: {
+      folderName: folder.name,
+      folderColor: folder.color ?? "",
+      folderIcon: folder.icon ?? "",
+    },
+  });
+
+  useEffect(() => {
+    if (isOpen) {
+      form.reset({
+        folderName: folder.name,
+        folderColor: folder.color ?? "",
+        folderIcon: folder.icon ?? "",
+      });
+    }
+  }, [isOpen, folder, form]);
+
+  const { mutate: updateFolder, isPending } = usePatchV2UpdateFolder({
+    mutation: {
+      onMutate: async ({ folderId, data }) => {
+        await queryClient.cancelQueries({
+          queryKey: getGetV2ListLibraryFoldersQueryKey(),
+        });
+
+        const previousData =
+          queryClient.getQueriesData<getV2ListLibraryFoldersResponseSuccess>({
+            queryKey: getGetV2ListLibraryFoldersQueryKey(),
+          });
+
+        queryClient.setQueriesData<getV2ListLibraryFoldersResponseSuccess>(
+          { queryKey: getGetV2ListLibraryFoldersQueryKey() },
+          (old) => {
+            if (!old?.data?.folders) return old;
+            return {
+              ...old,
+              data: {
+                ...old.data,
+                folders: old.data.folders.map((f) =>
+                  f.id === folderId
+                    ? {
+                        ...f,
+                        name: data.name ?? f.name,
+                        color: data.color ?? f.color,
+                        icon: data.icon ?? f.icon,
+                      }
+                    : f,
+                ),
+              },
+            };
+          },
+        );
+
+        return { previousData };
+      },
+      onError: (error: unknown, _variables, context) => {
+        if (context?.previousData) {
+          for (const [queryKey, data] of context.previousData) {
+            queryClient.setQueryData(queryKey, data);
+          }
+        }
+        if (error instanceof ApiError) {
+          const detail = (error.response as any)?.detail ?? "";
+          if (
+            typeof detail === "string" &&
+            detail.toLowerCase().includes("already exists")
+          ) {
+            form.setError("folderName", {
+              message: "A folder with this name already exists",
+            });
+            return;
+          }
+        }
+        toast({
+          title: "Error",
+          description: "Failed to update folder. Please try again.",
+          variant: "destructive",
+        });
+      },
+      onSuccess: () => {
+        setIsOpen(false);
+        toast({
+          title: "Folder updated",
+          description: "Your folder has been updated successfully.",
+        });
+      },
+      onSettled: () => {
+        queryClient.invalidateQueries({
+          queryKey: getGetV2ListLibraryFoldersQueryKey(),
+        });
+      },
+    },
+  });
+
+  function onSubmit(values: z.infer<typeof editFolderSchema>) {
+    updateFolder({
+      folderId: folder.id,
+      data: {
+        name: values.folderName.trim(),
+        color: values.folderColor,
+        icon: values.folderIcon,
+      },
+    });
+  }
+
+  return (
+    <Dialog
+      title="Edit Folder"
+      styling={{ maxWidth: "30rem" }}
+      controlled={{
+        isOpen,
+        set: setIsOpen,
+      }}
+    >
+      <Dialog.Content>
+        <Form
+          form={form}
+          onSubmit={(values) => onSubmit(values)}
+          className="flex flex-col justify-center gap-2 px-1"
+        >
+          <FormField
+            control={form.control}
+            name="folderName"
+            render={({ field }) => (
+              <FormItem>
+                <FormControl>
+                  <Input
+                    {...field}
+                    id={field.name}
+                    label="Folder name"
+                    placeholder="Enter folder name"
+                    className="w-full"
+                    wrapperClassName="!mb-0"
+                  />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+
+          <FormField
+            control={form.control}
+            name="folderColor"
+            render={({ field }) => (
+              <FormItem>
+                <FormControl>
+                  <Select
+                    id="folderColor"
+                    label="Folder color"
+                    placeholder="Select a color"
+                    value={field.value}
+                    onValueChange={field.onChange}
+                    wrapperClassName="!mb-0"
+                    options={FOLDER_COLORS.map((color) => ({
+                      value: color.value,
+                      label: color.label,
+                      icon: (
+                        <div
+                          className="h-4 w-4 rounded-full"
+                          style={{ backgroundColor: color.value }}
+                        />
+                      ),
+                    }))}
+                    renderItem={(option) => (
+                      <div className="flex items-center gap-2">
+                        {option.icon}
+                        <span>{option.label}</span>
+                      </div>
+                    )}
+                  />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+
+          <FormField
+            control={form.control}
+            name="folderIcon"
+            render={({ field }) => (
+              <FormItem>
+                <div className="flex flex-col gap-2">
+                  <Text variant="large-medium" as="span" className="text-black">
+                    Folder icon
+                  </Text>
+                  <div className="flex flex-col gap-3">
+                    <div className="flex items-center gap-3">
+                      <Text variant="small" className="text-zinc-500">
+                        Selected:
+                      </Text>
+                      <div className="flex h-10 w-10 items-center justify-center rounded-lg border border-zinc-200 bg-zinc-50 text-2xl">
+                        {form.watch("folderIcon") || (
+                          <span className="text-sm text-zinc-400">—</span>
+                        )}
+                      </div>
+                    </div>
+                    <div className="h-[295px] w-full overflow-hidden">
+                      <EmojiPicker
+                        onEmojiSelect={(emoji) => {
+                          field.onChange(emoji);
+                        }}
+                        emojiSize={32}
+                        className="w-full rounded-2xl px-2"
+                      >
+                        <EmojiPicker.Group className="pt-2">
+                          <EmojiPicker.List
+                            hideStickyHeader
+                            containerHeight={295}
+                          />
+                        </EmojiPicker.Group>
+                      </EmojiPicker>
+                    </div>
+                  </div>
+                  <FormMessage />
+                </div>
+              </FormItem>
+            )}
+          />
+
+          <Button
+            type="submit"
+            variant="primary"
+            className="mt-2 min-w-[18rem]"
+            disabled={!form.formState.isValid || isPending}
+            loading={isPending}
+          >
+            Save Changes
+          </Button>
+        </Form>
+      </Dialog.Content>
+    </Dialog>
+  );
+}

autogpt_platform/frontend/src/app/(platform)/library/components/LibrarySubSection/LibrarySubSection.tsx

@@ -0,0 +1,21 @@
+import LibraryFolderCreationDialog from "../LibraryFolderCreationDialog/LibraryFolderCreationDialog";
+import { LibraryTabs, Tab } from "../LibraryTabs/LibraryTabs";
+
+interface Props {
+  tabs: Tab[];
+  activeTab: string;
+  onTabChange: (tabId: string) => void;
+}
+
+export function LibrarySubSection({ tabs, activeTab, onTabChange }: Props) {
+  return (
+    <div className="flex items-center justify-between gap-4">
+      <LibraryTabs
+        tabs={tabs}
+        activeTab={activeTab}
+        onTabChange={onTabChange}
+      />
+      <LibraryFolderCreationDialog />
+    </div>
+  );
+}

autogpt_platform/frontend/src/app/(platform)/library/components/LibraryTabs/LibraryTabs.tsx

@@ -0,0 +1,147 @@
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import { motion } from "framer-motion";
+import { cn } from "@/lib/utils";
+import { Icon } from "@phosphor-icons/react";
+import { useFavoriteAnimation } from "../../context/FavoriteAnimationContext";
+
+export interface Tab {
+  id: string;
+  title: string;
+  icon: Icon;
+}
+
+interface Props {
+  tabs: Tab[];
+  activeTab: string;
+  onTabChange: (tabId: string) => void;
+  layoutId?: string;
+}
+
+export function LibraryTabs({
+  tabs,
+  activeTab,
+  onTabChange,
+  layoutId = "library-tabs",
+}: Props) {
+  const { registerFavoritesTabRef } = useFavoriteAnimation();
+
+  return (
+    <div className="flex items-center gap-2">
+      {tabs.map((tab) => (
+        <TabButton
+          key={tab.id}
+          tab={tab}
+          isActive={activeTab === tab.id}
+          onSelect={onTabChange}
+          layoutId={layoutId}
+          onRefReady={
+            tab.id === "favorites" ? registerFavoritesTabRef : undefined
+          }
+        />
+      ))}
+    </div>
+  );
+}
+
+interface TabButtonProps {
+  tab: Tab;
+  isActive: boolean;
+  onSelect: (tabId: string) => void;
+  layoutId: string;
+  onRefReady?: (element: HTMLElement | null) => void;
+}
+
+function TabButton({
+  tab,
+  isActive,
+  onSelect,
+  layoutId,
+  onRefReady,
+}: TabButtonProps) {
+  const [isLoaded, setIsLoaded] = useState(false);
+  const buttonRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (isActive && !isLoaded) {
+      setIsLoaded(true);
+    }
+  }, [isActive, isLoaded]);
+
+  useEffect(() => {
+    if (onRefReady) {
+      onRefReady(buttonRef.current);
+    }
+  }, [onRefReady]);
+
+  const ButtonIcon = tab.icon;
+  const activeColor = "text-primary";
+
+  return (
+    <motion.div
+      ref={buttonRef}
+      layoutId={`${layoutId}-button-${tab.id}`}
+      transition={{
+        layout: {
+          type: "spring",
+          damping: 20,
+          stiffness: 230,
+          mass: 1.2,
+          ease: [0.215, 0.61, 0.355, 1],
+        },
+      }}
+      onClick={() => {
+        onSelect(tab.id);
+        setIsLoaded(true);
+      }}
+      className="flex h-fit w-fit"
+      style={{ willChange: "transform" }}
+    >
+      <motion.div
+        layout
+        transition={{
+          layout: {
+            type: "spring",
+            damping: 20,
+            stiffness: 230,
+            mass: 1.2,
+          },
+        }}
+        className={cn(
+          "flex h-fit cursor-pointer items-center gap-1.5 overflow-hidden border border-zinc-200 px-3 py-2 text-black transition-colors duration-75 ease-out hover:border-zinc-300 hover:bg-zinc-300",
+          isActive && activeColor,
+          isActive ? "px-4" : "px-3",
+        )}
+        style={{
+          borderRadius: "25px",
+        }}
+      >
+        <motion.div
+          layoutId={`${layoutId}-icon-${tab.id}`}
+          className="shrink-0"
+        >
+          <ButtonIcon size={18} />
+        </motion.div>
+        {isActive && (
+          <motion.div
+            className="flex items-center"
+            initial={isLoaded ? { opacity: 0, filter: "blur(4px)" } : false}
+            animate={{ opacity: 1, filter: "blur(0px)" }}
+            transition={{
+              duration: isLoaded ? 0.2 : 0,
+              ease: [0.86, 0, 0.07, 1],
+            }}
+          >
+            <motion.span
+              layoutId={`${layoutId}-text-${tab.id}`}
+              className="font-sans text-sm font-medium text-black"
+            >
+              {tab.title}
+            </motion.span>
+          </motion.div>
+        )}
+      </motion.div>
+    </motion.div>
+  );
+}

autogpt_platform/frontend/src/app/(platform)/library/components/MoveToFolderDialog/MoveToFolderDialog.tsx

@@ -0,0 +1,135 @@
+"use client";
+
+import { Button } from "@/components/atoms/Button/Button";
+import { Input } from "@/components/atoms/Input/Input";
+import { Text } from "@/components/atoms/Text/Text";
+import { Dialog } from "@/components/molecules/Dialog/Dialog";
+import { useToast } from "@/components/molecules/Toast/use-toast";
+import {
+  useGetV2ListLibraryFolders,
+  usePostV2BulkMoveAgents,
+  getGetV2ListLibraryFoldersQueryKey,
+} from "@/app/api/__generated__/endpoints/folders/folders";
+import { getGetV2ListLibraryAgentsQueryKey } from "@/app/api/__generated__/endpoints/library/library";
+import { okData } from "@/app/api/helpers";
+import { useQueryClient } from "@tanstack/react-query";
+import { useState } from "react";
+
+interface Props {
+  agentId: string;
+  agentName: string;
+  currentFolderId?: string | null;
+  isOpen: boolean;
+  setIsOpen: (open: boolean) => void;
+}
+
+export function MoveToFolderDialog({
+  agentId,
+  agentName,
+  currentFolderId,
+  isOpen,
+  setIsOpen,
+}: Props) {
+  const queryClient = useQueryClient();
+  const { toast } = useToast();
+  const [search, setSearch] = useState("");
+
+  const { data: foldersData } = useGetV2ListLibraryFolders(undefined, {
+    query: { select: okData },
+  });
+
+  const { mutate: moveAgent, isPending } = usePostV2BulkMoveAgents({
+    mutation: {
+      onSuccess: () => {
+        queryClient.invalidateQueries({
+          queryKey: getGetV2ListLibraryAgentsQueryKey(),
+        });
+        queryClient.invalidateQueries({
+          queryKey: getGetV2ListLibraryFoldersQueryKey(),
+        });
+        setIsOpen(false);
+        setSearch("");
+        toast({
+          title: "Agent moved",
+          description: `"${agentName}" has been moved.`,
+        });
+      },
+      onError: () => {
+        toast({
+          title: "Error",
+          description: "Failed to move agent. Please try again.",
+          variant: "destructive",
+        });
+      },
+    },
+  });
+
+  const folders = (foldersData?.folders ?? []).filter(
+    (f) =>
+      f.id !== currentFolderId &&
+      f.name.toLowerCase().includes(search.toLowerCase()),
+  );
+
+  function handleMoveToFolder(folderId: string) {
+    moveAgent({
+      data: {
+        agent_ids: [agentId],
+        folder_id: folderId,
+      },
+    });
+  }
+
+  return (
+    <Dialog
+      controlled={{ isOpen, set: setIsOpen }}
+      styling={{ maxWidth: "28rem" }}
+      title="Move to folder"
+      onClose={() => {
+        setSearch("");
+      }}
+    >
+      <Dialog.Content>
+        <div className="flex flex-col gap-3">
+          <Input
+            id="search-folders"
+            label="Search folders"
+            placeholder="Search folders..."
+            value={search}
+            onChange={(e) => setSearch(e.target.value)}
+            className="w-full"
+          />
+          <div className="max-h-[280px] overflow-y-auto">
+            {folders.length === 0 ? (
+              <div className="flex h-20 items-center justify-center">
+                <Text variant="small" className="text-zinc-400">
+                  No folders found
+                </Text>
+              </div>
+            ) : (
+              <div className="flex flex-col gap-1">
+                {folders.map((folder) => (
+                  <Button
+                    key={folder.id}
+                    variant="ghost"
+                    className="w-full justify-start gap-3 px-3 py-2.5"
+                    disabled={isPending}
+                    onClick={() => handleMoveToFolder(folder.id)}
+                  >
+                    <span className="text-lg">{folder.icon ?? "📁"}</span>
+                    <div className="flex flex-col items-start">
+                      <Text variant="small-medium">{folder.name}</Text>
+                      <Text variant="small" className="text-zinc-400">
+                        {folder.agent_count ?? 0}{" "}
+                        {(folder.agent_count ?? 0) === 1 ? "agent" : "agents"}
+                      </Text>
+                    </div>
+                  </Button>
+                ))}
+              </div>
+            )}
+          </div>
+        </div>
+      </Dialog.Content>
+    </Dialog>
+  );
+}

autogpt_platform/frontend/src/app/(platform)/library/context/FavoriteAnimationContext.tsx

@@ -0,0 +1,84 @@
+"use client";
+
+import {
+  createContext,
+  useContext,
+  useState,
+  useCallback,
+  useRef,
+} from "react";
+import { FlyingHeart } from "../components/FlyingHeart/FlyingHeart";
+
+interface FavoriteAnimationContextType {
+  triggerFavoriteAnimation: (startPosition: { x: number; y: number }) => void;
+  registerFavoritesTabRef: (element: HTMLElement | null) => void;
+}
+
+const FavoriteAnimationContext =
+  createContext<FavoriteAnimationContextType | null>(null);
+
+interface FavoriteAnimationProviderProps {
+  children: React.ReactNode;
+  onAnimationComplete?: () => void;
+}
+
+export function FavoriteAnimationProvider({
+  children,
+  onAnimationComplete,
+}: FavoriteAnimationProviderProps) {
+  const [animationState, setAnimationState] = useState<{
+    startPosition: { x: number; y: number } | null;
+    targetPosition: { x: number; y: number } | null;
+  }>({
+    startPosition: null,
+    targetPosition: null,
+  });
+
+  const favoritesTabRef = useRef<HTMLElement | null>(null);
+
+  const registerFavoritesTabRef = useCallback((element: HTMLElement | null) => {
+    favoritesTabRef.current = element;
+  }, []);
+
+  const triggerFavoriteAnimation = useCallback(
+    (startPosition: { x: number; y: number }) => {
+      if (favoritesTabRef.current) {
+        const rect = favoritesTabRef.current.getBoundingClientRect();
+        const targetPosition = {
+          x: rect.left + rect.width / 2 - 12,
+          y: rect.top + rect.height / 2 - 12,
+        };
+        setAnimationState({ startPosition, targetPosition });
+      }
+    },
+    [],
+  );
+
+  function handleAnimationComplete() {
+    setAnimationState({ startPosition: null, targetPosition: null });
+    onAnimationComplete?.();
+  }
+
+  return (
+    <FavoriteAnimationContext.Provider
+      value={{ triggerFavoriteAnimation, registerFavoritesTabRef }}
+    >
+      {children}
+      <FlyingHeart
+        startPosition={animationState.startPosition}
+        targetPosition={animationState.targetPosition}
+        onAnimationComplete={handleAnimationComplete}
+      />
+    </FavoriteAnimationContext.Provider>
+  );
+}
+
+export function useFavoriteAnimation() {
+  const context = useContext(FavoriteAnimationContext);
+  if (!context) {
+    throw new Error(
+      "useFavoriteAnimation must be used within FavoriteAnimationProvider",
+    );
+  }
+  return context;
+}

autogpt_platform/frontend/src/app/(platform)/library/page.tsx

@@ -1,28 +1,55 @@
 "use client";
 
-import { useEffect } from "react";
-import { FavoritesSection } from "./components/FavoritesSection/FavoritesSection";
+import { useEffect, useState, useCallback } from "react";
+import { HeartIcon, ListIcon } from "@phosphor-icons/react";
 import { LibraryActionHeader } from "./components/LibraryActionHeader/LibraryActionHeader";
 import { LibraryAgentList } from "./components/LibraryAgentList/LibraryAgentList";
+import { Tab } from "./components/LibraryTabs/LibraryTabs";
 import { useLibraryListPage } from "./components/useLibraryListPage";
+import { FavoriteAnimationProvider } from "./context/FavoriteAnimationContext";
+
+const LIBRARY_TABS: Tab[] = [
+  { id: "all", title: "All", icon: ListIcon },
+  { id: "favorites", title: "Favorites", icon: HeartIcon },
+];
 
 export default function LibraryPage() {
   const { searchTerm, setSearchTerm, librarySort, setLibrarySort } =
     useLibraryListPage();
+  const [selectedFolderId, setSelectedFolderId] = useState<string | null>(null);
+  const [activeTab, setActiveTab] = useState(LIBRARY_TABS[0].id);
 
   useEffect(() => {
     document.title = "Library – AutoGPT Platform";
   }, []);
 
+  function handleTabChange(tabId: string) {
+    setActiveTab(tabId);
+    setSelectedFolderId(null);
+  }
+
+  const handleFavoriteAnimationComplete = useCallback(() => {
+    setActiveTab("favorites");
+    setSelectedFolderId(null);
+  }, []);
+
   return (
-    <main className="pt-160 container min-h-screen space-y-4 pb-20 pt-16 sm:px-8 md:px-12">
-      <LibraryActionHeader setSearchTerm={setSearchTerm} />
-      <FavoritesSection searchTerm={searchTerm} />
-      <LibraryAgentList
-        searchTerm={searchTerm}
-        librarySort={librarySort}
-        setLibrarySort={setLibrarySort}
-      />
-    </main>
+    <FavoriteAnimationProvider
+      onAnimationComplete={handleFavoriteAnimationComplete}
+    >
+      <main className="pt-160 container min-h-screen space-y-4 pb-20 pt-16 sm:px-8 md:px-12">
+        <LibraryActionHeader setSearchTerm={setSearchTerm} />
+        <LibraryAgentList
+          searchTerm={searchTerm}
+          librarySort={librarySort}
+          setLibrarySort={setLibrarySort}
+          selectedFolderId={selectedFolderId}
+          onFolderSelect={setSelectedFolderId}
+          tabs={LIBRARY_TABS}
+          activeTab={activeTab}
+          onTabChange={handleTabChange}
+        />
+      </main>
+    </FavoriteAnimationProvider>
   );
 }

autogpt_platform/frontend/src/app/api/openapi.json

@@ -3658,6 +3658,29 @@
               "title": "Page Size"
             },
             "description": "Number of agents per page (must be >= 1)"
+          },
+          {
+            "name": "folder_id",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "anyOf": [{ "type": "string" }, { "type": "null" }],
+              "description": "Filter by folder ID",
+              "title": "Folder Id"
+            },
+            "description": "Filter by folder ID"
+          },
+          {
+            "name": "include_root_only",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "boolean",
+              "description": "Only return agents without a folder (root-level agents)",
+              "default": false,
+              "title": "Include Root Only"
+            },
+            "description": "Only return agents without a folder (root-level agents)"
           }
         ],
         "responses": {
@@ -4025,6 +4048,338 @@
         }
       }
     },
+    "/api/library/folders": {
+      "get": {
+        "tags": ["v2", "library", "folders", "private"],
+        "summary": "List Library Folders",
+        "description": "List folders for the authenticated user.\n\nArgs:\n    user_id: ID of the authenticated user.\n    parent_id: Optional parent folder ID to filter by.\n    include_relations: Whether to include agent and subfolder relations for counts.\n\nReturns:\n    A FolderListResponse containing folders.",
+        "operationId": "getV2List library folders",
+        "security": [{ "HTTPBearerJWT": [] }],
+        "parameters": [
+          {
+            "name": "parent_id",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "anyOf": [{ "type": "string" }, { "type": "null" }],
+              "description": "Filter by parent folder ID. If not provided, returns root-level folders.",
+              "title": "Parent Id"
+            },
+            "description": "Filter by parent folder ID. If not provided, returns root-level folders."
+          },
+          {
+            "name": "include_relations",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "boolean",
+              "description": "Include agent and subfolder relations (for counts)",
+              "default": true,
+              "title": "Include Relations"
+            },
+            "description": "Include agent and subfolder relations (for counts)"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of folders",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/FolderListResponse" }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+              }
+            }
+          },
+          "500": { "description": "Server error" }
+        }
+      },
+      "post": {
+        "tags": ["v2", "library", "folders", "private"],
+        "summary": "Create Folder",
+        "description": "Create a new folder.\n\nArgs:\n    payload: The folder creation request.\n    user_id: ID of the authenticated user.\n\nReturns:\n    The created LibraryFolder.",
+        "operationId": "postV2Create folder",
+        "security": [{ "HTTPBearerJWT": [] }],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/FolderCreateRequest" }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Folder created successfully",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/LibraryFolder" }
+              }
+            }
+          },
+          "400": { "description": "Validation error" },
+          "401": {
+            "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+          },
+          "404": { "description": "Parent folder not found" },
+          "409": { "description": "Folder name conflict" },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+              }
+            }
+          },
+          "500": { "description": "Server error" }
+        }
+      }
+    },
+    "/api/library/folders/agents/bulk-move": {
+      "post": {
+        "tags": ["v2", "library", "folders", "private"],
+        "summary": "Bulk Move Agents",
+        "description": "Move multiple agents to a folder.\n\nArgs:\n    payload: The bulk move request with agent IDs and target folder.\n    user_id: ID of the authenticated user.\n\nReturns:\n    The updated LibraryAgents.",
+        "operationId": "postV2Bulk move agents",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/BulkMoveAgentsRequest" }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "Agents moved successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "items": { "$ref": "#/components/schemas/LibraryAgent" },
+                  "type": "array",
+                  "title": "Response Postv2Bulk Move Agents"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+          },
+          "404": { "description": "Folder not found" },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+              }
+            }
+          },
+          "500": { "description": "Server error" }
+        },
+        "security": [{ "HTTPBearerJWT": [] }]
+      }
+    },
+    "/api/library/folders/tree": {
+      "get": {
+        "tags": ["v2", "library", "folders", "private"],
+        "summary": "Get Folder Tree",
+        "description": "Get the full folder tree for the authenticated user.\n\nArgs:\n    user_id: ID of the authenticated user.\n\nReturns:\n    A FolderTreeResponse containing the nested folder structure.",
+        "operationId": "getV2Get folder tree",
+        "responses": {
+          "200": {
+            "description": "Folder tree structure",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/FolderTreeResponse" }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+          },
+          "500": { "description": "Server error" }
+        },
+        "security": [{ "HTTPBearerJWT": [] }]
+      }
+    },
+    "/api/library/folders/{folder_id}": {
+      "delete": {
+        "tags": ["v2", "library", "folders", "private"],
+        "summary": "Delete Folder",
+        "description": "Soft-delete a folder and all its contents.\n\nArgs:\n    folder_id: ID of the folder to delete.\n    user_id: ID of the authenticated user.\n\nReturns:\n    204 No Content if successful.",
+        "operationId": "deleteV2Delete folder",
+        "security": [{ "HTTPBearerJWT": [] }],
+        "parameters": [
+          {
+            "name": "folder_id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string", "title": "Folder Id" }
+          }
+        ],
+        "responses": {
+          "204": { "description": "Folder deleted successfully" },
+          "401": {
+            "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+          },
+          "404": { "description": "Folder not found" },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+              }
+            }
+          },
+          "500": { "description": "Server error" }
+        }
+      },
+      "get": {
+        "tags": ["v2", "library", "folders", "private"],
+        "summary": "Get Folder",
+        "description": "Get a specific folder.\n\nArgs:\n    folder_id: ID of the folder to retrieve.\n    user_id: ID of the authenticated user.\n\nReturns:\n    The requested LibraryFolder.",
+        "operationId": "getV2Get folder",
+        "security": [{ "HTTPBearerJWT": [] }],
+        "parameters": [
+          {
+            "name": "folder_id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string", "title": "Folder Id" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Folder details",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/LibraryFolder" }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+          },
+          "404": { "description": "Folder not found" },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+              }
+            }
+          },
+          "500": { "description": "Server error" }
+        }
+      },
+      "patch": {
+        "tags": ["v2", "library", "folders", "private"],
+        "summary": "Update Folder",
+        "description": "Update a folder's properties.\n\nArgs:\n    folder_id: ID of the folder to update.\n    payload: The folder update request.\n    user_id: ID of the authenticated user.\n\nReturns:\n    The updated LibraryFolder.",
+        "operationId": "patchV2Update folder",
+        "security": [{ "HTTPBearerJWT": [] }],
+        "parameters": [
+          {
+            "name": "folder_id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string", "title": "Folder Id" }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/FolderUpdateRequest" }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Folder updated successfully",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/LibraryFolder" }
+              }
+            }
+          },
+          "400": { "description": "Validation error" },
+          "401": {
+            "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+          },
+          "404": { "description": "Folder not found" },
+          "409": { "description": "Folder name conflict" },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+              }
+            }
+          },
+          "500": { "description": "Server error" }
+        }
+      }
+    },
+    "/api/library/folders/{folder_id}/move": {
+      "post": {
+        "tags": ["v2", "library", "folders", "private"],
+        "summary": "Move Folder",
+        "description": "Move a folder to a new parent.\n\nArgs:\n    folder_id: ID of the folder to move.\n    payload: The move request with target parent.\n    user_id: ID of the authenticated user.\n\nReturns:\n    The moved LibraryFolder.",
+        "operationId": "postV2Move folder",
+        "security": [{ "HTTPBearerJWT": [] }],
+        "parameters": [
+          {
+            "name": "folder_id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string", "title": "Folder Id" }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/FolderMoveRequest" }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Folder moved successfully",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/LibraryFolder" }
+              }
+            }
+          },
+          "400": { "description": "Validation error (circular reference)" },
+          "401": {
+            "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+          },
+          "404": { "description": "Folder or target parent not found" },
+          "409": { "description": "Folder name conflict in target location" },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+              }
+            }
+          },
+          "500": { "description": "Server error" }
+        }
+      }
+    },
     "/api/library/presets": {
       "get": {
         "tags": ["v2", "presets"],
@@ -7575,6 +7930,23 @@
         "required": ["file"],
         "title": "Body_postV2Upload submission media"
       },
+      "BulkMoveAgentsRequest": {
+        "properties": {
+          "agent_ids": {
+            "items": { "type": "string" },
+            "type": "array",
+            "title": "Agent Ids"
+          },
+          "folder_id": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Folder Id"
+          }
+        },
+        "type": "object",
+        "required": ["agent_ids"],
+        "title": "BulkMoveAgentsRequest",
+        "description": "Request model for moving multiple agents to a folder."
+      },
       "CancelTaskResponse": {
         "properties": {
           "cancelled": { "type": "boolean", "title": "Cancelled" },
@@ -8315,6 +8687,96 @@
         "title": "ExecutionStartedResponse",
         "description": "Response for run/schedule actions."
       },
+      "FolderCreateRequest": {
+        "properties": {
+          "name": {
+            "type": "string",
+            "maxLength": 100,
+            "minLength": 1,
+            "title": "Name"
+          },
+          "icon": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Icon"
+          },
+          "color": {
+            "anyOf": [
+              { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
+              { "type": "null" }
+            ],
+            "title": "Color",
+            "description": "Hex color code (#RRGGBB)"
+          },
+          "parent_id": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Parent Id"
+          }
+        },
+        "type": "object",
+        "required": ["name"],
+        "title": "FolderCreateRequest",
+        "description": "Request model for creating a folder."
+      },
+      "FolderListResponse": {
+        "properties": {
+          "folders": {
+            "items": { "$ref": "#/components/schemas/LibraryFolder" },
+            "type": "array",
+            "title": "Folders"
+          },
+          "pagination": { "$ref": "#/components/schemas/Pagination" }
+        },
+        "type": "object",
+        "required": ["folders", "pagination"],
+        "title": "FolderListResponse",
+        "description": "Response schema for a list of folders."
+      },
+      "FolderMoveRequest": {
+        "properties": {
+          "target_parent_id": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Target Parent Id"
+          }
+        },
+        "type": "object",
+        "title": "FolderMoveRequest",
+        "description": "Request model for moving a folder to a new parent."
+      },
+      "FolderTreeResponse": {
+        "properties": {
+          "tree": {
+            "items": { "$ref": "#/components/schemas/LibraryFolderTree" },
+            "type": "array",
+            "title": "Tree"
+          }
+        },
+        "type": "object",
+        "required": ["tree"],
+        "title": "FolderTreeResponse",
+        "description": "Response schema for folder tree structure."
+      },
+      "FolderUpdateRequest": {
+        "properties": {
+          "name": {
+            "anyOf": [
+              { "type": "string", "maxLength": 100, "minLength": 1 },
+              { "type": "null" }
+            ],
+            "title": "Name"
+          },
+          "icon": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Icon"
+          },
+          "color": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Color"
+          }
+        },
+        "type": "object",
+        "title": "FolderUpdateRequest",
+        "description": "Request model for updating a folder."
+      },
       "Graph": {
         "properties": {
           "id": { "type": "string", "title": "Id" },
@@ -9203,6 +9665,14 @@
             "title": "Is Latest Version"
           },
           "is_favorite": { "type": "boolean", "title": "Is Favorite" },
+          "folder_id": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Folder Id"
+          },
+          "folder_name": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Folder Name"
+          },
           "recommended_schedule_cron": {
             "anyOf": [{ "type": "string" }, { "type": "null" }],
             "title": "Recommended Schedule Cron"
@@ -9470,12 +9940,109 @@
               { "type": "null" }
             ],
             "description": "User-specific settings for this library agent"
+          },
+          "folder_id": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Folder Id",
+            "description": "Folder ID to move agent to (None to move to root)"
           }
         },
         "type": "object",
         "title": "LibraryAgentUpdateRequest",
         "description": "Schema for updating a library agent via PUT.\n\nIncludes flags for auto-updating version, marking as favorite,\narchiving, or deleting."
       },
+      "LibraryFolder": {
+        "properties": {
+          "id": { "type": "string", "title": "Id" },
+          "user_id": { "type": "string", "title": "User Id" },
+          "name": { "type": "string", "title": "Name" },
+          "icon": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Icon"
+          },
+          "color": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Color"
+          },
+          "parent_id": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Parent Id"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "title": "Created At"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time",
+            "title": "Updated At"
+          },
+          "agent_count": {
+            "type": "integer",
+            "title": "Agent Count",
+            "default": 0
+          },
+          "subfolder_count": {
+            "type": "integer",
+            "title": "Subfolder Count",
+            "default": 0
+          }
+        },
+        "type": "object",
+        "required": ["id", "user_id", "name", "created_at", "updated_at"],
+        "title": "LibraryFolder",
+        "description": "Represents a folder for organizing library agents."
+      },
+      "LibraryFolderTree": {
+        "properties": {
+          "id": { "type": "string", "title": "Id" },
+          "user_id": { "type": "string", "title": "User Id" },
+          "name": { "type": "string", "title": "Name" },
+          "icon": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Icon"
+          },
+          "color": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Color"
+          },
+          "parent_id": {
+            "anyOf": [{ "type": "string" }, { "type": "null" }],
+            "title": "Parent Id"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "title": "Created At"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time",
+            "title": "Updated At"
+          },
+          "agent_count": {
+            "type": "integer",
+            "title": "Agent Count",
+            "default": 0
+          },
+          "subfolder_count": {
+            "type": "integer",
+            "title": "Subfolder Count",
+            "default": 0
+          },
+          "children": {
+            "items": { "$ref": "#/components/schemas/LibraryFolderTree" },
+            "type": "array",
+            "title": "Children",
+            "default": []
+          }
+        },
+        "type": "object",
+        "required": ["id", "user_id", "name", "created_at", "updated_at"],
+        "title": "LibraryFolderTree",
+        "description": "Folder with nested children for tree view."
+      },
       "Link": {
         "properties": {
           "id": { "type": "string", "title": "Id" },

autogpt_platform/frontend/src/components/contextual/CredentialsInput/components/CredentialsFlatView/CredentialsFlatView.tsx

@@ -119,7 +119,7 @@ export function CredentialsFlatView({
       ) : (
         !readOnly && (
           <Button
-            variant="secondary"
+            variant="primary"
             size="small"
             onClick={onAddCredential}
             className="w-fit"

autogpt_platform/frontend/src/components/renderers/InputRenderer/FormRenderer.tsx

@@ -1,10 +1,11 @@
+import { cn } from "@/lib/utils";
 import { RJSFSchema } from "@rjsf/utils";
-import { preprocessInputSchema } from "./utils/input-schema-pre-processor";
 import { useMemo } from "react";
-import { customValidator } from "./utils/custom-validator";
 import Form from "./registry";
 import { ExtendedFormContextType } from "./types";
+import { customValidator } from "./utils/custom-validator";
 import { generateUiSchemaForCustomFields } from "./utils/generate-ui-schema";
+import { preprocessInputSchema } from "./utils/input-schema-pre-processor";
 
 type FormRendererProps = {
   jsonSchema: RJSFSchema;
@@ -12,15 +13,17 @@ type FormRendererProps = {
   uiSchema: any;
   initialValues: any;
   formContext: ExtendedFormContextType;
+  className?: string;
 };
 
-export const FormRenderer = ({
+export function FormRenderer({
   jsonSchema,
   handleChange,
   uiSchema,
   initialValues,
   formContext,
-}: FormRendererProps) => {
+  className,
+}: FormRendererProps) {
   const preprocessedSchema = useMemo(() => {
     return preprocessInputSchema(jsonSchema);
   }, [jsonSchema]);
@@ -31,7 +34,10 @@ export const FormRenderer = ({
   }, [preprocessedSchema, uiSchema]);
 
   return (
-    <div className={"mb-6 mt-4"} data-tutorial-id="input-handles">
+    <div
+      className={cn("mb-6 mt-4", className)}
+      data-tutorial-id="input-handles"
+    >
       <Form
         formContext={formContext}
         idPrefix="agpt"
@@ -45,4 +51,4 @@ export const FormRenderer = ({
       />
     </div>
   );
-};
+}

autogpt_platform/frontend/src/tests/pages/library.page.ts

@@ -444,7 +444,10 @@ export async function navigateToAgentByName(
   // Wait for the agent card to be visible before clicking
   // This handles async loading of agents after page navigation
   await agentCard.waitFor({ state: "visible", timeout: 15000 });
-  await agentCard.click();
+  // Click the link inside the card to navigate reliably through
+  // the motion.div + draggable wrapper layers.
+  const link = agentCard.locator('a[href*="/library/agents/"]').first();
+  await link.click();
 }
 
 export async function clickRunButton(page: Page): Promise<void> {
@@ -481,19 +484,17 @@ export async function clickRunButton(page: Page): Promise<void> {
   // Check which button is visible and click it
   if (await setupTaskButton.isVisible()) {
     await setupTaskButton.click();
-    await page
-      .getByRole("button", { name: /Start Task/i })
-      .first()
-      .click({ timeout: 10000 });
+    const startBtn = page.getByRole("button", { name: /Start Task/i }).first();
+    await startBtn.waitFor({ state: "visible", timeout: 15000 });
+    await startBtn.click();
     return;
   }
 
   if (await newTaskButton.isVisible()) {
     await newTaskButton.click();
-    await page
-      .getByRole("button", { name: /Start Task/i })
-      .first()
-      .click({ timeout: 10000 });
+    const startBtn = page.getByRole("button", { name: /Start Task/i }).first();
+    await startBtn.waitFor({ state: "visible", timeout: 15000 });
+    await startBtn.click();
     return;
   }
 

docs/platform/getting-started.md

@@ -218,6 +218,17 @@ If you initially installed Docker with Hyper-V, you **don’t need to reinstall*
 
 For more details, refer to [Docker's official documentation](https://docs.docker.com/desktop/windows/wsl/).
 
+### ⚠️ Podman Not Supported
+
+AutoGPT requires **Docker** (Docker Desktop or Docker Engine). **Podman and podman-compose are not supported** and may cause path resolution issues, particularly on Windows.
+
+If you see errors like:
+```text
+Error: the specified Containerfile or Dockerfile does not exist, ..\..\autogpt_platform\backend\Dockerfile
+```
+
+This indicates you're using Podman instead of Docker. Please install [Docker Desktop](https://docs.docker.com/desktop/) and use `docker compose` instead of `podman-compose`.
+
 
 ## Development