Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

feat(platform): add workspace folders for artifacts page (#13359)

Abhimanyu Yadavd9041c5b7a6f
diff --git a/autogpt_platform/backend/backend/api/features/workspace/folder_routes.py b/autogpt_platform/backend/backend/api/features/workspace/folder_routes.py
new file mode 100644
index 0000000000..a7617464d5
--- /dev/null
+++ b/autogpt_platform/backend/backend/api/features/workspace/folder_routes.py
@@ -0,0 +1,138 @@
+"""
+Workspace folder API routes.
+
+Folders are a DB-level organizational layer over workspace files; storage paths
+are unaffected. Routes spell out their full ``/folders`` paths (matching the
+sibling workspace file routes) and are included into the workspace router, which
+the app mounts under ``/api/workspace`` — giving ``/api/workspace/folders``.
+"""
+
+from typing import Annotated
+
+import fastapi
+from autogpt_libs.auth.dependencies import get_user_id, requires_user
+from fastapi.responses import Response
+from pydantic import BaseModel, Field
+
+from backend.data.workspace import WorkspaceFile, get_or_create_workspace
+from backend.data.workspace_folder import (
+ WorkspaceFolder,
+ bulk_move_files_to_folder,
+ create_folder,
+ delete_folder,
+ list_folders,
+ update_folder,
+)
+
+router = fastapi.APIRouter(
+ dependencies=[fastapi.Security(requires_user)],
+)
+
+
+class WorkspaceFolderCreateRequest(BaseModel):
+ name: str = Field(..., min_length=1, max_length=100)
+ icon: str | None = None
+
+
+class WorkspaceFolderUpdateRequest(BaseModel):
+ name: str | None = Field(None, min_length=1, max_length=100)
+ icon: str | None = None
+
+
+class BulkMoveFilesRequest(BaseModel):
+ file_ids: list[str]
+ # None = move to root. Reject "" so it can't bypass the truthiness-based
+ # ownership check and hit a foreign-key error (returns 422 instead).
+ folder_id: str | None = Field(None, min_length=1)
+
+
+class WorkspaceFolderListResponse(BaseModel):
+ folders: list[WorkspaceFolder]
+
+
+ "/folders",
+ summary="List workspace folders",
+ operation_id="listWorkspaceFolders",
+)
+async def list_workspace_folders(
+ user_id: Annotated[str, fastapi.Security(get_user_id)],
+) -> WorkspaceFolderListResponse:
+ workspace = await get_or_create_workspace(user_id)
+ folders = await list_folders(workspace.id)
+ return WorkspaceFolderListResponse(folders=folders)
+
+
+ "/folders",
+ summary="Create workspace folder",
+ operation_id="createWorkspaceFolder",
+ status_code=fastapi.status.HTTP_201_CREATED,
+ responses={409: {"description": "A folder with this name already exists"}},
+)
+async def create_workspace_folder(
+ user_id: Annotated[str, fastapi.Security(get_user_id)],
+ payload: WorkspaceFolderCreateRequest,
+) -> WorkspaceFolder:
+ workspace = await get_or_create_workspace(user_id)
+ return await create_folder(
+ workspace_id=workspace.id,
+ name=payload.name,
+ icon=payload.icon,
+ )
+
+
+ "/folders/{folder_id}",
+ summary="Update workspace folder",
+ operation_id="updateWorkspaceFolder",
+ responses={
+ 404: {"description": "Folder not found"},
+ 409: {"description": "A folder with this name already exists"},
+ },
+)
+async def update_workspace_folder(
+ user_id: Annotated[str, fastapi.Security(get_user_id)],
+ folder_id: str,
+ payload: WorkspaceFolderUpdateRequest,
+) -> WorkspaceFolder:
+ workspace = await get_or_create_workspace(user_id)
+ return await update_folder(
+ folder_id=folder_id,
+ workspace_id=workspace.id,
+ name=payload.name,
+ icon=payload.icon,
+ )
+
+
+ "/folders/{folder_id}",
+ summary="Delete workspace folder",
+ operation_id="deleteWorkspaceFolder",
+ status_code=fastapi.status.HTTP_204_NO_CONTENT,
+ responses={404: {"description": "Folder not found"}},
+)
+async def delete_workspace_folder(
+ user_id: Annotated[str, fastapi.Security(get_user_id)],
+ folder_id: str,
+) -> Response:
+ workspace = await get_or_create_workspace(user_id)
+ await delete_folder(folder_id=folder_id, workspace_id=workspace.id)
+ return Response(status_code=fastapi.status.HTTP_204_NO_CONTENT)
+
+
+ "/folders/files/bulk-move",
+ summary="Move workspace files to a folder",
+ operation_id="bulkMoveWorkspaceFiles",
+)
+async def bulk_move_workspace_files(
+ user_id: Annotated[str, fastapi.Security(get_user_id)],
+ payload: BulkMoveFilesRequest,
+) -> list[WorkspaceFile]:
+ workspace = await get_or_create_workspace(user_id)
+ return await bulk_move_files_to_folder(
+ workspace_id=workspace.id,
+ file_ids=payload.file_ids,
+ folder_id=payload.folder_id,
+ )
diff --git a/autogpt_platform/backend/backend/api/features/workspace/folder_routes_test.py b/autogpt_platform/backend/backend/api/features/workspace/folder_routes_test.py
new file mode 100644
index 0000000000..9348f0386e
--- /dev/null
+++ b/autogpt_platform/backend/backend/api/features/workspace/folder_routes_test.py
@@ -0,0 +1,228 @@
+from datetime import datetime, timezone
+from unittest.mock import AsyncMock
+
+import fastapi
+import fastapi.testclient
+import pytest
+
+from backend.api.features.library.exceptions import FolderAlreadyExistsError
+from backend.api.features.workspace.folder_routes import router
+from backend.data.workspace import Workspace, WorkspaceFile
+from backend.data.workspace_folder import WorkspaceFolder
+from backend.util.exceptions import NotFoundError
+
+app = fastapi.FastAPI()
+# The router owns its /folders prefix (see folder_routes.py), so mounting it
+# plainly here exercises the same /folders/* paths the app serves.
+app.include_router(router)
+
+
[email protected]_handler(FolderAlreadyExistsError)
+async def _folder_exists_handler(
+ request: fastapi.Request, exc: FolderAlreadyExistsError
+) -> fastapi.responses.JSONResponse:
+ return fastapi.responses.JSONResponse(status_code=409, content={"detail": str(exc)})
+
+
[email protected]_handler(NotFoundError)
+async def _not_found_handler(
+ request: fastapi.Request, exc: NotFoundError
+) -> fastapi.responses.JSONResponse:
+ return fastapi.responses.JSONResponse(status_code=404, content={"detail": str(exc)})
+
+
+client = fastapi.testclient.TestClient(app)
+
+
[email protected](autouse=True)
+def setup_app_auth(mock_jwt_user):
+ from autogpt_libs.auth.jwt_utils import get_jwt_payload
+
+ app.dependency_overrides[get_jwt_payload] = mock_jwt_user["get_jwt_payload"]
+ yield
+ app.dependency_overrides.clear()
+
+
+def _make_workspace() -> Workspace:
+ return Workspace(
+ id="ws-001",
+ user_id="test-user-id",
+ created_at=datetime(2026, 1, 1, tzinfo=timezone.utc),
+ updated_at=datetime(2026, 1, 1, tzinfo=timezone.utc),
+ )
+
+
+def _make_folder(**overrides) -> WorkspaceFolder:
+ defaults = {
+ "id": "fld-1",
+ "workspace_id": "ws-001",
+ "name": "Reports",
+ "icon": None,
+ "created_at": datetime(2026, 1, 1, tzinfo=timezone.utc),
+ "updated_at": datetime(2026, 1, 1, tzinfo=timezone.utc),
+ "file_count": 0,
+ }
+ defaults.update(overrides)
+ return WorkspaceFolder(**defaults)
+
+
+def _make_file(**overrides) -> WorkspaceFile:
+ defaults = {
+ "id": "file-001",
+ "workspace_id": "ws-001",
+ "created_at": datetime(2026, 1, 1, tzinfo=timezone.utc),
+ "updated_at": datetime(2026, 1, 1, tzinfo=timezone.utc),
+ "name": "test.txt",
+ "path": "/test.txt",
+ "storage_path": "local://test.txt",
+ "mime_type": "text/plain",
+ "size_bytes": 100,
+ }
+ defaults.update(overrides)
+ return WorkspaceFile(**defaults)
+
+
+def test_list_folders_returns_folders(mocker):
+ mocker.patch(
+ "backend.api.features.workspace.folder_routes.get_or_create_workspace",
+ AsyncMock(return_value=_make_workspace()),
+ )
+ mocker.patch(
+ "backend.api.features.workspace.folder_routes.list_folders",
+ AsyncMock(return_value=[_make_folder(file_count=3)]),
+ )
+
+ response = client.get("/folders")
+ assert response.status_code == 200
+ data = response.json()
+ assert len(data["folders"]) == 1
+ assert data["folders"][0]["id"] == "fld-1"
+ assert data["folders"][0]["file_count"] == 3
+
+
+def test_create_folder_success(mocker):
+ mocker.patch(
+ "backend.api.features.workspace.folder_routes.get_or_create_workspace",
+ AsyncMock(return_value=_make_workspace()),
+ )
+ create = mocker.patch(
+ "backend.api.features.workspace.folder_routes.create_folder",
+ AsyncMock(return_value=_make_folder(name="Invoices")),
+ )
+
+ response = client.post("/folders", json={"name": "Invoices"})
+ assert response.status_code == 201
+ assert response.json()["name"] == "Invoices"
+ create.assert_awaited_once_with(workspace_id="ws-001", name="Invoices", icon=None)
+
+
+def test_create_folder_name_conflict_returns_409(mocker):
+ mocker.patch(
+ "backend.api.features.workspace.folder_routes.get_or_create_workspace",
+ AsyncMock(return_value=_make_workspace()),
+ )
+ mocker.patch(
+ "backend.api.features.workspace.folder_routes.create_folder",
+ AsyncMock(side_effect=FolderAlreadyExistsError("exists")),
+ )
+
+ response = client.post("/folders", json={"name": "Reports"})
+ assert response.status_code == 409
+
+
+def test_update_folder_success(mocker):
+ mocker.patch(
+ "backend.api.features.workspace.folder_routes.get_or_create_workspace",
+ AsyncMock(return_value=_make_workspace()),
+ )
+ update = mocker.patch(
+ "backend.api.features.workspace.folder_routes.update_folder",
+ AsyncMock(return_value=_make_folder(name="Renamed")),
+ )
+
+ response = client.patch("/folders/fld-1", json={"name": "Renamed"})
+ assert response.status_code == 200
+ assert response.json()["name"] == "Renamed"
+ update.assert_awaited_once_with(
+ folder_id="fld-1", workspace_id="ws-001", name="Renamed", icon=None
+ )
+
+
+def test_update_folder_not_found_returns_404(mocker):
+ mocker.patch(
+ "backend.api.features.workspace.folder_routes.get_or_create_workspace",
+ AsyncMock(return_value=_make_workspace()),
+ )
+ mocker.patch(
+ "backend.api.features.workspace.folder_routes.update_folder",
+ AsyncMock(side_effect=NotFoundError("nope")),
+ )
+
+ response = client.patch("/folders/missing", json={"name": "X"})
+ assert response.status_code == 404
+
+
+def test_delete_folder_returns_204(mocker):
+ mocker.patch(
+ "backend.api.features.workspace.folder_routes.get_or_create_workspace",
+ AsyncMock(return_value=_make_workspace()),
+ )
+ delete = mocker.patch(
+ "backend.api.features.workspace.folder_routes.delete_folder",
+ AsyncMock(return_value=None),
+ )
+
+ response = client.delete("/folders/fld-1")
+ assert response.status_code == 204
+ delete.assert_awaited_once_with(folder_id="fld-1", workspace_id="ws-001")
+
+
+def test_bulk_move_files_returns_updated_files(mocker):
+ mocker.patch(
+ "backend.api.features.workspace.folder_routes.get_or_create_workspace",
+ AsyncMock(return_value=_make_workspace()),
+ )
+ move = mocker.patch(
+ "backend.api.features.workspace.folder_routes.bulk_move_files_to_folder",
+ AsyncMock(return_value=[_make_file(id="f1", folder_id="fld-1")]),
+ )
+
+ response = client.post(
+ "/folders/files/bulk-move",
+ json={"file_ids": ["f1"], "folder_id": "fld-1"},
+ )
+ assert response.status_code == 200
+ data = response.json()
+ assert data[0]["id"] == "f1"
+ assert data[0]["folder_id"] == "fld-1"
+ move.assert_awaited_once_with(
+ workspace_id="ws-001", file_ids=["f1"], folder_id="fld-1"
+ )
+
+
+def test_bulk_move_rejects_empty_folder_id():
+ """An empty-string folder_id is rejected at validation (422), not passed
+ through to a foreign-key error."""
+ response = client.post(
+ "/folders/files/bulk-move",
+ json={"file_ids": ["f1"], "folder_id": ""},
+ )
+ assert response.status_code == 422
+
+
+def test_bulk_move_files_to_root(mocker):
+ """folder_id omitted means move to root (None)."""
+ mocker.patch(
+ "backend.api.features.workspace.folder_routes.get_or_create_workspace",
+ AsyncMock(return_value=_make_workspace()),
+ )
+ move = mocker.patch(
+ "backend.api.features.workspace.folder_routes.bulk_move_files_to_folder",
+ AsyncMock(return_value=[]),
+ )
+
+ response = client.post("/folders/files/bulk-move", json={"file_ids": ["f1"]})
+ assert response.status_code == 200
+ move.assert_awaited_once_with(
+ workspace_id="ws-001", file_ids=["f1"], folder_id=None
+ )
diff --git a/autogpt_platform/backend/backend/api/features/workspace/routes.py b/autogpt_platform/backend/backend/api/features/workspace/routes.py
index cf957ce746..1ba04f55aa 100644
--- a/autogpt_platform/backend/backend/api/features/workspace/routes.py
+++ b/autogpt_platform/backend/backend/api/features/workspace/routes.py
@@ -148,6 +148,7 @@ class WorkspaceFileItem(BaseModel):
path: str
mime_type: str
size_bytes: int
+ folder_id: str | None = None
metadata: dict = Field(default_factory=dict)
origin: Literal["uploaded", "generated"]
created_at: str
@@ -400,6 +401,15 @@ async def list_workspace_files(
"Ignored when ``session_id`` is set."
),
),
+ folder_id: str | None = Query(
+ default=None,
+ min_length=1,
+ description="Only return files in this folder.",
+ ),
+ root_only: bool = Query(
+ default=False,
+ description="Only return root-level files (not in any folder).",
+ ),
) -> ListFilesResponse:
"""
List files in the user's workspace.
@@ -410,14 +420,34 @@ async def list_workspace_files(
The Artifacts page uses ``q`` for name search and ``origin`` to filter
between Uploaded (user-uploaded) and Generated (agent/block output) files.
- """
- workspace = await get_or_create_workspace(user_id)
+ ``session_id`` (a per-session view) and the folder filters (``folder_id`` /
+ ``root_only``) are distinct, mutually exclusive axes, and ``folder_id`` and
+ ``root_only`` likewise conflict; passing conflicting filters returns a 400
+ rather than silently yielding an empty list.
+ """
# Treat empty-string session_id the same as omitted — an empty value
# would otherwise silently list files across every session instead of
# scoping to one.
session_id = session_id or None
+ # Reject conflicting filters instead of silently combining them into an
+ # (almost always) empty result. Validate before touching the DB so an
+ # invalid GET can't create a workspace row for a first-time user.
+ # session_id scopes to one chat session; folder_id/root_only organize
+ # files across the whole workspace.
+ if session_id is not None and (folder_id is not None or root_only):
+ raise fastapi.HTTPException(
+ status_code=400,
+ detail="session_id cannot be combined with folder_id or root_only",
+ )
+ if folder_id is not None and root_only:
+ raise fastapi.HTTPException(
+ status_code=400,
+ detail="folder_id and root_only are mutually exclusive",
+ )
+
+ workspace = await get_or_create_workspace(user_id)
manager = WorkspaceManager(user_id, workspace.id, session_id)
include_all = session_id is None
@@ -444,6 +474,8 @@ async def list_workspace_files(
name_contains=name_contains,
metadata_equals=metadata_equals,
metadata_not_equals=metadata_not_equals,
+ folder_id=folder_id,
+ root_only=root_only,
)
has_more = len(files) > limit
page = files[:limit]
@@ -456,6 +488,7 @@ async def list_workspace_files(
path=f.path,
mime_type=f.mime_type,
size_bytes=f.size_bytes,
+ folder_id=f.folder_id,
metadata=f.metadata or {},
origin=_derive_origin(f.metadata),
created_at=f.created_at.isoformat(),
diff --git a/autogpt_platform/backend/backend/api/features/workspace/routes_test.py b/autogpt_platform/backend/backend/api/features/workspace/routes_test.py
index 538b6ad04b..5df821907a 100644
--- a/autogpt_platform/backend/backend/api/features/workspace/routes_test.py
+++ b/autogpt_platform/backend/backend/api/features/workspace/routes_test.py
@@ -70,6 +70,7 @@ def _make_file_mock(**overrides) -> MagicMock:
"path": "/test.txt",
"mime_type": "text/plain",
"size_bytes": 100,
+ "folder_id": None,
"metadata": {},
"created_at": datetime(2026, 1, 1, tzinfo=timezone.utc),
}
@@ -114,6 +115,8 @@ def test_list_files_returns_all_when_no_session(mock_manager_cls, mock_get_works
name_contains=None,
metadata_equals=None,
metadata_not_equals=None,
+ folder_id=None,
+ root_only=False,
)
@@ -136,6 +139,8 @@ def test_list_files_uploaded_origin_filters_on_metadata(
name_contains=None,
metadata_equals={"origin": "user-upload"},
metadata_not_equals=None,
+ folder_id=None,
+ root_only=False,
)
@@ -158,6 +163,8 @@ def test_list_files_generated_origin_excludes_uploads(
name_contains=None,
metadata_equals=None,
metadata_not_equals={"origin": "user-upload"},
+ folder_id=None,
+ root_only=False,
)
@@ -185,6 +192,8 @@ def test_list_files_scopes_to_session_when_provided(
name_contains=None,
metadata_equals=None,
metadata_not_equals=None,
+ folder_id=None,
+ root_only=False,
)
@@ -606,6 +615,8 @@ def test_list_files_has_more_true_when_limit_exceeded(
name_contains=None,
metadata_equals=None,
metadata_not_equals=None,
+ folder_id=None,
+ root_only=False,
)
@@ -646,6 +657,8 @@ def test_list_files_offset_is_echoed_back(mock_manager_cls, mock_get_workspace):
name_contains=None,
metadata_equals=None,
metadata_not_equals=None,
+ folder_id=None,
+ root_only=False,
)
@@ -669,6 +682,8 @@ def test_list_files_origin_ignored_when_session_id_set(
name_contains=None,
metadata_equals=None,
metadata_not_equals=None,
+ folder_id=None,
+ root_only=False,
)
@@ -690,6 +705,8 @@ def test_list_files_q_search_passed_through(mock_manager_cls, mock_get_workspace
name_contains="report",
metadata_equals=None,
metadata_not_equals=None,
+ folder_id=None,
+ root_only=False,
)
@@ -711,6 +728,8 @@ def test_list_files_blank_q_becomes_none(mock_manager_cls, mock_get_workspace):
name_contains=None,
metadata_equals=None,
metadata_not_equals=None,
+ folder_id=None,
+ root_only=False,
)
@@ -732,6 +751,8 @@ def test_list_files_q_and_origin_combine(mock_manager_cls, mock_get_workspace):
name_contains="report",
metadata_equals=None,
metadata_not_equals={"origin": "user-upload"},
+ folder_id=None,
+ root_only=False,
)
@@ -757,6 +778,8 @@ def test_list_files_empty_session_id_treated_as_omitted(
name_contains=None,
metadata_equals=None,
metadata_not_equals=None,
+ folder_id=None,
+ root_only=False,
)
@@ -766,6 +789,113 @@ def test_list_files_rejects_invalid_origin():
assert response.status_code == 422
+@patch("backend.api.features.workspace.routes.get_or_create_workspace")
+@patch("backend.api.features.workspace.routes.WorkspaceManager")
+def test_list_files_folder_id_passed_through(mock_manager_cls, mock_get_workspace):
+ """folder_id forwards to the manager and scopes the listing to that folder."""
+ mock_get_workspace.return_value = _make_workspace()
+ mock_instance = AsyncMock()
+ mock_instance.list_files.return_value = []
+ mock_manager_cls.return_value = mock_instance
+
+ response = client.get("/files?folder_id=fld-1")
+ assert response.status_code == 200
+ mock_instance.list_files.assert_called_once_with(
+ limit=201,
+ offset=0,
+ include_all_sessions=True,
+ name_contains=None,
+ metadata_equals=None,
+ metadata_not_equals=None,
+ folder_id="fld-1",
+ root_only=False,
+ )
+
+
+@patch("backend.api.features.workspace.routes.get_or_create_workspace")
+@patch("backend.api.features.workspace.routes.WorkspaceManager")
+def test_list_files_root_only_passed_through(mock_manager_cls, mock_get_workspace):
+ """root_only forwards to the manager to surface only root-level files."""
+ mock_get_workspace.return_value = _make_workspace()
+ mock_instance = AsyncMock()
+ mock_instance.list_files.return_value = []
+ mock_manager_cls.return_value = mock_instance
+
+ response = client.get("/files?root_only=true")
+ assert response.status_code == 200
+ mock_instance.list_files.assert_called_once_with(
+ limit=201,
+ offset=0,
+ include_all_sessions=True,
+ name_contains=None,
+ metadata_equals=None,
+ metadata_not_equals=None,
+ folder_id=None,
+ root_only=True,
+ )
+
+
+@patch("backend.api.features.workspace.routes.get_or_create_workspace")
+@patch("backend.api.features.workspace.routes.WorkspaceManager")
+def test_list_files_rejects_session_id_with_folder_id(
+ mock_manager_cls, mock_get_workspace
+):
+ """session_id and folder_id are mutually exclusive axes — reject with 400."""
+ mock_get_workspace.return_value = _make_workspace()
+ mock_instance = AsyncMock()
+ mock_manager_cls.return_value = mock_instance
+
+ response = client.get("/files?session_id=sess-1&folder_id=fld-1")
+ assert response.status_code == 400
+ mock_instance.list_files.assert_not_called()
+
+
+@patch("backend.api.features.workspace.routes.get_or_create_workspace")
+@patch("backend.api.features.workspace.routes.WorkspaceManager")
+def test_list_files_rejects_session_id_with_root_only(
+ mock_manager_cls, mock_get_workspace
+):
+ """session_id and root_only are mutually exclusive axes — reject with 400."""
+ mock_get_workspace.return_value = _make_workspace()
+ mock_instance = AsyncMock()
+ mock_manager_cls.return_value = mock_instance
+
+ response = client.get("/files?session_id=sess-1&root_only=true")
+ assert response.status_code == 400
+ mock_instance.list_files.assert_not_called()
+
+
+@patch("backend.api.features.workspace.routes.get_or_create_workspace")
+@patch("backend.api.features.workspace.routes.WorkspaceManager")
+def test_list_files_rejects_folder_id_with_root_only(
+ mock_manager_cls, mock_get_workspace
+):
+ """folder_id and root_only contradict each other — reject with 400."""
+ mock_get_workspace.return_value = _make_workspace()
+ mock_instance = AsyncMock()
+ mock_manager_cls.return_value = mock_instance
+
+ response = client.get("/files?folder_id=fld-1&root_only=true")
+ assert response.status_code == 400
+ mock_instance.list_files.assert_not_called()
+
+
+@patch("backend.api.features.workspace.routes.get_or_create_workspace")
+@patch("backend.api.features.workspace.routes.WorkspaceManager")
+def test_list_files_includes_folder_id_in_response(
+ mock_manager_cls, mock_get_workspace
+):
+ """The listed item exposes its folder_id so the UI knows membership."""
+ mock_get_workspace.return_value = _make_workspace()
+ mock_instance = AsyncMock()
+ mock_instance.list_files.return_value = [_make_file(id="f1", folder_id="fld-1")]
+ mock_manager_cls.return_value = mock_instance
+
+ response = client.get("/files")
+ assert response.status_code == 200
+ assert response.json()["files"][0]["folder_id"] == "fld-1"
+
+
def test_upload_virus_scan_infrastructure_error_returns_500(mocker):
"""VirusScanError (ClamAV outage) should return 500, not 409."""
from backend.api.features.store.exceptions import VirusScanError
diff --git a/autogpt_platform/backend/backend/api/rest_api.py b/autogpt_platform/backend/backend/api/rest_api.py
index 7472782b85..cf9d61e5c5 100644
--- a/autogpt_platform/backend/backend/api/rest_api.py
+++ b/autogpt_platform/backend/backend/api/rest_api.py
@@ -43,6 +43,7 @@ import backend.api.features.search.routes as search_routes
import backend.api.features.store.model
import backend.api.features.store.routes
import backend.api.features.v1
+import backend.api.features.workspace.folder_routes as workspace_folder_routes
import backend.api.features.workspace.routes as workspace_routes
import backend.data.block
import backend.data.db
@@ -423,6 +424,11 @@ app.include_router(
tags=["workspace"],
prefix="/api/workspace",
)
+app.include_router(
+ workspace_folder_routes.router,
+ tags=["workspace"],
+ prefix="/api/workspace",
+)
app.include_router(
mcp_routes.router,
tags=["v2", "mcp"],
diff --git a/autogpt_platform/backend/backend/data/workspace.py b/autogpt_platform/backend/backend/data/workspace.py
index 83f7ae65fe..122a966bc7 100644
--- a/autogpt_platform/backend/backend/data/workspace.py
+++ b/autogpt_platform/backend/backend/data/workspace.py
@@ -56,6 +56,7 @@ class WorkspaceFile(pydantic.BaseModel):
checksum: Optional[str] = None
is_deleted: bool = False
deleted_at: Optional[datetime] = None
+ folder_id: Optional[str] = None
metadata: dict = pydantic.Field(default_factory=dict)
@staticmethod
@@ -73,6 +74,7 @@ class WorkspaceFile(pydantic.BaseModel):
checksum=file.checksum,
is_deleted=file.isDeleted,
deleted_at=file.deletedAt,
+ folder_id=file.folderId,
metadata=file.metadata if isinstance(file.metadata, dict) else {},
)
@@ -258,6 +260,8 @@ async def list_workspace_files(
name_contains: Optional[str] = None,
metadata_equals: Optional[dict] = None,
metadata_not_equals: Optional[dict] = None,
+ folder_id: Optional[str] = None,
+ root_only: bool = False,
) -> list[WorkspaceFile]:
"""
List files in a workspace.
@@ -281,6 +285,9 @@ async def list_workspace_files(
equal this object. Used by the "Generated" filter. ``metadata``
is never SQL NULL (column default ``{}``), so whole-object
inequality is null-safe and covers untagged/legacy files.
+ folder_id: If set, only return files in this folder.
+ root_only: If True, only return root-level files (folderId IS NULL).
+ Ignored when ``folder_id`` is set.
Returns:
List of WorkspaceFile instances
@@ -290,6 +297,11 @@ async def list_workspace_files(
if not include_deleted:
where_clause["isDeleted"] = False
+ if folder_id:
+ where_clause["folderId"] = folder_id
+ elif root_only:
+ where_clause["folderId"] = None
+
if path_prefix:
# Normalize prefix
if not path_prefix.startswith("/"):
diff --git a/autogpt_platform/backend/backend/data/workspace_folder.py b/autogpt_platform/backend/backend/data/workspace_folder.py
new file mode 100644
index 0000000000..6b0570a395
--- /dev/null
+++ b/autogpt_platform/backend/backend/data/workspace_folder.py
@@ -0,0 +1,273 @@
+"""
+Database CRUD operations for User Workspace Folders.
+
+Folders are a purely DB-level organizational layer on top of workspace files —
+storage paths are unaffected. A file's membership is tracked by its ``folderId``
+(null = root). Mirrors the Library folder implementation.
+"""
+
+import logging
+from datetime import datetime
+from typing import Optional
+
+import pydantic
+from prisma.errors import UniqueViolationError
+from prisma.models import UserWorkspaceFile, UserWorkspaceFolder
+
+from backend.api.features.library.exceptions import FolderAlreadyExistsError
+from backend.data.db import transaction
+from backend.data.workspace import WorkspaceFile
+from backend.util.exceptions import NotFoundError
+
+logger = logging.getLogger(__name__)
+
+
+class WorkspaceFolder(pydantic.BaseModel):
+ """Pydantic model for UserWorkspaceFolder, safe for RPC transport."""
+
+ id: str
+ workspace_id: str
+ name: str
+ icon: Optional[str] = None
+ created_at: datetime
+ updated_at: datetime
+ file_count: int = 0
+
+ @staticmethod
+ def from_db(
+ folder: "UserWorkspaceFolder", file_count: int = 0
+ ) -> "WorkspaceFolder":
+ return WorkspaceFolder(
+ id=folder.id,
+ workspace_id=folder.workspaceId,
+ name=folder.name,
+ icon=folder.icon,
+ created_at=folder.createdAt,
+ updated_at=folder.updatedAt,
+ file_count=file_count,
+ )
+
+
+async def _file_count(workspace_id: str, folder_id: str) -> int:
+ """Live (non-deleted) file count for a single folder."""
+ return await UserWorkspaceFile.prisma().count(
+ where={
+ "folderId": folder_id,
+ "workspaceId": workspace_id,
+ "isDeleted": False,
+ },
+ )
+
+
+async def _file_counts(workspace_id: str, folder_ids: list[str]) -> dict[str, int]:
+ """Live file counts per folder in a single batched query.
+
+ Counts in SQL instead of hydrating every file row just to ``len()`` it, so
+ listing folders stays cheap regardless of how many files a workspace holds.
+ """
+ if not folder_ids:
+ return {}
+ rows = await UserWorkspaceFile.prisma().group_by(
+ by=["folderId"],
+ where={
+ "workspaceId": workspace_id,
+ "folderId": {"in": folder_ids},
+ "isDeleted": False,
+ },
+ count=True,
+ )
+ return {
+ row["folderId"]: int((row.get("_count") or {}).get("_all") or 0)
+ for row in rows
+ if row.get("folderId")
+ }
+
+
+async def _get_folder_record(
+ folder_id: str,
+ workspace_id: str,
+) -> "UserWorkspaceFolder":
+ """Fetch a workspace-scoped folder record or raise NotFoundError."""
+ folder = await UserWorkspaceFolder.prisma().find_first(
+ where={
+ "id": folder_id,
+ "workspaceId": workspace_id,
+ "isDeleted": False,
+ },
+ )
+ if not folder:
+ raise NotFoundError(f"Folder #{folder_id} not found")
+ return folder
+
+
+async def list_folders(workspace_id: str) -> list[WorkspaceFolder]:
+ """List non-deleted folders for a workspace (flat; v1 has no nesting)."""
+ folders = await UserWorkspaceFolder.prisma().find_many(
+ where={"workspaceId": workspace_id, "isDeleted": False},
+ order={"name": "asc"},
+ )
+ counts = await _file_counts(workspace_id, [f.id for f in folders])
+ return [WorkspaceFolder.from_db(f, file_count=counts.get(f.id, 0)) for f in folders]
+
+
+async def get_folder(folder_id: str, workspace_id: str) -> WorkspaceFolder:
+ """Get a single folder by ID, scoped to the workspace."""
+ folder = await _get_folder_record(folder_id, workspace_id)
+ count = await _file_count(workspace_id, folder_id)
+ return WorkspaceFolder.from_db(folder, file_count=count)
+
+
+async def _root_name_taken(
+ workspace_id: str,
+ name: str,
+ exclude_folder_id: Optional[str] = None,
+) -> bool:
+ """Whether a live root-level folder with this name already exists.
+
+ The DB unique constraint ``@@unique([workspaceId, parentId, name])`` does
+ not prevent duplicates at root: v1 folders always have ``parentId = NULL``
+ and Postgres treats NULLs as distinct, so the constraint never fires for
+ root folders. Guard the v1 (root) case explicitly here.
+ """
+ where: dict = {
+ "workspaceId": workspace_id,
+ "name": name,
+ "parentId": None,
+ "isDeleted": False,
+ }
+ if exclude_folder_id is not None:
+ where["id"] = {"not": exclude_folder_id}
+ return await UserWorkspaceFolder.prisma().find_first(where=where) is not None
+
+
+async def create_folder(
+ workspace_id: str,
+ name: str,
+ icon: Optional[str] = None,
+) -> WorkspaceFolder:
+ """Create a new root-level folder for the workspace."""
+ if await _root_name_taken(workspace_id, name):
+ raise FolderAlreadyExistsError("A folder with this name already exists")
+
+ create_data: dict = {
+ "name": name,
+ "Workspace": {"connect": {"id": workspace_id}},
+ }
+ if icon is not None:
+ create_data["icon"] = icon
+
+ try:
+ folder = await UserWorkspaceFolder.prisma().create(data=create_data)
+ except UniqueViolationError:
+ raise FolderAlreadyExistsError("A folder with this name already exists")
+
+ logger.info(f"Created workspace folder {folder.id} in workspace {workspace_id}")
+ return WorkspaceFolder.from_db(folder)
+
+
+async def update_folder(
+ folder_id: str,
+ workspace_id: str,
+ name: Optional[str] = None,
+ icon: Optional[str] = None,
+) -> WorkspaceFolder:
+ """Update a folder's name/icon."""
+ # update() uses where={"id": ...} without workspaceId — verify ownership first.
+ await _get_folder_record(folder_id, workspace_id)
+
+ if name is not None and await _root_name_taken(
+ workspace_id, name, exclude_folder_id=folder_id
+ ):
+ raise FolderAlreadyExistsError("A folder with this name already exists")
+
+ update_data: dict = {}
+ if name is not None:
+ update_data["name"] = name
+ if icon is not None:
+ update_data["icon"] = icon
+
+ if not update_data:
+ return await get_folder(folder_id, workspace_id)
+
+ # update_many (not update) so the write itself is guarded by isDeleted: a
+ # folder soft-deleted concurrently after the ownership check above must not
+ # be silently updated (and reported as a 200).
+ try:
+ updated_count = await UserWorkspaceFolder.prisma().update_many(
+ where={"id": folder_id, "isDeleted": False},
+ data=update_data,
+ )
+ except UniqueViolationError:
+ raise FolderAlreadyExistsError("A folder with this name already exists")
+
+ if updated_count == 0:
+ raise NotFoundError(f"Folder #{folder_id} not found")
+
+ # Re-read without an isDeleted filter so a delete racing in *after* a
+ # successful update doesn't turn it into a spurious 404.
+ refreshed = await UserWorkspaceFolder.prisma().find_first(
+ where={"id": folder_id},
+ )
+ if refreshed is None:
+ raise NotFoundError(f"Folder #{folder_id} not found")
+ count = await _file_count(workspace_id, folder_id)
+ return WorkspaceFolder.from_db(refreshed, file_count=count)
+
+
+async def delete_folder(folder_id: str, workspace_id: str) -> None:
+ """
+ Soft-delete a folder and return its files to root.
+
+ Files are reparented to root (``folderId = null``) in the same transaction
+ so they remain visible and are never orphaned behind a hidden folder.
+ """
+ await _get_folder_record(folder_id, workspace_id)
+
+ async with transaction() as tx:
+ await UserWorkspaceFile.prisma(tx).update_many(
+ where={"folderId": folder_id, "workspaceId": workspace_id},
+ data={"folderId": None},
+ )
+ # update_many with an isDeleted guard so a concurrent delete that slips
+ # past the ownership check above is a no-op rather than re-deleting a
+ # logically-deleted row (TOCTOU-safe, idempotent).
+ await UserWorkspaceFolder.prisma(tx).update_many(
+ where={"id": folder_id, "isDeleted": False},
+ data={"isDeleted": True},
+ )
+
+ logger.info(f"Soft-deleted workspace folder {folder_id}; files moved to root")
+
+
+async def bulk_move_files_to_folder(
+ workspace_id: str,
+ file_ids: list[str],
+ folder_id: Optional[str],
+) -> list[WorkspaceFile]:
+ """
+ Move multiple files into a folder (or to root when ``folder_id`` is None).
+
+ Only files belonging to this workspace are updated; the target folder must
+ belong to the workspace too. Cross-workspace IDs are silently dropped.
+ """
+ # folderId is set directly; the FK only checks existence, not ownership.
+ if folder_id:
+ await _get_folder_record(folder_id, workspace_id)
+
+ if not file_ids:
+ return []
+
+ # Move and read back in one transaction so the returned list reflects
+ # exactly what this call moved, even under concurrent writes.
+ scope: dict = {
+ "id": {"in": file_ids},
+ "workspaceId": workspace_id,
+ "isDeleted": False,
+ }
+ async with transaction() as tx:
+ await UserWorkspaceFile.prisma(tx).update_many(
+ where=scope,
+ data={"folderId": folder_id},
+ )
+ files = await UserWorkspaceFile.prisma(tx).find_many(where=scope)
+ return [WorkspaceFile.from_db(f) for f in files]
diff --git a/autogpt_platform/backend/backend/data/workspace_folder_test.py b/autogpt_platform/backend/backend/data/workspace_folder_test.py
new file mode 100644
index 0000000000..1b1ad25117
--- /dev/null
+++ b/autogpt_platform/backend/backend/data/workspace_folder_test.py
@@ -0,0 +1,203 @@
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+
+import pytest
+
+from backend.api.features.library.exceptions import FolderAlreadyExistsError
+from backend.data import workspace_folder as wf
+from backend.util.exceptions import NotFoundError
+
+
+def _folder_record(**overrides):
+ """A lightweight stand-in for a Prisma UserWorkspaceFolder record."""
+
+ class _Rec:
+ pass
+
+ rec = _Rec()
+ rec.id = overrides.get("id", "fld-1")
+ rec.workspaceId = overrides.get("workspaceId", "ws-001")
+ rec.name = overrides.get("name", "Reports")
+ rec.icon = overrides.get("icon", None)
+ rec.createdAt = datetime(2026, 1, 1, tzinfo=timezone.utc)
+ rec.updatedAt = datetime(2026, 1, 1, tzinfo=timezone.utc)
+ rec.Files = overrides.get("Files", [])
+ return rec
+
+
+async def test_delete_folder_reparents_files_then_soft_deletes(mocker):
+ """Files must be moved to root BEFORE the folder is soft-deleted, in one tx."""
+ mocker.patch.object(
+ wf,
+ "_get_folder_record",
+ mocker.AsyncMock(return_value=_folder_record()),
+ )
+
+ calls: list[str] = []
+
+ file_prisma = mocker.MagicMock()
+ file_prisma.update_many = mocker.AsyncMock(
+ side_effect=lambda *a, **k: calls.append("reparent_files")
+ )
+ folder_prisma = mocker.MagicMock()
+ folder_prisma.update_many = mocker.AsyncMock(
+ side_effect=lambda *a, **k: calls.append("soft_delete_folder")
+ )
+
+ mocker.patch.object(
+ wf.UserWorkspaceFile, "prisma", mocker.MagicMock(return_value=file_prisma)
+ )
+ mocker.patch.object(
+ wf.UserWorkspaceFolder, "prisma", mocker.MagicMock(return_value=folder_prisma)
+ )
+
+ @asynccontextmanager
+ async def _fake_tx(*args, **kwargs):
+ yield None
+
+ mocker.patch.object(wf, "transaction", _fake_tx)
+
+ await wf.delete_folder("fld-1", "ws-001")
+
+ assert calls == ["reparent_files", "soft_delete_folder"]
+ # Files reparented to root (folderId=None) scoped to the workspace.
+ _, kwargs = file_prisma.update_many.call_args
+ assert kwargs["where"] == {"folderId": "fld-1", "workspaceId": "ws-001"}
+ assert kwargs["data"] == {"folderId": None}
+ # Folder soft-deleted (not hard-deleted) with a TOCTOU-safe isDeleted guard.
+ _, kwargs = folder_prisma.update_many.call_args
+ assert kwargs["where"] == {"id": "fld-1", "isDeleted": False}
+ assert kwargs["data"] == {"isDeleted": True}
+
+
+async def test_create_folder_rejects_duplicate_root_name(mocker):
+ """Duplicate root-level names are rejected in-app (NULL parentId defeats
+ the DB unique constraint)."""
+ folder_prisma = mocker.MagicMock()
+ folder_prisma.find_first = mocker.AsyncMock(return_value=_folder_record())
+ folder_prisma.create = mocker.AsyncMock()
+ mocker.patch.object(
+ wf.UserWorkspaceFolder, "prisma", mocker.MagicMock(return_value=folder_prisma)
+ )
+
+ with pytest.raises(FolderAlreadyExistsError):
+ await wf.create_folder("ws-001", "Reports")
+
+ folder_prisma.create.assert_not_awaited()
+ _, kwargs = folder_prisma.find_first.call_args
+ assert kwargs["where"] == {
+ "workspaceId": "ws-001",
+ "name": "Reports",
+ "parentId": None,
+ "isDeleted": False,
+ }
+
+
+async def test_update_folder_rejects_duplicate_root_name(mocker):
+ """Renaming onto an existing root-level name is rejected, excluding self."""
+ mocker.patch.object(
+ wf, "_get_folder_record", mocker.AsyncMock(return_value=_folder_record())
+ )
+ folder_prisma = mocker.MagicMock()
+ folder_prisma.find_first = mocker.AsyncMock(return_value=_folder_record(id="fld-2"))
+ folder_prisma.update = mocker.AsyncMock()
+ mocker.patch.object(
+ wf.UserWorkspaceFolder, "prisma", mocker.MagicMock(return_value=folder_prisma)
+ )
+
+ with pytest.raises(FolderAlreadyExistsError):
+ await wf.update_folder("fld-1", "ws-001", name="Reports")
+
+ folder_prisma.update.assert_not_awaited()
+ _, kwargs = folder_prisma.find_first.call_args
+ assert kwargs["where"]["id"] == {"not": "fld-1"}
+
+
+async def test_update_folder_raises_when_concurrently_deleted(mocker):
+ """A folder soft-deleted between the ownership check and the write must
+ surface NotFoundError, not a false 200 on a logically-deleted row."""
+ mocker.patch.object(
+ wf, "_get_folder_record", mocker.AsyncMock(return_value=_folder_record())
+ )
+ folder_prisma = mocker.MagicMock()
+ folder_prisma.find_first = mocker.AsyncMock(return_value=None) # no name dup
+ folder_prisma.update_many = mocker.AsyncMock(return_value=0) # nothing matched
+ mocker.patch.object(
+ wf.UserWorkspaceFolder, "prisma", mocker.MagicMock(return_value=folder_prisma)
+ )
+
+ with pytest.raises(NotFoundError):
+ await wf.update_folder("fld-1", "ws-001", name="Renamed")
+
+ _, kwargs = folder_prisma.update_many.call_args
+ assert kwargs["where"] == {"id": "fld-1", "isDeleted": False}
+
+
+async def test_bulk_move_validates_target_folder_ownership(mocker):
+ """A non-null target folder must be verified against the workspace."""
+ guard = mocker.patch.object(
+ wf, "_get_folder_record", mocker.AsyncMock(return_value=_folder_record())
+ )
+ file_prisma = mocker.MagicMock()
+ file_prisma.update_many = mocker.AsyncMock()
+ file_prisma.find_many = mocker.AsyncMock(return_value=[])
+ mocker.patch.object(
+ wf.UserWorkspaceFile, "prisma", mocker.MagicMock(return_value=file_prisma)
+ )
+
+ @asynccontextmanager
+ async def _fake_tx(*args, **kwargs):
+ yield None
+
+ mocker.patch.object(wf, "transaction", _fake_tx)
+
+ await wf.bulk_move_files_to_folder("ws-001", ["f1"], "fld-1")
+
+ guard.assert_awaited_once_with("fld-1", "ws-001")
+ _, kwargs = file_prisma.update_many.call_args
+ assert kwargs["data"] == {"folderId": "fld-1"}
+ assert kwargs["where"]["workspaceId"] == "ws-001"
+
+
+async def test_bulk_move_to_root_skips_folder_lookup(mocker):
+ """Moving to root (folder_id=None) must not require a folder lookup."""
+ guard = mocker.patch.object(wf, "_get_folder_record", mocker.AsyncMock())
+ file_prisma = mocker.MagicMock()
+ file_prisma.update_many = mocker.AsyncMock()
+ file_prisma.find_many = mocker.AsyncMock(return_value=[])
+ mocker.patch.object(
+ wf.UserWorkspaceFile, "prisma", mocker.MagicMock(return_value=file_prisma)
+ )
+
+ @asynccontextmanager
+ async def _fake_tx(*args, **kwargs):
+ yield None
+
+ mocker.patch.object(wf, "transaction", _fake_tx)
+
+ await wf.bulk_move_files_to_folder("ws-001", ["f1"], None)
+
+ guard.assert_not_awaited()
+ _, kwargs = file_prisma.update_many.call_args
+ assert kwargs["data"] == {"folderId": None}
+
+
+async def test_bulk_move_empty_file_ids_noop(mocker):
+ """Empty file list returns immediately without touching the DB."""
+ file_prisma = mocker.MagicMock()
+ file_prisma.update_many = mocker.AsyncMock()
+ mocker.patch.object(
+ wf.UserWorkspaceFile, "prisma", mocker.MagicMock(return_value=file_prisma)
+ )
+
+ result = await wf.bulk_move_files_to_folder("ws-001", [], None)
+
+ assert result == []
+ file_prisma.update_many.assert_not_awaited()
diff --git a/autogpt_platform/backend/backend/util/workspace.py b/autogpt_platform/backend/backend/util/workspace.py
index 3346a31e7f..681d5ffd19 100644
--- a/autogpt_platform/backend/backend/util/workspace.py
+++ b/autogpt_platform/backend/backend/util/workspace.py
@@ -353,6 +353,8 @@ class WorkspaceManager:
path_not_starts_with: Optional[str] = None,
metadata_equals: Optional[dict] = None,
metadata_not_equals: Optional[dict] = None,
+ folder_id: Optional[str] = None,
+ root_only: bool = False,
) -> list[WorkspaceFile]:
"""
List files in workspace.
@@ -375,6 +377,8 @@ class WorkspaceManager:
exactly (Artifacts "Uploaded" filter).
metadata_not_equals: Match files whose ``metadata`` does not equal
this object (Artifacts "Generated" filter).
+ folder_id: If set, only return files in this folder.
+ root_only: If True, only return root-level files (folderId IS NULL).
Returns:
List of WorkspaceFile instances
@@ -391,6 +395,8 @@ class WorkspaceManager:
name_contains=name_contains,
metadata_equals=metadata_equals,
metadata_not_equals=metadata_not_equals,
+ folder_id=folder_id,
+ root_only=root_only,
)
async def delete_file(self, file_id: str) -> bool:
diff --git a/autogpt_platform/backend/migrations/20260615120000_add_user_workspace_folders/migration.sql b/autogpt_platform/backend/migrations/20260615120000_add_user_workspace_folders/migration.sql
new file mode 100644
index 0000000000..4b2ef97228
--- /dev/null
+++ b/autogpt_platform/backend/migrations/20260615120000_add_user_workspace_folders/migration.sql
@@ -0,0 +1,40 @@
+-- AlterTable
+ALTER TABLE "UserWorkspaceFile" ADD COLUMN "folderId" TEXT;
+
+-- CreateTable
+CREATE TABLE "UserWorkspaceFolder" (
+ "id" TEXT NOT NULL,
+ "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ "updatedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ "workspaceId" TEXT NOT NULL,
+ "name" TEXT NOT NULL,
+ "icon" TEXT,
+ "parentId" TEXT,
+ "isDeleted" BOOLEAN NOT NULL DEFAULT false,
+
+ CONSTRAINT "UserWorkspaceFolder_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "UserWorkspaceFolder_workspaceId_isDeleted_idx" ON "UserWorkspaceFolder"("workspaceId", "isDeleted");
+
+-- CreateIndex
+CREATE UNIQUE INDEX "UserWorkspaceFolder_workspaceId_parentId_name_key" ON "UserWorkspaceFolder"("workspaceId", "parentId", "name");
+
+-- Root folders have parentId = NULL; Postgres treats NULLs as distinct, so the
+-- composite unique index above does not constrain them. Enforce unique names
+-- among live root folders so concurrent creates/renames can't duplicate
+-- (race-safe backstop for the application-level check).
+CREATE UNIQUE INDEX "UserWorkspaceFolder_workspaceId_name_root_key" ON "UserWorkspaceFolder"("workspaceId", "name") WHERE "parentId" IS NULL AND "isDeleted" = false;
+
+-- CreateIndex
+CREATE INDEX "UserWorkspaceFile_folderId_idx" ON "UserWorkspaceFile"("folderId");
+
+-- AddForeignKey
+ALTER TABLE "UserWorkspaceFile" ADD CONSTRAINT "UserWorkspaceFile_folderId_fkey" FOREIGN KEY ("folderId") REFERENCES "UserWorkspaceFolder"("id") ON DELETE SET NULL ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "UserWorkspaceFolder" ADD CONSTRAINT "UserWorkspaceFolder_workspaceId_fkey" FOREIGN KEY ("workspaceId") REFERENCES "UserWorkspace"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "UserWorkspaceFolder" ADD CONSTRAINT "UserWorkspaceFolder_parentId_fkey" FOREIGN KEY ("parentId") REFERENCES "UserWorkspaceFolder"("id") ON DELETE CASCADE ON UPDATE CASCADE;
diff --git a/autogpt_platform/backend/schema.prisma b/autogpt_platform/backend/schema.prisma
index 49113ef819..65d0de56dc 100644
--- a/autogpt_platform/backend/schema.prisma
+++ b/autogpt_platform/backend/schema.prisma
@@ -177,7 +177,8 @@ model UserWorkspace {
userId String @unique
User User @relation(fields: [userId], references: [id], onDelete: Cascade)
- Files UserWorkspaceFile[]
+ Files UserWorkspaceFile[]
+ Folders UserWorkspaceFolder[]
@@index([userId])
}
@@ -205,11 +206,43 @@ model UserWorkspaceFile {
metadata Json @default("{}")
+ // User-level organization. Null = root. The folder API soft-deletes
+ // folders and reparents files to root; SetNull is a hard-delete safety net.
+ folderId String?
+ Folder UserWorkspaceFolder? @relation(fields: [folderId], references: [id], onDelete: SetNull)
+
SharedExecutionFiles SharedExecutionFile[]
SharedChatFiles SharedChatFile[]
@@unique([workspaceId, path])
@@index([workspaceId, isDeleted])
+ @@index([folderId])
+}
+
+// User-created folder for organizing workspace files. Purely a DB-level
+// organizational layer — storage paths are unaffected. Mirrors LibraryFolder.
+model UserWorkspaceFolder {
+ id String @id @default(uuid())
+ createdAt DateTime @default(now())
+ updatedAt DateTime @default(now()) @updatedAt
+
+ workspaceId String
+ Workspace UserWorkspace @relation(fields: [workspaceId], references: [id], onDelete: Cascade)
+
+ name String
+ icon String?
+
+ // Forward-compat for nesting; unused by the v1 API (always null).
+ parentId String?
+ Parent UserWorkspaceFolder? @relation("WorkspaceFolderHierarchy", fields: [parentId], references: [id], onDelete: Cascade)
+ Children UserWorkspaceFolder[] @relation("WorkspaceFolderHierarchy")
+
+ isDeleted Boolean @default(false)
+
+ Files UserWorkspaceFile[]
+
+ @@unique([workspaceId, parentId, name])
+ @@index([workspaceId, isDeleted])
}
// Tracks which workspace files are exposed via a shared execution.
diff --git a/autogpt_platform/frontend/src/app/(platform)/PaywallGate/__tests__/PaywallModal.test.tsx b/autogpt_platform/frontend/src/app/(platform)/PaywallGate/__tests__/PaywallModal.test.tsx
index 8e363482d6..751476e94b 100644
--- a/autogpt_platform/frontend/src/app/(platform)/PaywallGate/__tests__/PaywallModal.test.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/PaywallGate/__tests__/PaywallModal.test.tsx
@@ -118,8 +118,12 @@ function setupMocks({
return { mutateFn, refetchFn };
}
-afterEach(() => {
+afterEach(async () => {
cleanup();
+ // Flush in-flight async work (e.g. a redirect from a rejected upgrade
+ // mutation) before clearing mocks, so a late router.replace from one test
+ // can't leak into the next and trip its "not redirected" assertion.
+ await new Promise((resolve) => setTimeout(resolve, 0));
vi.clearAllMocks();
});
diff --git a/autogpt_platform/frontend/src/app/(platform)/artifacts/__tests__/folders.test.tsx b/autogpt_platform/frontend/src/app/(platform)/artifacts/__tests__/folders.test.tsx
new file mode 100644
index 0000000000..c61da98a9b
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/artifacts/__tests__/folders.test.tsx
@@ -0,0 +1,455 @@
+import { describe, expect, test, vi } from "vitest";
+
+import {
+ fireEvent,
+ render,
+ screen,
+ waitFor,
+} from "@/tests/integrations/test-utils";
+import { server } from "@/mocks/mock-server";
+import { http, HttpResponse } from "msw";
+import {
+ getGetWorkspaceStorageUsageMockHandler,
+ getListWorkspaceFilesMockHandler,
+ getListWorkspaceFoldersMockHandler,
+} from "@/app/api/__generated__/endpoints/workspace/workspace.msw";
+import type { WorkspaceFileItem } from "@/app/api/__generated__/models/workspaceFileItem";
+import type { WorkspaceFolder } from "@/app/api/__generated__/models/workspaceFolder";
+import { FILE_DRAG_MIME } from "../components/WorkspaceFolders/drag";
+
+vi.mock("@/services/feature-flags/use-get-flag", () => ({
+ Flag: { ARTIFACTS_PAGE: "artifacts-page" },
+ useGetFlag: () => true,
+ useFlagStatus: () => ({ enabled: true, ready: true }),
+}));
+
+vi.mock("next/navigation", () => ({
+ useRouter: () => ({
+ push: vi.fn(),
+ replace: vi.fn(),
+ prefetch: vi.fn(),
+ back: vi.fn(),
+ forward: vi.fn(),
+ refresh: vi.fn(),
+ }),
+ usePathname: () => "/artifacts",
+ useSearchParams: () => new URLSearchParams(),
+ useParams: () => ({}),
+ notFound: () => {
+ throw new Error("NEXT_NOT_FOUND");
+ },
+}));
+
+vi.mock("framer-motion", async (importActual) => {
+ const actual = await importActual<typeof import("framer-motion")>();
+ return { ...actual, useReducedMotion: () => true };
+});
+
+import ArtifactsPage from "../page";
+
+const PROXY = "/api/proxy/api/workspace";
+
+function makeFile(
+ overrides: Partial<WorkspaceFileItem> = {},
+): WorkspaceFileItem {
+ return {
+ id: "file-base",
+ name: "base.txt",
+ path: "/base.txt",
+ mime_type: "text/plain",
+ size_bytes: 1024,
+ folder_id: null,
+ metadata: {},
+ origin: "generated",
+ created_at: "2026-05-01T00:00:00Z",
+ ...overrides,
+ };
+}
+
+function makeFolder(overrides: Partial<WorkspaceFolder> = {}): WorkspaceFolder {
+ return {
+ id: "fld-1",
+ workspace_id: "ws-1",
+ name: "Reports",
+ file_count: 2,
+ created_at: "2026-05-01T00:00:00Z" as unknown as Date,
+ updated_at: "2026-05-01T00:00:00Z" as unknown as Date,
+ ...overrides,
+ };
+}
+
+function useStorageHandler() {
+ server.use(
+ getGetWorkspaceStorageUsageMockHandler({
+ used_bytes: 0,
+ limit_bytes: 1_000_000_000,
+ used_percent: 0,
+ file_count: 0,
+ }),
+ );
+}
+
+describe("ArtifactsPage - folders", () => {
+ test("renders folders at the root with file counts", async () => {
+ useStorageHandler();
+ server.use(
+ getListWorkspaceFilesMockHandler({
+ files: [],
+ offset: 0,
+ has_more: false,
+ }),
+ getListWorkspaceFoldersMockHandler({
+ folders: [makeFolder({ name: "Reports", file_count: 2 })],
+ }),
+ );
+
+ render(<ArtifactsPage />);
+
+ expect(await screen.findByTestId("workspace-folders")).toBeDefined();
+ expect(await screen.findByText("Reports")).toBeDefined();
+ expect(screen.getByText("2 files")).toBeDefined();
+ });
+
+ test("selecting a folder scopes the list and shows a breadcrumb", async () => {
+ useStorageHandler();
+ server.use(
+ getListWorkspaceFoldersMockHandler({
+ folders: [makeFolder({ id: "fld-1", name: "Reports" })],
+ }),
+ // Branch on folder_id: root shows root.txt, folder shows inside.txt.
+ http.get(`${PROXY}/files`, ({ request }) => {
+ const url = new URL(request.url);
+ const inFolder = url.searchParams.get("folder_id") === "fld-1";
+ return HttpResponse.json({
+ files: [
+ inFolder
+ ? makeFile({ id: "f-in", name: "inside.txt", folder_id: "fld-1" })
+ : makeFile({ id: "f-root", name: "root.txt" }),
+ ],
+ offset: 0,
+ has_more: false,
+ });
+ }),
+ );
+
+ render(<ArtifactsPage />);
+
+ expect(await screen.findByText("root.txt")).toBeDefined();
+
+ fireEvent.click(await screen.findByTestId("workspace-folder"));
+
+ expect(await screen.findByTestId("folder-breadcrumb")).toBeDefined();
+ expect(await screen.findByText("inside.txt")).toBeDefined();
+
+ // Back to root via breadcrumb.
+ fireEvent.click(screen.getByTestId("folder-breadcrumb-root"));
+ expect(await screen.findByText("root.txt")).toBeDefined();
+ });
+
+ test("creating a folder posts to the create endpoint", async () => {
+ useStorageHandler();
+ let createdName: string | null = null;
+ server.use(
+ getListWorkspaceFilesMockHandler({
+ files: [],
+ offset: 0,
+ has_more: false,
+ }),
+ getListWorkspaceFoldersMockHandler({ folders: [] }),
+ http.post(`${PROXY}/folders`, async ({ request }) => {
+ const body = (await request.json()) as { name: string };
+ createdName = body.name;
+ return HttpResponse.json(makeFolder({ name: body.name }), {
+ status: 201,
+ });
+ }),
+ );
+
+ render(<ArtifactsPage />);
+
+ fireEvent.click(await screen.findByTestId("create-folder-button"));
+ fireEvent.change(screen.getByLabelText(/folder name/i), {
+ target: { value: "Invoices" },
+ });
+ fireEvent.click(screen.getByTestId("folder-form-submit"));
+
+ await waitFor(() => expect(createdName).toBe("Invoices"));
+ });
+
+ test("move-to-folder menu posts a bulk move", async () => {
+ useStorageHandler();
+ let movedTo: string | null | undefined;
+ server.use(
+ getListWorkspaceFilesMockHandler({
+ files: [makeFile({ id: "f1", name: "movable.txt" })],
+ offset: 0,
+ has_more: false,
+ }),
+ getListWorkspaceFoldersMockHandler({
+ folders: [makeFolder({ id: "fld-1", name: "Reports" })],
+ }),
+ http.post(`${PROXY}/folders/files/bulk-move`, async ({ request }) => {
+ const body = (await request.json()) as { folder_id: string | null };
+ movedTo = body.folder_id;
+ return HttpResponse.json([]);
+ }),
+ );
+
+ render(<ArtifactsPage />);
+
+ expect(await screen.findByText("movable.txt")).toBeDefined();
+ // Radix DropdownMenu opens on pointerdown, not click, under happy-dom.
+ fireEvent.pointerDown(screen.getByTestId("artifacts-card-menu"), {
+ button: 0,
+ });
+ fireEvent.click(await screen.findByTestId("artifacts-move-to-folder"));
+ fireEvent.click(await screen.findByTestId("move-to-folder-option"));
+
+ await waitFor(() => expect(movedTo).toBe("fld-1"));
+ });
+
+ test("renaming a folder patches the folder", async () => {
+ useStorageHandler();
+ let patchedName: string | null = null;
+ server.use(
+ getListWorkspaceFilesMockHandler({
+ files: [],
+ offset: 0,
+ has_more: false,
+ }),
+ getListWorkspaceFoldersMockHandler({
+ folders: [makeFolder({ id: "fld-1", name: "Reports" })],
+ }),
+ http.patch(`${PROXY}/folders/fld-1`, async ({ request }) => {
+ const body = (await request.json()) as { name?: string };
+ patchedName = body.name ?? null;
+ return HttpResponse.json(
+ makeFolder({ id: "fld-1", name: body.name ?? "Reports" }),
+ );
+ }),
+ );
+
+ render(<ArtifactsPage />);
+
+ fireEvent.click(await screen.findByLabelText("Rename folder"));
+ const input = await screen.findByLabelText(/folder name/i);
+ fireEvent.change(input, { target: { value: "Invoices" } });
+ // Submit via Enter to exercise the input's keydown handler.
+ fireEvent.keyDown(input, { key: "Enter" });
+
+ await waitFor(() => expect(patchedName).toBe("Invoices"));
+ });
+
+ test("deleting a folder calls the delete endpoint", async () => {
+ useStorageHandler();
+ let deleted = false;
+ server.use(
+ getListWorkspaceFilesMockHandler({
+ files: [],
+ offset: 0,
+ has_more: false,
+ }),
+ getListWorkspaceFoldersMockHandler({
+ folders: [makeFolder({ id: "fld-1", name: "Reports" })],
+ }),
+ http.delete(`${PROXY}/folders/fld-1`, () => {
+ deleted = true;
+ return new HttpResponse(null, { status: 204 });
+ }),
+ );
+
+ render(<ArtifactsPage />);
+
+ fireEvent.click(await screen.findByLabelText("Delete folder"));
+ fireEvent.click(await screen.findByTestId("confirm-delete-folder"));
+
+ await waitFor(() => expect(deleted).toBe(true));
+ });
+
+ test("move-to-folder offers root when the file is already in a folder", async () => {
+ useStorageHandler();
+ let movedTo: string | null | undefined;
+ server.use(
+ getListWorkspaceFilesMockHandler({
+ files: [
+ makeFile({ id: "f1", name: "movable.txt", folder_id: "fld-1" }),
+ ],
+ offset: 0,
+ has_more: false,
+ }),
+ getListWorkspaceFoldersMockHandler({
+ folders: [makeFolder({ id: "fld-1", name: "Reports" })],
+ }),
+ http.post(`${PROXY}/folders/files/bulk-move`, async ({ request }) => {
+ const body = (await request.json()) as { folder_id: string | null };
+ movedTo = body.folder_id;
+ return HttpResponse.json([]);
+ }),
+ );
+
+ render(<ArtifactsPage />);
+
+ expect(await screen.findByText("movable.txt")).toBeDefined();
+ fireEvent.pointerDown(screen.getByTestId("artifacts-card-menu"), {
+ button: 0,
+ });
+ fireEvent.click(await screen.findByTestId("artifacts-move-to-folder"));
+ fireEvent.click(await screen.findByTestId("move-to-root"));
+
+ await waitFor(() => expect(movedTo).toBeNull());
+ });
+
+ test("shows an error card when folders fail to load", async () => {
+ useStorageHandler();
+ server.use(
+ getListWorkspaceFilesMockHandler({
+ files: [],
+ offset: 0,
+ has_more: false,
+ }),
+ http.get(`${PROXY}/folders`, () =>
+ HttpResponse.json({ detail: "boom" }, { status: 500 }),
+ ),
+ );
+
+ render(<ArtifactsPage />);
+
+ expect(await screen.findByText(/something went wrong/i)).toBeDefined();
+ });
+
+ test("dragging a file onto a folder moves it", async () => {
+ useStorageHandler();
+ let movedTo: string | null | undefined;
+ server.use(
+ getListWorkspaceFilesMockHandler({
+ files: [makeFile({ id: "f1", name: "drag.txt" })],
+ offset: 0,
+ has_more: false,
+ }),
+ getListWorkspaceFoldersMockHandler({
+ folders: [makeFolder({ id: "fld-1", name: "Reports" })],
+ }),
+ http.post(`${PROXY}/folders/files/bulk-move`, async ({ request }) => {
+ const body = (await request.json()) as {
+ file_ids: string[];
+ folder_id: string | null;
+ };
+ movedTo = body.folder_id;
+ return HttpResponse.json([]);
+ }),
+ );
+
+ render(<ArtifactsPage />);
+
+ expect(await screen.findByText("drag.txt")).toBeDefined();
+
+ const store: Record<string, string> = {};
+ const dataTransfer = {
+ setData: (key: string, value: string) => {
+ store[key] = value;
+ },
+ getData: (key: string) => store[key] ?? "",
+ setDragImage: () => {},
+ get types() {
+ return Object.keys(store);
+ },
+ };
+
+ const card = screen.getByTestId("artifacts-list-item");
+ const folder = screen.getByTestId("workspace-folder");
+ fireEvent.dragStart(card, { dataTransfer });
+ fireEvent.dragOver(folder, { dataTransfer });
+ fireEvent.drop(folder, { dataTransfer });
+ fireEvent.dragEnd(card, { dataTransfer });
+
+ await waitFor(() => expect(movedTo).toBe("fld-1"));
+ expect(store[FILE_DRAG_MIME]).toBe("f1");
+ });
+
+ test("opening a folder with the keyboard scopes the list", async () => {
+ useStorageHandler();
+ server.use(
+ getListWorkspaceFoldersMockHandler({
+ folders: [makeFolder({ id: "fld-1", name: "Reports" })],
+ }),
+ http.get(`${PROXY}/files`, ({ request }) => {
+ const inFolder =
+ new URL(request.url).searchParams.get("folder_id") === "fld-1";
+ return HttpResponse.json({
+ files: [
+ inFolder
+ ? makeFile({ id: "f-in", name: "inside.txt", folder_id: "fld-1" })
+ : makeFile({ id: "f-root", name: "root.txt" }),
+ ],
+ offset: 0,
+ has_more: false,
+ });
+ }),
+ );
+
+ render(<ArtifactsPage />);
+
+ expect(await screen.findByText("root.txt")).toBeDefined();
+ fireEvent.keyDown(await screen.findByTestId("workspace-folder"), {
+ key: "Enter",
+ });
+ expect(await screen.findByText("inside.txt")).toBeDefined();
+ });
+
+ test("create failure keeps the dialog open and toasts", async () => {
+ useStorageHandler();
+ server.use(
+ getListWorkspaceFilesMockHandler({
+ files: [],
+ offset: 0,
+ has_more: false,
+ }),
+ getListWorkspaceFoldersMockHandler({ folders: [] }),
+ http.post(`${PROXY}/folders`, () =>
+ HttpResponse.json({ detail: "exists" }, { status: 409 }),
+ ),
+ );
+
+ render(<ArtifactsPage />);
+
+ fireEvent.click(await screen.findByTestId("create-folder-button"));
+ fireEvent.change(await screen.findByLabelText(/folder name/i), {
+ target: { value: "Dupe" },
+ });
+ fireEvent.click(screen.getByTestId("folder-form-submit"));
+
+ // Dialog stays open on error (submit button still present).
+ await waitFor(() =>
+ expect(screen.getByTestId("folder-form-submit")).toBeDefined(),
+ );
+ });
+
+ test("cancelling the delete dialog closes it without deleting", async () => {
+ useStorageHandler();
+ let deleteCalled = false;
+ server.use(
+ getListWorkspaceFilesMockHandler({
+ files: [],
+ offset: 0,
+ has_more: false,
+ }),
+ getListWorkspaceFoldersMockHandler({
+ folders: [makeFolder({ id: "fld-1", name: "Reports" })],
+ }),
+ http.delete(`${PROXY}/folders/fld-1`, () => {
+ deleteCalled = true;
+ return new HttpResponse(null, { status: 204 });
+ }),
+ );
+
+ render(<ArtifactsPage />);
+
+ fireEvent.click(await screen.findByLabelText("Delete folder"));
+ fireEvent.click(await screen.findByRole("button", { name: /cancel/i }));
+
+ await waitFor(() =>
+ expect(screen.queryByTestId("confirm-delete-folder")).toBeNull(),
+ );
+ expect(deleteCalled).toBe(false);
+ });
+});
diff --git a/autogpt_platform/frontend/src/app/(platform)/artifacts/__tests__/main.test.tsx b/autogpt_platform/frontend/src/app/(platform)/artifacts/__tests__/main.test.tsx
index 5236e36760..52f1323012 100644
--- a/autogpt_platform/frontend/src/app/(platform)/artifacts/__tests__/main.test.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/artifacts/__tests__/main.test.tsx
@@ -1,6 +1,11 @@
import { describe, expect, test, vi } from "vitest";
-import { fireEvent, render, screen } from "@/tests/integrations/test-utils";
+import {
+ fireEvent,
+ render,
+ screen,
+ waitFor,
+} from "@/tests/integrations/test-utils";
import { server } from "@/mocks/mock-server";
import { http, HttpResponse } from "msw";
import {
@@ -183,6 +188,30 @@ describe("ArtifactsPage - search filter", () => {
// Wait for the filtered list to appear (debounced ~250ms).
expect(await screen.findByText("beta.txt")).toBeDefined();
});
+
+ test("searching at root spans folders instead of forcing root_only", async () => {
+ useStorageHandler();
+ const rootOnlyParams: (string | null)[] = [];
+ server.use(
+ http.get("/api/proxy/api/workspace/files", ({ request }) => {
+ rootOnlyParams.push(new URL(request.url).searchParams.get("root_only"));
+ return HttpResponse.json({ files: [], offset: 0, has_more: false });
+ }),
+ );
+
+ render(<ArtifactsPage />);
+
+ // Initial root listing is scoped to root-level files.
+ await waitFor(() => expect(rootOnlyParams).toContain("true"));
+
+ const search = screen.getByPlaceholderText(/search/i);
+ fireEvent.change(search, { target: { value: "beta" } });
+
+ // A global search must not be limited to root — files inside folders count.
+ await waitFor(() => {
+ expect(rootOnlyParams[rootOnlyParams.length - 1]).toBe("false");
+ });
+ });
});
describe("ArtifactsPage - feature flag gating", () => {
diff --git a/autogpt_platform/frontend/src/app/(platform)/artifacts/components/ArtifactsList/ArtifactCard/ArtifactCard.tsx b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/ArtifactsList/ArtifactCard/ArtifactCard.tsx
index d467eb0bdc..c8aa630cb6 100644
--- a/autogpt_platform/frontend/src/app/(platform)/artifacts/components/ArtifactsList/ArtifactCard/ArtifactCard.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/ArtifactsList/ArtifactCard/ArtifactCard.tsx
@@ -17,13 +17,19 @@ import {
CircleNotchIcon,
DotsThreeIcon,
DownloadSimpleIcon,
+ FolderIcon,
TrashIcon,
} from "@phosphor-icons/react";
import { useQueryClient } from "@tanstack/react-query";
import { motion, useReducedMotion } from "framer-motion";
import type { Variants } from "framer-motion";
import Link from "next/link";
-import { useState } from "react";
+import { useEffect, useRef, useState } from "react";
+import { MoveToFolderDialog } from "../../MoveToFolderDialog/MoveToFolderDialog";
+import {
+ createFileDragImage,
+ FILE_DRAG_MIME,
+} from "../../WorkspaceFolders/drag";
import {
deriveFileOrigin,
downloadFileBlob,
@@ -60,6 +66,32 @@ export function ArtifactCard({ file, onOpen }: Props) {
const goLabel = origin.kind === "session" ? "Open chat" : "Open in Builder";
const TypeIcon = getFileTypeIcon(file.mime_type, file.name);
const reduceMotion = useReducedMotion();
+ const [isMoveOpen, setIsMoveOpen] = useState(false);
+ const dragImageRef = useRef<HTMLElement | null>(null);
+
+ // Clean up a leftover drag-image node if the card unmounts mid-drag (before
+ // dragend fires), so the off-screen element isn't leaked into the DOM.
+ useEffect(() => {
+ return () => {
+ dragImageRef.current?.remove();
+ dragImageRef.current = null;
+ };
+ }, []);
+
+ function handleDragStart(e: React.DragEvent<HTMLLIElement>) {
+ dragImageRef.current?.remove();
+ e.dataTransfer.setData(FILE_DRAG_MIME, file.id);
+ e.dataTransfer.effectAllowed = "move";
+ const dragImage = createFileDragImage(file.name);
+ document.body.appendChild(dragImage);
+ e.dataTransfer.setDragImage(dragImage, 16, 16);
+ dragImageRef.current = dragImage;
+ }
+
+ function handleDragEnd() {
+ dragImageRef.current?.remove();
+ dragImageRef.current = null;
+ }
return (
<motion.li
@@ -67,6 +99,9 @@ export function ArtifactCard({ file, onOpen }: Props) {
style={{ willChange: "transform, opacity, filter" }}
className="group relative flex flex-col overflow-hidden rounded-2xl border border-zinc-200 bg-white transition-colors hover:border-zinc-300"
data-testid="artifacts-list-item"
+ draggable
+ onDragStartCapture={handleDragStart}
+ onDragEndCapture={handleDragEnd}
>
{/* Full-card click target: opening the file is the primary action.
Sits behind the content (z-0); the content is pointer-events-none so
@@ -101,10 +136,24 @@ export function ArtifactCard({ file, onOpen }: Props) {
</Text>
</div>
<div className="pointer-events-auto">
- <CardMenu file={file} goLabel={goLabel} goHref={origin.href} />
+ <CardMenu
+ file={file}
+ goLabel={goLabel}
+ goHref={origin.href}
+ onMove={() => setIsMoveOpen(true)}
+ />
</div>
</div>
</div>
+ {isMoveOpen && (
+ <MoveToFolderDialog
+ fileId={file.id}
+ fileName={file.name}
+ currentFolderId={file.folder_id}
+ isOpen={isMoveOpen}
+ setIsOpen={setIsMoveOpen}
+ />
+ )}
</motion.li>
);
}
@@ -113,10 +162,12 @@ function CardMenu({
file,
goLabel,
goHref,
+ onMove,
}: {
file: WorkspaceFileItem;
goLabel: string;
goHref: string;
+ onMove: () => void;
}) {
const [isDownloading, setIsDownloading] = useState(false);
const { toast } = useToast();
@@ -199,6 +250,16 @@ function CardMenu({
{goLabel}
</Link>
</DropdownMenuItem>
+ <DropdownMenuItem
+ onSelect={(e) => {
+ e.preventDefault();
+ onMove();
+ }}
+ data-testid="artifacts-move-to-folder"
+ >
+ <FolderIcon size={16} className="mr-2" />
+ Move to folder
+ </DropdownMenuItem>
<DropdownMenuSeparator />
<DropdownMenuItem
onSelect={(e) => {
diff --git a/autogpt_platform/frontend/src/app/(platform)/artifacts/components/MoveToFolderDialog/MoveToFolderDialog.tsx b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/MoveToFolderDialog/MoveToFolderDialog.tsx
new file mode 100644
index 0000000000..49bb69c6d2
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/MoveToFolderDialog/MoveToFolderDialog.tsx
@@ -0,0 +1,85 @@
+"use client";
+
+import { FolderIcon, HouseIcon } from "@phosphor-icons/react";
+import { Button } from "@/components/atoms/Button/Button";
+import { Text } from "@/components/atoms/Text/Text";
+import { Dialog } from "@/components/molecules/Dialog/Dialog";
+import { useArtifactsFolders } from "../../useArtifactsFolders";
+import { FOLDER_STYLE } from "../WorkspaceFolders/folder-constants";
+
+interface Props {
+ fileId: string;
+ fileName: string;
+ currentFolderId?: string | null;
+ isOpen: boolean;
+ setIsOpen: (open: boolean) => void;
+}
+
+export function MoveToFolderDialog({
+ fileId,
+ fileName,
+ currentFolderId,
+ isOpen,
+ setIsOpen,
+}: Props) {
+ const { folders, moveFileToFolder } = useArtifactsFolders();
+ const destinationFolders = folders.filter((f) => f.id !== currentFolderId);
+
+ function handleMove(folderId: string | null) {
+ // Close only on success; the hook toasts on error and we keep the dialog
+ // open so the user can retry without re-opening it.
+ moveFileToFolder({ fileId, folderId })
+ .then(() => setIsOpen(false))
+ .catch(() => {});
+ }
+
+ return (
+ <Dialog
+ controlled={{ isOpen, set: setIsOpen }}
+ styling={{ maxWidth: "28rem" }}
+ title="Move to folder"
+ >
+ <Dialog.Content>
+ <div className="flex flex-col gap-1">
+ <Text variant="small" className="mb-1 text-zinc-500">
+ Move &ldquo;{fileName}&rdquo; to:
+ </Text>
+ {currentFolderId != null && (
+ <Button
+ variant="ghost"
+ className="w-full justify-start gap-3 px-3 py-2.5"
+ onClick={() => handleMove(null)}
+ data-testid="move-to-root"
+ >
+ <HouseIcon size={18} className="text-zinc-500" />
+ <Text variant="small-medium">Files (root)</Text>
+ </Button>
+ )}
+ {destinationFolders.length === 0 ? (
+ <div className="flex h-20 items-center justify-center">
+ <Text variant="small" className="text-zinc-400">
+ {folders.length === 0 ? "No folders yet" : "No other folders"}
+ </Text>
+ </div>
+ ) : (
+ destinationFolders.map((folder) => {
+ const style = FOLDER_STYLE;
+ return (
+ <Button
+ key={folder.id}
+ variant="ghost"
+ className="w-full justify-start gap-3 px-3 py-2.5"
+ onClick={() => handleMove(folder.id)}
+ data-testid="move-to-folder-option"
+ >
+ <FolderIcon size={18} weight="fill" className={style.icon} />
+ <Text variant="small-medium">{folder.name}</Text>
+ </Button>
+ );
+ })
+ )}
+ </div>
+ </Dialog.Content>
+ </Dialog>
+ );
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/DeleteFolderDialog.tsx b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/DeleteFolderDialog.tsx
new file mode 100644
index 0000000000..1302687e42
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/DeleteFolderDialog.tsx
@@ -0,0 +1,57 @@
+"use client";
+
+import { Button } from "@/components/atoms/Button/Button";
+import { Text } from "@/components/atoms/Text/Text";
+import { Dialog } from "@/components/molecules/Dialog/Dialog";
+
+interface Props {
+ isOpen: boolean;
+ setIsOpen: (open: boolean) => void;
+ folderName: string;
+ isDeleting: boolean;
+ onConfirm: () => void;
+}
+
+export function DeleteFolderDialog({
+ isOpen,
+ setIsOpen,
+ folderName,
+ isDeleting,
+ onConfirm,
+}: Props) {
+ return (
+ <Dialog
+ controlled={{ isOpen, set: setIsOpen }}
+ styling={{ maxWidth: "28rem" }}
+ title="Delete folder"
+ >
+ <Dialog.Content>
+ <div className="flex flex-col gap-4">
+ <Text variant="body" className="text-zinc-600">
+ Delete{" "}
+ <span className="font-medium">&ldquo;{folderName}&rdquo;</span>?
+ Files inside it will be moved back to the root, not deleted.
+ </Text>
+ <div className="flex justify-end gap-2">
+ <Button
+ variant="secondary"
+ onClick={() => setIsOpen(false)}
+ disabled={isDeleting}
+ >
+ Cancel
+ </Button>
+ <Button
+ variant="destructive"
+ onClick={onConfirm}
+ loading={isDeleting}
+ disabled={isDeleting}
+ data-testid="confirm-delete-folder"
+ >
+ Delete
+ </Button>
+ </div>
+ </div>
+ </Dialog.Content>
+ </Dialog>
+ );
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/FolderBreadcrumb.tsx b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/FolderBreadcrumb.tsx
new file mode 100644
index 0000000000..e309e182c2
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/FolderBreadcrumb.tsx
@@ -0,0 +1,35 @@
+"use client";
+
+import { CaretRightIcon, HouseIcon } from "@phosphor-icons/react";
+import { Text } from "@/components/atoms/Text/Text";
+
+interface Props {
+ folderName: string;
+ onBack: () => void;
+}
+
+export function FolderBreadcrumb({ folderName, onBack }: Props) {
+ return (
+ <nav
+ className="flex items-center gap-1.5 text-zinc-500"
+ aria-label="Breadcrumb"
+ data-testid="folder-breadcrumb"
+ >
+ <button
+ type="button"
+ onClick={onBack}
+ className="inline-flex items-center gap-1.5 rounded-md px-1.5 py-1 hover:bg-zinc-100 hover:text-zinc-800"
+ data-testid="folder-breadcrumb-root"
+ >
+ <HouseIcon size={16} />
+ <Text variant="small-medium" as="span">
+ Files
+ </Text>
+ </button>
+ <CaretRightIcon size={14} className="text-zinc-400" />
+ <Text variant="small-medium" as="span" className="text-zinc-800">
+ {folderName}
+ </Text>
+ </nav>
+ );
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/FolderFormDialog.tsx b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/FolderFormDialog.tsx
new file mode 100644
index 0000000000..2edf5af94f
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/FolderFormDialog.tsx
@@ -0,0 +1,76 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { Button } from "@/components/atoms/Button/Button";
+import { Input } from "@/components/atoms/Input/Input";
+import { Dialog } from "@/components/molecules/Dialog/Dialog";
+
+interface Props {
+ isOpen: boolean;
+ setIsOpen: (open: boolean) => void;
+ mode: "create" | "edit";
+ initialName?: string;
+ isSubmitting: boolean;
+ onSubmit: (values: { name: string }) => void;
+}
+
+export function FolderFormDialog({
+ isOpen,
+ setIsOpen,
+ mode,
+ initialName = "",
+ isSubmitting,
+ onSubmit,
+}: Props) {
+ const [name, setName] = useState(initialName);
+
+ useEffect(() => {
+ if (isOpen) {
+ setName(initialName);
+ }
+ }, [isOpen, initialName]);
+
+ const trimmed = name.trim();
+ const canSubmit =
+ trimmed.length > 0 && trimmed.length <= 100 && !isSubmitting;
+
+ function handleSubmit() {
+ if (!canSubmit) return;
+ onSubmit({ name: trimmed });
+ }
+
+ return (
+ <Dialog
+ controlled={{ isOpen, set: setIsOpen }}
+ styling={{ maxWidth: "28rem" }}
+ title={mode === "create" ? "Create folder" : "Rename folder"}
+ >
+ <Dialog.Content>
+ <div className="flex flex-col gap-3">
+ <Input
+ id="folder-name"
+ label="Folder name"
+ placeholder="Enter folder name"
+ value={name}
+ onChange={(e) => setName(e.target.value)}
+ onKeyDown={(e) => {
+ if (e.key === "Enter") handleSubmit();
+ }}
+ className="w-full"
+ wrapperClassName="!mb-0"
+ />
+ <Button
+ variant="primary"
+ className="mt-2"
+ disabled={!canSubmit}
+ loading={isSubmitting}
+ onClick={handleSubmit}
+ data-testid="folder-form-submit"
+ >
+ {mode === "create" ? "Create" : "Save"}
+ </Button>
+ </div>
+ </Dialog.Content>
+ </Dialog>
+ );
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/WorkspaceFolder.tsx b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/WorkspaceFolder.tsx
new file mode 100644
index 0000000000..07958dc3cd
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/WorkspaceFolder.tsx
@@ -0,0 +1,120 @@
+"use client";
+
+import { useState } from "react";
+import { FolderIcon, PencilSimpleIcon, TrashIcon } from "@phosphor-icons/react";
+import { Button } from "@/components/atoms/Button/Button";
+import { Text } from "@/components/atoms/Text/Text";
+import { FILE_DRAG_MIME } from "./drag";
+import { FOLDER_STYLE } from "./folder-constants";
+
+interface Props {
+ id: string;
+ name: string;
+ fileCount: number;
+ onEdit: () => void;
+ onDelete: () => void;
+ onClick: () => void;
+ onFileDrop: (fileId: string, folderId: string) => void;
+}
+
+export function WorkspaceFolder({
+ id,
+ name,
+ fileCount,
+ onEdit,
+ onDelete,
+ onClick,
+ onFileDrop,
+}: Props) {
+ const [isDragOver, setIsDragOver] = useState(false);
+ const style = FOLDER_STYLE;
+
+ function handleDragOver(e: React.DragEvent<HTMLDivElement>) {
+ if (e.dataTransfer.types.includes(FILE_DRAG_MIME)) {
+ e.preventDefault();
+ e.dataTransfer.dropEffect = "move";
+ setIsDragOver(true);
+ }
+ }
+
+ function handleDragLeave(e: React.DragEvent<HTMLDivElement>) {
+ // Ignore leave events fired while moving onto a child element — only clear
+ // the highlight when the cursor actually exits the folder card.
+ if (e.currentTarget.contains(e.relatedTarget as Node | null)) return;
+ setIsDragOver(false);
+ }
+
+ function handleDrop(e: React.DragEvent<HTMLDivElement>) {
+ e.preventDefault();
+ setIsDragOver(false);
+ const fileId = e.dataTransfer.getData(FILE_DRAG_MIME);
+ if (fileId) onFileDrop(fileId, id);
+ }
+
+ return (
+ <div
+ role="button"
+ tabIndex={0}
+ data-testid="workspace-folder"
+ data-folder-id={id}
+ onClick={onClick}
+ onKeyDown={(e) => {
+ if (e.key === "Enter" || e.key === " ") {
+ e.preventDefault();
+ onClick();
+ }
+ }}
+ onDragOver={handleDragOver}
+ onDragLeave={handleDragLeave}
+ onDrop={handleDrop}
+ className={`group flex cursor-pointer items-center gap-3 rounded-2xl border border-zinc-200 bg-white p-3 transition-all hover:border-zinc-300 ${
+ isDragOver ? `${style.surface} ring-2 ${style.ring}` : ""
+ }`}
+ >
+ <div
+ className={`flex h-10 w-10 shrink-0 items-center justify-center rounded-xl ${style.surface}`}
+ >
+ <FolderIcon size={22} weight="fill" className={style.icon} />
+ </div>
+ <div className="flex min-w-0 flex-1 flex-col">
+ <Text
+ variant="body-medium"
+ className="truncate text-zinc-900"
+ data-testid="workspace-folder-name"
+ title={name}
+ >
+ {name}
+ </Text>
+ <Text variant="small" className="text-zinc-500">
+ {fileCount} {fileCount === 1 ? "file" : "files"}
+ </Text>
+ </div>
+ <div className="flex items-center gap-1 opacity-0 transition-opacity group-focus-within:opacity-100 group-hover:opacity-100">
+ <Button
+ variant="icon"
+ size="icon"
+ aria-label="Rename folder"
+ onClick={(e) => {
+ e.stopPropagation();
+ onEdit();
+ }}
+ className="h-9 w-9 !p-2 text-zinc-500 hover:text-zinc-800"
+ >
+ <PencilSimpleIcon size={16} />
+ </Button>
+ <Button
+ variant="icon"
+ size="icon"
+ aria-label="Delete folder"
+ onClick={(e) => {
+ e.stopPropagation();
+ onDelete();
+ }}
+ className="h-9 w-9 !p-2 text-zinc-500 hover:text-red-600"
+ >
+ <TrashIcon size={16} />
+ </Button>
+ </div>
+ </div>
+ );
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/WorkspaceFolders.tsx b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/WorkspaceFolders.tsx
new file mode 100644
index 0000000000..806a207b46
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/WorkspaceFolders.tsx
@@ -0,0 +1,141 @@
+"use client";
+
+import { useState } from "react";
+import { FolderSimplePlusIcon } from "@phosphor-icons/react";
+import { Button } from "@/components/atoms/Button/Button";
+import { Skeleton } from "@/components/atoms/Skeleton/Skeleton";
+import { Text } from "@/components/atoms/Text/Text";
+import { ErrorCard } from "@/components/molecules/ErrorCard/ErrorCard";
+import type { WorkspaceFolder as WorkspaceFolderModel } from "@/app/api/__generated__/models/workspaceFolder";
+import { useArtifactsFolders } from "../../useArtifactsFolders";
+import { DeleteFolderDialog } from "./DeleteFolderDialog";
+import { FolderFormDialog } from "./FolderFormDialog";
+import { WorkspaceFolder } from "./WorkspaceFolder";
+
+interface Props {
+ onSelectFolder: (folderId: string) => void;
+}
+
+export function WorkspaceFolders({ onSelectFolder }: Props) {
+ const {
+ folders,
+ isLoading,
+ isError,
+ error,
+ createFolder,
+ isCreating,
+ updateFolder,
+ isUpdating,
+ deleteFolder,
+ isDeleting,
+ moveFileToFolder,
+ } = useArtifactsFolders();
+
+ const [isCreateOpen, setIsCreateOpen] = useState(false);
+ const [editing, setEditing] = useState<WorkspaceFolderModel | null>(null);
+ const [deleting, setDeleting] = useState<WorkspaceFolderModel | null>(null);
+
+ if (isLoading) {
+ return (
+ <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4">
+ {Array.from({ length: 3 }).map((_, i) => (
+ <Skeleton key={i} className="h-16 w-full rounded-2xl" />
+ ))}
+ </div>
+ );
+ }
+
+ if (isError) {
+ return (
+ <ErrorCard
+ context="folders"
+ responseError={
+ error instanceof Error ? { message: error.message } : undefined
+ }
+ />
+ );
+ }
+
+ return (
+ <div className="flex flex-col gap-3" data-testid="workspace-folders">
+ <div className="flex items-center justify-between">
+ <Text variant="large-medium" className="text-zinc-700">
+ Folders
+ </Text>
+ <Button
+ variant="secondary"
+ size="small"
+ onClick={() => setIsCreateOpen(true)}
+ data-testid="create-folder-button"
+ >
+ <FolderSimplePlusIcon size={18} />
+ New folder
+ </Button>
+ </div>
+
+ {folders.length === 0 ? (
+ <Text variant="small" className="text-zinc-400">
+ No folders yet. Create one to organize your files.
+ </Text>
+ ) : (
+ <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4">
+ {folders.map((folder) => (
+ <WorkspaceFolder
+ key={folder.id}
+ id={folder.id}
+ name={folder.name}
+ fileCount={folder.file_count ?? 0}
+ onClick={() => onSelectFolder(folder.id)}
+ onEdit={() => setEditing(folder)}
+ onDelete={() => setDeleting(folder)}
+ onFileDrop={(fileId, folderId) => {
+ moveFileToFolder({ fileId, folderId }).catch(() => {});
+ }}
+ />
+ ))}
+ </div>
+ )}
+
+ <FolderFormDialog
+ isOpen={isCreateOpen}
+ setIsOpen={setIsCreateOpen}
+ mode="create"
+ isSubmitting={isCreating}
+ onSubmit={(values) => {
+ // Close only on success; the hook toasts on error and we keep the
+ // dialog open so the user's input isn't lost.
+ createFolder(values)
+ .then(() => setIsCreateOpen(false))
+ .catch(() => {});
+ }}
+ />
+
+ <FolderFormDialog
+ isOpen={editing !== null}
+ setIsOpen={(open) => !open && setEditing(null)}
+ mode="edit"
+ initialName={editing?.name}
+ isSubmitting={isUpdating}
+ onSubmit={(values) => {
+ if (!editing) return;
+ updateFolder({ folderId: editing.id, ...values })
+ .then(() => setEditing(null))
+ .catch(() => {});
+ }}
+ />
+
+ <DeleteFolderDialog
+ isOpen={deleting !== null}
+ setIsOpen={(open) => !open && setDeleting(null)}
+ folderName={deleting?.name ?? ""}
+ isDeleting={isDeleting}
+ onConfirm={() => {
+ if (!deleting) return;
+ deleteFolder(deleting.id)
+ .then(() => setDeleting(null))
+ .catch(() => {});
+ }}
+ />
+ </div>
+ );
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/drag.test.ts b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/drag.test.ts
new file mode 100644
index 0000000000..ec9cddeba4
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/drag.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, test } from "vitest";
+
+import { createFileDragImage, FILE_DRAG_MIME } from "./drag";
+
+describe("createFileDragImage", () => {
+ test("renders an off-screen chip containing the file name", () => {
+ const el = createFileDragImage("report.pdf");
+ expect(el.textContent).toContain("report.pdf");
+ // Positioned off-screen so it never flashes on the page.
+ expect(el.style.position).toBe("absolute");
+ });
+
+ test("escapes HTML special characters in the file name", () => {
+ const el = createFileDragImage('<img src=x onerror="alert(1)">.txt');
+ expect(el.innerHTML).not.toContain("<img");
+ expect(el.innerHTML).toContain("&lt;img");
+ });
+});
+
+describe("FILE_DRAG_MIME", () => {
+ test("is a stable custom MIME type", () => {
+ expect(FILE_DRAG_MIME).toBe("application/workspace-file-id");
+ });
+});
diff --git a/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/drag.ts b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/drag.ts
new file mode 100644
index 0000000000..f45065df8a
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/drag.ts
@@ -0,0 +1,40 @@
+/** DataTransfer MIME type used when dragging a file card onto a folder. */
+export const FILE_DRAG_MIME = "application/workspace-file-id";
+
+const FILE_GLYPH = `<svg width="20" height="20" viewBox="0 0 256 256" fill="currentColor" xmlns="http://www.w3.org/2000/svg"><path d="M213.66,82.34l-56-56A8,8,0,0,0,152,24H56A16,16,0,0,0,40,40V216a16,16,0,0,0,16,16H200a16,16,0,0,0,16-16V88A8,8,0,0,0,213.66,82.34ZM160,51.31,188.69,80H160ZM200,216H56V40h88V88a8,8,0,0,0,8,8h48V216Z"></path></svg>`;
+
+function escapeHtml(value: string): string {
+ return value
+ .replace(/&/g, "&amp;")
+ .replace(/</g, "&lt;")
+ .replace(/>/g, "&gt;")
+ .replace(/"/g, "&quot;");
+}
+
+/**
+ * Builds an off-screen "file illustration" element used as the drag image when
+ * dragging a file card, so the cursor carries a compact file chip instead of a
+ * snapshot of the whole card. Caller is responsible for removing it on dragend.
+ */
+export function createFileDragImage(fileName: string): HTMLElement {
+ const el = document.createElement("div");
+ el.style.cssText = [
+ "position:absolute",
+ "top:-1000px",
+ "left:-1000px",
+ "display:inline-flex",
+ "align-items:center",
+ "gap:8px",
+ "padding:8px 12px",
+ "border-radius:12px",
+ "border:1px solid #e4e4e7",
+ "background:#ffffff",
+ "color:#71717a",
+ "font:500 13px ui-sans-serif,system-ui,sans-serif",
+ "box-shadow:0 4px 12px rgba(0,0,0,0.08)",
+ ].join(";");
+ el.innerHTML = `${FILE_GLYPH}<span style="color:#18181b;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:160px;">${escapeHtml(
+ fileName,
+ )}</span>`;
+ return el;
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/folder-constants.ts b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/folder-constants.ts
new file mode 100644
index 0000000000..3c0e0d95f4
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/artifacts/components/WorkspaceFolders/folder-constants.ts
@@ -0,0 +1,6 @@
+/** Neutral styling shared by folder surfaces (icon tile, drag-over ring). */
+export const FOLDER_STYLE = {
+ icon: "text-zinc-500",
+ surface: "bg-zinc-100",
+ ring: "ring-zinc-300",
+};
diff --git a/autogpt_platform/frontend/src/app/(platform)/artifacts/page.tsx b/autogpt_platform/frontend/src/app/(platform)/artifacts/page.tsx
index 3b5fc2d857..19ad3446ad 100644
--- a/autogpt_platform/frontend/src/app/(platform)/artifacts/page.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/artifacts/page.tsx
@@ -11,6 +11,9 @@ import { ArtifactsSearchBar } from "./components/ArtifactsSearchBar/ArtifactsSea
import { ArtifactsList } from "./components/ArtifactsList/ArtifactsList";
import { OriginFilter } from "./components/OriginFilter/OriginFilter";
import { StorageUsage } from "./components/StorageUsage/StorageUsage";
+import { FolderBreadcrumb } from "./components/WorkspaceFolders/FolderBreadcrumb";
+import { WorkspaceFolders } from "./components/WorkspaceFolders/WorkspaceFolders";
+import { useArtifactsFolders } from "./useArtifactsFolders";
import { useArtifactsPage } from "./useArtifactsPage";
const EASE_OUT_SOFT: Transition["ease"] = [0.16, 1, 0.3, 1];
@@ -45,10 +48,16 @@ export default function ArtifactsPage() {
debouncedSearch,
originFilter,
setOriginFilter,
+ selectedFolderId,
+ setSelectedFolderId,
hasMore,
isLoadingMore,
loadMore,
} = useArtifactsPage();
+ const { folders } = useArtifactsFolders();
+
+ const isSearching = searchTerm.length > 0;
+ const selectedFolder = folders.find((f) => f.id === selectedFolderId);
useEffect(() => {
document.title = "Files – AutoGPT Platform";
@@ -110,6 +119,30 @@ export default function ArtifactsPage() {
<OriginFilter value={originFilter} onChange={setOriginFilter} />
</motion.div>
</div>
+ {selectedFolderId !== null ? (
+ <motion.div
+ variants={variants}
+ initial="hidden"
+ animate="show"
+ transition={{ delay: reduceMotion ? 0 : 0.3 }}
+ >
+ <FolderBreadcrumb
+ folderName={selectedFolder?.name ?? "Folder"}
+ onBack={() => setSelectedFolderId(null)}
+ />
+ </motion.div>
+ ) : (
+ !isSearching && (
+ <motion.div
+ variants={variants}
+ initial="hidden"
+ animate="show"
+ transition={{ delay: reduceMotion ? 0 : 0.3 }}
+ >
+ <WorkspaceFolders onSelectFolder={setSelectedFolderId} />
+ </motion.div>
+ )
+ )}
<motion.div
variants={variants}
initial="hidden"
@@ -125,7 +158,7 @@ export default function ArtifactsPage() {
hasMore={hasMore}
isLoadingMore={isLoadingMore}
onLoadMore={loadMore}
- listKey={`${originFilter}|${debouncedSearch}`}
+ listKey={`${originFilter}|${debouncedSearch}|${selectedFolderId ?? "root"}`}
/>
</motion.div>
</main>
diff --git a/autogpt_platform/frontend/src/app/(platform)/artifacts/useArtifactsFolders.ts b/autogpt_platform/frontend/src/app/(platform)/artifacts/useArtifactsFolders.ts
new file mode 100644
index 0000000000..14af989547
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/artifacts/useArtifactsFolders.ts
@@ -0,0 +1,109 @@
+import { useQueryClient } from "@tanstack/react-query";
+import {
+ getListWorkspaceFoldersQueryKey,
+ useBulkMoveWorkspaceFiles,
+ useCreateWorkspaceFolder,
+ useDeleteWorkspaceFolder,
+ useListWorkspaceFolders,
+ useUpdateWorkspaceFolder,
+} from "@/app/api/__generated__/endpoints/workspace/workspace";
+import { okData } from "@/app/api/helpers";
+import { useToast } from "@/components/molecules/Toast/use-toast";
+import { ARTIFACTS_LIST_QUERY_KEY } from "./useArtifactsPage";
+
+export function useArtifactsFolders() {
+ const queryClient = useQueryClient();
+ const { toast } = useToast();
+
+ const foldersQuery = useListWorkspaceFolders({
+ query: { select: okData },
+ });
+
+ function invalidate() {
+ queryClient.invalidateQueries({
+ queryKey: getListWorkspaceFoldersQueryKey(),
+ });
+ queryClient.invalidateQueries({ queryKey: ARTIFACTS_LIST_QUERY_KEY });
+ }
+
+ const createMutation = useCreateWorkspaceFolder({
+ mutation: {
+ onSuccess: () => {
+ invalidate();
+ toast({ title: "Folder created" });
+ },
+ onError: () => {
+ toast({
+ title: "Failed to create folder",
+ description: "A folder with this name may already exist.",
+ variant: "destructive",
+ });
+ },
+ },
+ });
+
+ const updateMutation = useUpdateWorkspaceFolder({
+ mutation: {
+ onSuccess: () => {
+ invalidate();
+ toast({ title: "Folder updated" });
+ },
+ onError: () => {
+ toast({
+ title: "Failed to update folder",
+ variant: "destructive",
+ });
+ },
+ },
+ });
+
+ const deleteMutation = useDeleteWorkspaceFolder({
+ mutation: {
+ onSuccess: () => {
+ invalidate();
+ toast({ title: "Folder deleted", description: "Files moved to root." });
+ },
+ onError: () => {
+ toast({
+ title: "Failed to delete folder",
+ variant: "destructive",
+ });
+ },
+ },
+ });
+
+ const moveMutation = useBulkMoveWorkspaceFiles({
+ mutation: {
+ onSuccess: () => {
+ invalidate();
+ toast({ title: "File moved" });
+ },
+ onError: () => {
+ toast({ title: "Failed to move file", variant: "destructive" });
+ },
+ },
+ });
+
+ return {
+ folders: foldersQuery.data?.folders ?? [],
+ isLoading: foldersQuery.isLoading,
+ isError: foldersQuery.isError,
+ error: foldersQuery.error,
+ createFolder: (args: { name: string }) =>
+ createMutation.mutateAsync({ data: { name: args.name } }),
+ isCreating: createMutation.isPending,
+ updateFolder: (args: { folderId: string; name?: string }) =>
+ updateMutation.mutateAsync({
+ folderId: args.folderId,
+ data: { name: args.name },
+ }),
+ isUpdating: updateMutation.isPending,
+ deleteFolder: (folderId: string) =>
+ deleteMutation.mutateAsync({ folderId }),
+ isDeleting: deleteMutation.isPending,
+ moveFileToFolder: (args: { fileId: string; folderId: string | null }) =>
+ moveMutation.mutateAsync({
+ data: { file_ids: [args.fileId], folder_id: args.folderId },
+ }),
+ };
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/artifacts/useArtifactsPage.ts b/autogpt_platform/frontend/src/app/(platform)/artifacts/useArtifactsPage.ts
index 56df6010e2..835dc6c2e7 100644
--- a/autogpt_platform/frontend/src/app/(platform)/artifacts/useArtifactsPage.ts
+++ b/autogpt_platform/frontend/src/app/(platform)/artifacts/useArtifactsPage.ts
@@ -15,6 +15,7 @@ type ListPage = Awaited<ReturnType<typeof listWorkspaceFiles>>;
export function useArtifactsPage() {
const [searchTerm, setSearchTerm] = useState("");
const [originFilter, setOriginFilter] = useState<OriginFilter>("all");
+ const [selectedFolderId, setSelectedFolderId] = useState<string | null>(null);
const debouncedSearch = useDebouncedValue(
searchTerm.trim(),
@@ -23,11 +24,22 @@ export function useArtifactsPage() {
const q = debouncedSearch || undefined;
const origin = originFilter === "all" ? undefined : originFilter;
+ // No folder selected → show only root-level files; a folder is selected →
+ // scope the listing to that folder.
+ const folderId = selectedFolderId ?? undefined;
+ // While searching, span the whole workspace (including files inside folders)
+ // so global search isn't limited to root-level files.
+ const rootOnly = selectedFolderId === null && !q;
const query = useInfiniteQuery({
queryKey: [
...ARTIFACTS_LIST_QUERY_KEY,
- { q: q ?? null, origin: origin ?? null },
+ {
+ q: q ?? null,
+ origin: origin ?? null,
+ folderId: folderId ?? null,
+ rootOnly,
+ },
] as const,
queryFn: ({ pageParam }) =>
listWorkspaceFiles({
@@ -35,6 +47,8 @@ export function useArtifactsPage() {
offset: pageParam,
q,
origin,
+ folder_id: folderId,
+ root_only: rootOnly,
}),
initialPageParam: 0,
getNextPageParam: (lastPage, allPages) => {
@@ -58,6 +72,8 @@ export function useArtifactsPage() {
debouncedSearch,
originFilter,
setOriginFilter,
+ selectedFolderId,
+ setSelectedFolderId,
hasMore: !!query.hasNextPage,
isLoadingMore: query.isFetchingNextPage,
loadMore: () => {
diff --git a/autogpt_platform/frontend/src/app/api/openapi.json b/autogpt_platform/frontend/src/app/api/openapi.json
index 98235ad2f2..e203a315ac 100644
--- a/autogpt_platform/frontend/src/app/api/openapi.json
+++ b/autogpt_platform/frontend/src/app/api/openapi.json
@@ -10996,7 +10996,7 @@
"get": {
"tags": ["workspace"],
"summary": "List workspace files",
- "description": "List files in the user's workspace.\n\nWhen session_id is provided, only files for that session are returned.\nOtherwise, all files across sessions are listed. Results are paginated\nvia `limit`/`offset`; `has_more` indicates whether additional pages exist.\n\nThe Artifacts page uses ``q`` for name search and ``origin`` to filter\nbetween Uploaded (user-uploaded) and Generated (agent/block output) files.",
+ "description": "List files in the user's workspace.\n\nWhen session_id is provided, only files for that session are returned.\nOtherwise, all files across sessions are listed. Results are paginated\nvia `limit`/`offset`; `has_more` indicates whether additional pages exist.\n\nThe Artifacts page uses ``q`` for name search and ``origin`` to filter\nbetween Uploaded (user-uploaded) and Generated (agent/block output) files.\n\n``session_id`` (a per-session view) and the folder filters (``folder_id`` /\n``root_only``) are distinct, mutually exclusive axes, and ``folder_id`` and\n``root_only`` likewise conflict; passing conflicting filters returns a 400\nrather than silently yielding an empty list.",
"operationId": "listWorkspaceFiles",
"security": [{ "HTTPBearerJWT": [] }],
"parameters": [
@@ -11056,6 +11056,32 @@
"title": "Origin"
},
"description": "Filter by file origin. ``uploaded`` matches files the user uploaded (``metadata.origin == 'user-upload'``, set by the upload endpoint for both Builder and CoPilot uploads); ``generated`` matches everything else (agent/block output). Ignored when ``session_id`` is set."
+ },
+ {
+ "name": "folder_id",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "anyOf": [
+ { "type": "string", "minLength": 1 },
+ { "type": "null" }
+ ],
+ "description": "Only return files in this folder.",
+ "title": "Folder Id"
+ },
+ "description": "Only return files in this folder."
+ },
+ {
+ "name": "root_only",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "boolean",
+ "description": "Only return root-level files (not in any folder).",
+ "default": false,
+ "title": "Root Only"
+ },
+ "description": "Only return root-level files (not in any folder)."
}
],
"responses": {
@@ -11274,6 +11300,186 @@
}
}
},
+ "/api/workspace/folders": {
+ "get": {
+ "tags": ["workspace"],
+ "summary": "List workspace folders",
+ "operationId": "listWorkspaceFolders",
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WorkspaceFolderListResponse"
+ }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+ }
+ },
+ "security": [{ "HTTPBearerJWT": [] }]
+ },
+ "post": {
+ "tags": ["workspace"],
+ "summary": "Create workspace folder",
+ "operationId": "createWorkspaceFolder",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WorkspaceFolderCreateRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "201": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/WorkspaceFolder" }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+ },
+ "409": { "description": "A folder with this name already exists" },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+ }
+ }
+ }
+ },
+ "security": [{ "HTTPBearerJWT": [] }]
+ }
+ },
+ "/api/workspace/folders/files/bulk-move": {
+ "post": {
+ "tags": ["workspace"],
+ "summary": "Move workspace files to a folder",
+ "operationId": "bulkMoveWorkspaceFiles",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/BulkMoveFilesRequest" }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": {
+ "items": { "$ref": "#/components/schemas/WorkspaceFile" },
+ "type": "array",
+ "title": "Response Bulkmoveworkspacefiles"
+ }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+ }
+ }
+ }
+ },
+ "security": [{ "HTTPBearerJWT": [] }]
+ }
+ },
+ "/api/workspace/folders/{folder_id}": {
+ "delete": {
+ "tags": ["workspace"],
+ "summary": "Delete workspace folder",
+ "operationId": "deleteWorkspaceFolder",
+ "security": [{ "HTTPBearerJWT": [] }],
+ "parameters": [
+ {
+ "name": "folder_id",
+ "in": "path",
+ "required": true,
+ "schema": { "type": "string", "title": "Folder Id" }
+ }
+ ],
+ "responses": {
+ "204": { "description": "Successful Response" },
+ "401": {
+ "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+ },
+ "404": { "description": "Folder not found" },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+ }
+ }
+ }
+ }
+ },
+ "patch": {
+ "tags": ["workspace"],
+ "summary": "Update workspace folder",
+ "operationId": "updateWorkspaceFolder",
+ "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/WorkspaceFolderUpdateRequest"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/WorkspaceFolder" }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+ },
+ "404": { "description": "Folder not found" },
+ "409": { "description": "A folder with this name already exists" },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+ }
+ }
+ }
+ }
+ }
+ },
"/api/workspace/storage/usage": {
"get": {
"tags": ["workspace"],
@@ -12856,6 +13062,22 @@
"title": "BulkMoveAgentsRequest",
"description": "Request model for moving multiple agents to a folder."
},
+ "BulkMoveFilesRequest": {
+ "properties": {
+ "file_ids": {
+ "items": { "type": "string" },
+ "type": "array",
+ "title": "File Ids"
+ },
+ "folder_id": {
+ "anyOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }],
+ "title": "Folder Id"
+ }
+ },
+ "type": "object",
+ "required": ["file_ids"],
+ "title": "BulkMoveFilesRequest"
+ },
"CancelSessionResponse": {
"properties": {
"cancelled": { "type": "boolean", "title": "Cancelled" },
@@ -22768,6 +22990,66 @@
],
"title": "Webhook"
},
+ "WorkspaceFile": {
+ "properties": {
+ "id": { "type": "string", "title": "Id" },
+ "workspace_id": { "type": "string", "title": "Workspace Id" },
+ "created_at": {
+ "type": "string",
+ "format": "date-time",
+ "title": "Created At"
+ },
+ "updated_at": {
+ "type": "string",
+ "format": "date-time",
+ "title": "Updated At"
+ },
+ "name": { "type": "string", "title": "Name" },
+ "path": { "type": "string", "title": "Path" },
+ "storage_path": { "type": "string", "title": "Storage Path" },
+ "mime_type": { "type": "string", "title": "Mime Type" },
+ "size_bytes": { "type": "integer", "title": "Size Bytes" },
+ "checksum": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Checksum"
+ },
+ "is_deleted": {
+ "type": "boolean",
+ "title": "Is Deleted",
+ "default": false
+ },
+ "deleted_at": {
+ "anyOf": [
+ { "type": "string", "format": "date-time" },
+ { "type": "null" }
+ ],
+ "title": "Deleted At"
+ },
+ "folder_id": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Folder Id"
+ },
+ "metadata": {
+ "additionalProperties": true,
+ "type": "object",
+ "title": "Metadata"
+ }
+ },
+ "type": "object",
+ "required": [
+ "id",
+ "workspace_id",
+ "created_at",
+ "updated_at",
+ "name",
+ "path",
+ "storage_path",
+ "mime_type",
+ "size_bytes"
+ ],
+ "title": "WorkspaceFile",
+ "description": "Pydantic model for UserWorkspaceFile, safe for RPC transport."
+ },
"WorkspaceFileItem": {
"properties": {
"id": { "type": "string", "title": "Id" },
@@ -22775,6 +23057,10 @@
"path": { "type": "string", "title": "Path" },
"mime_type": { "type": "string", "title": "Mime Type" },
"size_bytes": { "type": "integer", "title": "Size Bytes" },
+ "folder_id": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Folder Id"
+ },
"metadata": {
"additionalProperties": true,
"type": "object",
@@ -22799,6 +23085,82 @@
],
"title": "WorkspaceFileItem"
},
+ "WorkspaceFolder": {
+ "properties": {
+ "id": { "type": "string", "title": "Id" },
+ "workspace_id": { "type": "string", "title": "Workspace Id" },
+ "name": { "type": "string", "title": "Name" },
+ "icon": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Icon"
+ },
+ "created_at": {
+ "type": "string",
+ "format": "date-time",
+ "title": "Created At"
+ },
+ "updated_at": {
+ "type": "string",
+ "format": "date-time",
+ "title": "Updated At"
+ },
+ "file_count": {
+ "type": "integer",
+ "title": "File Count",
+ "default": 0
+ }
+ },
+ "type": "object",
+ "required": ["id", "workspace_id", "name", "created_at", "updated_at"],
+ "title": "WorkspaceFolder",
+ "description": "Pydantic model for UserWorkspaceFolder, safe for RPC transport."
+ },
+ "WorkspaceFolderCreateRequest": {
+ "properties": {
+ "name": {
+ "type": "string",
+ "maxLength": 100,
+ "minLength": 1,
+ "title": "Name"
+ },
+ "icon": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Icon"
+ }
+ },
+ "type": "object",
+ "required": ["name"],
+ "title": "WorkspaceFolderCreateRequest"
+ },
+ "WorkspaceFolderListResponse": {
+ "properties": {
+ "folders": {
+ "items": { "$ref": "#/components/schemas/WorkspaceFolder" },
+ "type": "array",
+ "title": "Folders"
+ }
+ },
+ "type": "object",
+ "required": ["folders"],
+ "title": "WorkspaceFolderListResponse"
+ },
+ "WorkspaceFolderUpdateRequest": {
+ "properties": {
+ "name": {
+ "anyOf": [
+ { "type": "string", "maxLength": 100, "minLength": 1 },
+ { "type": "null" }
+ ],
+ "title": "Name"
+ },
+ "icon": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Icon"
+ }
+ },
+ "type": "object",
+ "title": "WorkspaceFolderUpdateRequest"
+ },
"WriteSummary": {
"properties": {
"edge_uuid": {
diff --git a/autogpt_platform/frontend/src/mocks/mock-handlers.ts b/autogpt_platform/frontend/src/mocks/mock-handlers.ts
index 49c2392bdb..1069d178f0 100644
--- a/autogpt_platform/frontend/src/mocks/mock-handlers.ts
+++ b/autogpt_platform/frontend/src/mocks/mock-handlers.ts
@@ -21,6 +21,7 @@ import { getPresetsMock } from "@/app/api/__generated__/endpoints/presets/preset
import { getSchedulesMock } from "@/app/api/__generated__/endpoints/schedules/schedules.msw";
import { getSearchMock } from "@/app/api/__generated__/endpoints/search/search.msw";
import { getStoreMock } from "@/app/api/__generated__/endpoints/store/store.msw";
+import { getWorkspaceMock } from "@/app/api/__generated__/endpoints/workspace/workspace.msw";
// Pass hard-coded data to individual handler functions to override faker-generated data.
export const mockHandlers = [
@@ -47,4 +48,5 @@ export const mockHandlers = [
...getSchedulesMock(),
...getSearchMock(),
...getStoreMock(),
+ ...getWorkspaceMock(),
];