refactor: remove redundant virus scan from WriteWorkspaceFileTool

WorkspaceManager.write_file() now handles scanning, so tools don't need to.

autogpt_platform/autogpt_libs/pyproject.toml

@@ -11,15 +11,15 @@ python = ">=3.10,<4.0"
 colorama = "^0.4.6"
 cryptography = "^45.0"
 expiringdict = "^1.2.2"
-fastapi = "^0.128.0"
-google-cloud-logging = "^3.13.0"
-launchdarkly-server-sdk = "^9.14.1"
-pydantic = "^2.12.5"
-pydantic-settings = "^2.12.0"
-pyjwt = { version = "^2.11.0", extras = ["crypto"] }
+fastapi = "^0.116.1"
+google-cloud-logging = "^3.12.1"
+launchdarkly-server-sdk = "^9.12.0"
+pydantic = "^2.11.7"
+pydantic-settings = "^2.10.1"
+pyjwt = { version = "^2.10.1", extras = ["crypto"] }
 redis = "^6.2.0"
-supabase = "^2.27.2"
-uvicorn = "^0.40.0"
+supabase = "^2.16.0"
+uvicorn = "^0.35.0"
 
 [tool.poetry.group.dev.dependencies]
 pyright = "^1.1.404"

autogpt_platform/backend/CLAUDE.md

@@ -157,6 +157,16 @@ yield "image_url", result_url
 3. Write tests alongside the route file
 4. Run `poetry run test` to verify
 
+## Workspace & Media Files
+
+**Read [Workspace & Media Architecture](../../docs/platform/workspace-media-architecture.md) when:**
+- Working on CoPilot file upload/download features
+- Building blocks that handle `MediaFileType` inputs/outputs
+- Modifying `WorkspaceManager` or `store_media_file()`
+- Debugging file persistence or virus scanning issues
+
+Covers: `WorkspaceManager` (persistent storage with session scoping), `store_media_file()` (media normalization pipeline), and responsibility boundaries for virus scanning and persistence.
+
 ## Security Implementation
 
 ### Cache Protection Middleware

autogpt_platform/backend/backend/api/features/chat/tools/utils.py

@@ -6,6 +6,7 @@ from typing import Any
 from backend.api.features.library import db as library_db
 from backend.api.features.library import model as library_model
 from backend.api.features.store import db as store_db
+from backend.data import graph as graph_db
 from backend.data.graph import GraphModel
 from backend.data.model import (
     CredentialsFieldInfo,
@@ -43,8 +44,14 @@ async def fetch_graph_from_store_slug(
         return None, None
 
     # Get the graph from store listing version
-    graph = await store_db.get_available_graph(
-        store_agent.store_listing_version_id, hide_nodes=False
+    graph_meta = await store_db.get_available_graph(
+        store_agent.store_listing_version_id
+    )
+    graph = await graph_db.get_graph(
+        graph_id=graph_meta.id,
+        version=graph_meta.version,
+        user_id=None,  # Public access
+        include_subgraphs=True,
     )
     return graph, store_agent
 
@@ -121,7 +128,7 @@ def build_missing_credentials_from_graph(
 
     return {
         field_key: _serialize_missing_credential(field_key, field_info)
-        for field_key, (field_info, _, _) in aggregated_fields.items()
+        for field_key, (field_info, _node_fields) in aggregated_fields.items()
         if field_key not in matched_keys
     }
 
@@ -262,8 +269,7 @@ async def match_user_credentials_to_graph(
     # provider is in the set of acceptable providers.
     for credential_field_name, (
         credential_requirements,
-        _,
-        _,
+        _node_fields,
     ) in aggregated_creds.items():
         # Find first matching credential by provider, type, and scopes
         matching_cred = next(

autogpt_platform/backend/backend/api/features/chat/tools/workspace_files.py

@@ -9,7 +9,6 @@ from pydantic import BaseModel
 from backend.api.features.chat.model import ChatSession
 from backend.data.workspace import get_or_create_workspace
 from backend.util.settings import Config
-from backend.util.virus_scanner import scan_content_safe
 from backend.util.workspace import WorkspaceManager
 
 from .base import BaseTool
@@ -475,9 +474,6 @@ class WriteWorkspaceFileTool(BaseTool):
             )
 
         try:
-            # Virus scan
-            await scan_content_safe(content, filename=filename)
-
             workspace = await get_or_create_workspace(user_id)
             # Pass session_id for session-scoped file access
             manager = WorkspaceManager(user_id, workspace.id, session_id)

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

@@ -374,7 +374,7 @@ async def get_library_agent_by_graph_id(
 
 
 async def add_generated_agent_image(
-    graph: graph_db.GraphBaseMeta,
+    graph: graph_db.BaseGraph,
     user_id: str,
     library_agent_id: str,
 ) -> Optional[prisma.models.LibraryAgent]:

autogpt_platform/backend/backend/api/features/store/db.py

@@ -1,7 +1,7 @@
 import asyncio
 import logging
 from datetime import datetime, timezone
-from typing import Any, Literal, overload
+from typing import Any, Literal
 
 import fastapi
 import prisma.enums
@@ -11,8 +11,8 @@ import prisma.types
 
 from backend.data.db import transaction
 from backend.data.graph import (
+    GraphMeta,
     GraphModel,
-    GraphModelWithoutNodes,
     get_graph,
     get_graph_as_admin,
     get_sub_graphs,
@@ -334,22 +334,7 @@ async def get_store_agent_details(
         raise DatabaseError("Failed to fetch agent details") from e
 
 
-@overload
-async def get_available_graph(
-    store_listing_version_id: str, hide_nodes: Literal[False]
-) -> GraphModel: ...
-
-
-@overload
-async def get_available_graph(
-    store_listing_version_id: str, hide_nodes: Literal[True] = True
-) -> GraphModelWithoutNodes: ...
-
-
-async def get_available_graph(
-    store_listing_version_id: str,
-    hide_nodes: bool = True,
-) -> GraphModelWithoutNodes | GraphModel:
+async def get_available_graph(store_listing_version_id: str) -> GraphMeta:
     try:
         # Get avaialble, non-deleted store listing version
         store_listing_version = (
@@ -359,7 +344,7 @@ async def get_available_graph(
                     "isAvailable": True,
                     "isDeleted": False,
                 },
-                include={"AgentGraph": {"include": AGENT_GRAPH_INCLUDE}},
+                include={"AgentGraph": {"include": {"Nodes": True}}},
             )
         )
 
@@ -369,9 +354,7 @@ async def get_available_graph(
                 detail=f"Store listing version {store_listing_version_id} not found",
             )
 
-        return (GraphModelWithoutNodes if hide_nodes else GraphModel).from_db(
-            store_listing_version.AgentGraph
-        )
+        return GraphModel.from_db(store_listing_version.AgentGraph).meta()
 
     except Exception as e:
         logger.error(f"Error getting agent: {e}")

autogpt_platform/backend/backend/api/features/store/image_gen.py

@@ -16,7 +16,7 @@ from backend.blocks.ideogram import (
     StyleType,
     UpscaleOption,
 )
-from backend.data.graph import GraphBaseMeta
+from backend.data.graph import BaseGraph
 from backend.data.model import CredentialsMetaInput, ProviderName
 from backend.integrations.credentials_store import ideogram_credentials
 from backend.util.request import Requests
@@ -34,14 +34,14 @@ class ImageStyle(str, Enum):
     DIGITAL_ART = "digital art"
 
 
-async def generate_agent_image(agent: GraphBaseMeta | AgentGraph) -> io.BytesIO:
+async def generate_agent_image(agent: BaseGraph | AgentGraph) -> io.BytesIO:
     if settings.config.use_agent_image_generation_v2:
         return await generate_agent_image_v2(graph=agent)
     else:
         return await generate_agent_image_v1(agent=agent)
 
 
-async def generate_agent_image_v2(graph: GraphBaseMeta | AgentGraph) -> io.BytesIO:
+async def generate_agent_image_v2(graph: BaseGraph | AgentGraph) -> io.BytesIO:
     """
     Generate an image for an agent using Ideogram model.
     Returns:
@@ -54,17 +54,14 @@ async def generate_agent_image_v2(graph: GraphBaseMeta | AgentGraph) -> io.Bytes
     description = f"{name} ({graph.description})" if graph.description else name
 
     prompt = (
-        "Create a visually striking retro-futuristic vector pop art illustration "
-        f'prominently featuring "{name}" in bold typography. The image clearly and '
-        f"literally depicts a {description}, along with recognizable objects directly "
-        f"associated with the primary function of a {name}. "
-        f"Ensure the imagery is concrete, intuitive, and immediately understandable, "
-        f"clearly conveying the purpose of a {name}. "
-        "Maintain vibrant, limited-palette colors, sharp vector lines, "
-        "geometric shapes, flat illustration techniques, and solid colors "
-        "without gradients or shading. Preserve a retro-futuristic aesthetic "
-        "influenced by mid-century futurism and 1960s psychedelia, "
-        "prioritizing clear visual storytelling and thematic clarity above all else."
+        f"Create a visually striking retro-futuristic vector pop art illustration prominently featuring "
+        f'"{name}" in bold typography. The image clearly and literally depicts a {description}, '
+        f"along with recognizable objects directly associated with the primary function of a {name}. "
+        f"Ensure the imagery is concrete, intuitive, and immediately understandable, clearly conveying the "
+        f"purpose of a {name}. Maintain vibrant, limited-palette colors, sharp vector lines, geometric "
+        f"shapes, flat illustration techniques, and solid colors without gradients or shading. Preserve a "
+        f"retro-futuristic aesthetic influenced by mid-century futurism and 1960s psychedelia, "
+        f"prioritizing clear visual storytelling and thematic clarity above all else."
     )
 
     custom_colors = [
@@ -102,12 +99,12 @@ async def generate_agent_image_v2(graph: GraphBaseMeta | AgentGraph) -> io.Bytes
     return io.BytesIO(response.content)
 
 
-async def generate_agent_image_v1(agent: GraphBaseMeta | AgentGraph) -> io.BytesIO:
+async def generate_agent_image_v1(agent: BaseGraph | AgentGraph) -> io.BytesIO:
     """
     Generate an image for an agent using Flux model via Replicate API.
 
     Args:
-        agent (GraphBaseMeta | AgentGraph): The agent to generate an image for
+        agent (Graph): The agent to generate an image for
 
     Returns:
         io.BytesIO: The generated image as bytes
@@ -117,13 +114,7 @@ async def generate_agent_image_v1(agent: GraphBaseMeta | AgentGraph) -> io.Bytes
             raise ValueError("Missing Replicate API key in settings")
 
         # Construct prompt from agent details
-        prompt = (
-            "Create a visually engaging app store thumbnail for the AI agent "
-            "that highlights what it does in a clear and captivating way:\n"
-            f"- **Name**: {agent.name}\n"
-            f"- **Description**: {agent.description}\n"
-            f"Focus on showcasing its core functionality with an appealing design."
-        )
+        prompt = f"Create a visually engaging app store thumbnail for the AI agent that highlights what it does in a clear and captivating way:\n- **Name**: {agent.name}\n- **Description**: {agent.description}\nFocus on showcasing its core functionality with an appealing design."
 
         # Set up Replicate client
         client = ReplicateClient(api_token=settings.secrets.replicate_api_key)

autogpt_platform/backend/backend/api/features/store/routes.py

@@ -278,7 +278,7 @@ async def get_agent(
 )
 async def get_graph_meta_by_store_listing_version_id(
     store_listing_version_id: str,
-) -> backend.data.graph.GraphModelWithoutNodes:
+) -> backend.data.graph.GraphMeta:
     """
     Get Agent Graph from Store Listing Version ID.
     """

autogpt_platform/backend/backend/blocks/exa/websets.py

@@ -478,7 +478,7 @@ class ExaCreateOrFindWebsetBlock(Block):
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
         try:
-            webset = await aexa.websets.get(id=input_data.external_id)
+            webset = aexa.websets.get(id=input_data.external_id)
             webset_result = Webset.model_validate(webset.model_dump(by_alias=True))
 
             yield "webset", webset_result
@@ -494,7 +494,7 @@ class ExaCreateOrFindWebsetBlock(Block):
                         count=input_data.search_count,
                     )
 
-                webset = await aexa.websets.create(
+                webset = aexa.websets.create(
                     params=CreateWebsetParameters(
                         search=search_params,
                         external_id=input_data.external_id,
@@ -554,7 +554,7 @@ class ExaUpdateWebsetBlock(Block):
         if input_data.metadata is not None:
             payload["metadata"] = input_data.metadata
 
-        sdk_webset = await aexa.websets.update(id=input_data.webset_id, params=payload)
+        sdk_webset = aexa.websets.update(id=input_data.webset_id, params=payload)
 
         status_str = (
             sdk_webset.status.value
@@ -617,7 +617,7 @@ class ExaListWebsetsBlock(Block):
     ) -> BlockOutput:
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        response = await aexa.websets.list(
+        response = aexa.websets.list(
             cursor=input_data.cursor,
             limit=input_data.limit,
         )
@@ -678,7 +678,7 @@ class ExaGetWebsetBlock(Block):
     ) -> BlockOutput:
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        sdk_webset = await aexa.websets.get(id=input_data.webset_id)
+        sdk_webset = aexa.websets.get(id=input_data.webset_id)
 
         status_str = (
             sdk_webset.status.value
@@ -748,7 +748,7 @@ class ExaDeleteWebsetBlock(Block):
     ) -> BlockOutput:
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        deleted_webset = await aexa.websets.delete(id=input_data.webset_id)
+        deleted_webset = aexa.websets.delete(id=input_data.webset_id)
 
         status_str = (
             deleted_webset.status.value
@@ -798,7 +798,7 @@ class ExaCancelWebsetBlock(Block):
     ) -> BlockOutput:
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        canceled_webset = await aexa.websets.cancel(id=input_data.webset_id)
+        canceled_webset = aexa.websets.cancel(id=input_data.webset_id)
 
         status_str = (
             canceled_webset.status.value
@@ -968,7 +968,7 @@ class ExaPreviewWebsetBlock(Block):
                 entity["description"] = input_data.entity_description
             payload["entity"] = entity
 
-        sdk_preview = await aexa.websets.preview(params=payload)
+        sdk_preview = aexa.websets.preview(params=payload)
 
         preview = PreviewWebsetModel.from_sdk(sdk_preview)
 
@@ -1051,7 +1051,7 @@ class ExaWebsetStatusBlock(Block):
     ) -> BlockOutput:
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        webset = await aexa.websets.get(id=input_data.webset_id)
+        webset = aexa.websets.get(id=input_data.webset_id)
 
         status = (
             webset.status.value
@@ -1185,7 +1185,7 @@ class ExaWebsetSummaryBlock(Block):
     ) -> BlockOutput:
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        webset = await aexa.websets.get(id=input_data.webset_id)
+        webset = aexa.websets.get(id=input_data.webset_id)
 
         # Extract basic info
         webset_id = webset.id
@@ -1211,7 +1211,7 @@ class ExaWebsetSummaryBlock(Block):
         total_items = 0
 
         if input_data.include_sample_items and input_data.sample_size > 0:
-            items_response = await aexa.websets.items.list(
+            items_response = aexa.websets.items.list(
                 webset_id=input_data.webset_id, limit=input_data.sample_size
             )
             sample_items_data = [
@@ -1362,7 +1362,7 @@ class ExaWebsetReadyCheckBlock(Block):
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
         # Get webset details
-        webset = await aexa.websets.get(id=input_data.webset_id)
+        webset = aexa.websets.get(id=input_data.webset_id)
 
         status = (
             webset.status.value

autogpt_platform/backend/backend/blocks/exa/websets_enrichment.py

@@ -202,7 +202,7 @@ class ExaCreateEnrichmentBlock(Block):
         # Use AsyncExa SDK
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        sdk_enrichment = await aexa.websets.enrichments.create(
+        sdk_enrichment = aexa.websets.enrichments.create(
             webset_id=input_data.webset_id, params=payload
         )
 
@@ -223,7 +223,7 @@ class ExaCreateEnrichmentBlock(Block):
             items_enriched = 0
 
             while time.time() - poll_start < input_data.polling_timeout:
-                current_enrich = await aexa.websets.enrichments.get(
+                current_enrich = aexa.websets.enrichments.get(
                     webset_id=input_data.webset_id, id=enrichment_id
                 )
                 current_status = (
@@ -234,7 +234,7 @@ class ExaCreateEnrichmentBlock(Block):
 
                 if current_status in ["completed", "failed", "cancelled"]:
                     # Estimate items from webset searches
-                    webset = await aexa.websets.get(id=input_data.webset_id)
+                    webset = aexa.websets.get(id=input_data.webset_id)
                     if webset.searches:
                         for search in webset.searches:
                             if search.progress:
@@ -329,7 +329,7 @@ class ExaGetEnrichmentBlock(Block):
         # Use AsyncExa SDK
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        sdk_enrichment = await aexa.websets.enrichments.get(
+        sdk_enrichment = aexa.websets.enrichments.get(
             webset_id=input_data.webset_id, id=input_data.enrichment_id
         )
 
@@ -474,7 +474,7 @@ class ExaDeleteEnrichmentBlock(Block):
         # Use AsyncExa SDK
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        deleted_enrichment = await aexa.websets.enrichments.delete(
+        deleted_enrichment = aexa.websets.enrichments.delete(
             webset_id=input_data.webset_id, id=input_data.enrichment_id
         )
 
@@ -525,13 +525,13 @@ class ExaCancelEnrichmentBlock(Block):
         # Use AsyncExa SDK
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        canceled_enrichment = await aexa.websets.enrichments.cancel(
+        canceled_enrichment = aexa.websets.enrichments.cancel(
             webset_id=input_data.webset_id, id=input_data.enrichment_id
         )
 
         # Try to estimate how many items were enriched before cancellation
         items_enriched = 0
-        items_response = await aexa.websets.items.list(
+        items_response = aexa.websets.items.list(
             webset_id=input_data.webset_id, limit=100
         )
 

autogpt_platform/backend/backend/blocks/exa/websets_import_export.py

@@ -222,7 +222,7 @@ class ExaCreateImportBlock(Block):
     def _create_test_mock():
         """Create test mocks for the AsyncExa SDK."""
         from datetime import datetime
-        from unittest.mock import AsyncMock, MagicMock
+        from unittest.mock import MagicMock
 
         # Create mock SDK import object
         mock_import = MagicMock()
@@ -247,7 +247,7 @@ class ExaCreateImportBlock(Block):
         return {
             "_get_client": lambda *args, **kwargs: MagicMock(
                 websets=MagicMock(
-                    imports=MagicMock(create=AsyncMock(return_value=mock_import))
+                    imports=MagicMock(create=lambda *args, **kwargs: mock_import)
                 )
             )
         }
@@ -294,7 +294,7 @@ class ExaCreateImportBlock(Block):
         if input_data.metadata:
             payload["metadata"] = input_data.metadata
 
-        sdk_import = await aexa.websets.imports.create(
+        sdk_import = aexa.websets.imports.create(
             params=payload, csv_data=input_data.csv_data
         )
 
@@ -360,7 +360,7 @@ class ExaGetImportBlock(Block):
         # Use AsyncExa SDK
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        sdk_import = await aexa.websets.imports.get(import_id=input_data.import_id)
+        sdk_import = aexa.websets.imports.get(import_id=input_data.import_id)
 
         import_obj = ImportModel.from_sdk(sdk_import)
 
@@ -426,7 +426,7 @@ class ExaListImportsBlock(Block):
         # Use AsyncExa SDK
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        response = await aexa.websets.imports.list(
+        response = aexa.websets.imports.list(
             cursor=input_data.cursor,
             limit=input_data.limit,
         )
@@ -474,9 +474,7 @@ class ExaDeleteImportBlock(Block):
         # Use AsyncExa SDK
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        deleted_import = await aexa.websets.imports.delete(
-            import_id=input_data.import_id
-        )
+        deleted_import = aexa.websets.imports.delete(import_id=input_data.import_id)
 
         yield "import_id", deleted_import.id
         yield "success", "true"
@@ -575,14 +573,14 @@ class ExaExportWebsetBlock(Block):
             }
         )
 
-        # Create async iterator for list_all
-        async def async_item_iterator(*args, **kwargs):
-            for item in [mock_item1, mock_item2]:
-                yield item
+        # Create mock iterator
+        mock_items = [mock_item1, mock_item2]
 
         return {
             "_get_client": lambda *args, **kwargs: MagicMock(
-                websets=MagicMock(items=MagicMock(list_all=async_item_iterator))
+                websets=MagicMock(
+                    items=MagicMock(list_all=lambda *args, **kwargs: iter(mock_items))
+                )
             )
         }
 
@@ -604,7 +602,7 @@ class ExaExportWebsetBlock(Block):
                 webset_id=input_data.webset_id, limit=input_data.max_items
             )
 
-            async for sdk_item in item_iterator:
+            for sdk_item in item_iterator:
                 if len(all_items) >= input_data.max_items:
                     break
 

autogpt_platform/backend/backend/blocks/exa/websets_items.py

@@ -178,7 +178,7 @@ class ExaGetWebsetItemBlock(Block):
     ) -> BlockOutput:
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        sdk_item = await aexa.websets.items.get(
+        sdk_item = aexa.websets.items.get(
             webset_id=input_data.webset_id, id=input_data.item_id
         )
 
@@ -269,7 +269,7 @@ class ExaListWebsetItemsBlock(Block):
             response = None
 
             while time.time() - start_time < input_data.wait_timeout:
-                response = await aexa.websets.items.list(
+                response = aexa.websets.items.list(
                     webset_id=input_data.webset_id,
                     cursor=input_data.cursor,
                     limit=input_data.limit,
@@ -282,13 +282,13 @@ class ExaListWebsetItemsBlock(Block):
                 interval = min(interval * 1.2, 10)
 
             if not response:
-                response = await aexa.websets.items.list(
+                response = aexa.websets.items.list(
                     webset_id=input_data.webset_id,
                     cursor=input_data.cursor,
                     limit=input_data.limit,
                 )
         else:
-            response = await aexa.websets.items.list(
+            response = aexa.websets.items.list(
                 webset_id=input_data.webset_id,
                 cursor=input_data.cursor,
                 limit=input_data.limit,
@@ -340,7 +340,7 @@ class ExaDeleteWebsetItemBlock(Block):
     ) -> BlockOutput:
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        deleted_item = await aexa.websets.items.delete(
+        deleted_item = aexa.websets.items.delete(
             webset_id=input_data.webset_id, id=input_data.item_id
         )
 
@@ -408,7 +408,7 @@ class ExaBulkWebsetItemsBlock(Block):
             webset_id=input_data.webset_id, limit=input_data.max_items
         )
 
-        async for sdk_item in item_iterator:
+        for sdk_item in item_iterator:
             if len(all_items) >= input_data.max_items:
                 break
 
@@ -475,7 +475,7 @@ class ExaWebsetItemsSummaryBlock(Block):
         # Use AsyncExa SDK
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        webset = await aexa.websets.get(id=input_data.webset_id)
+        webset = aexa.websets.get(id=input_data.webset_id)
 
         entity_type = "unknown"
         if webset.searches:
@@ -495,7 +495,7 @@ class ExaWebsetItemsSummaryBlock(Block):
         # Get sample items if requested
         sample_items: List[WebsetItemModel] = []
         if input_data.sample_size > 0:
-            items_response = await aexa.websets.items.list(
+            items_response = aexa.websets.items.list(
                 webset_id=input_data.webset_id, limit=input_data.sample_size
             )
             # Convert to our stable models
@@ -569,7 +569,7 @@ class ExaGetNewItemsBlock(Block):
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
         # Get items starting from cursor
-        response = await aexa.websets.items.list(
+        response = aexa.websets.items.list(
             webset_id=input_data.webset_id,
             cursor=input_data.since_cursor,
             limit=input_data.max_items,

autogpt_platform/backend/backend/blocks/exa/websets_monitor.py

@@ -233,7 +233,7 @@ class ExaCreateMonitorBlock(Block):
     def _create_test_mock():
         """Create test mocks for the AsyncExa SDK."""
         from datetime import datetime
-        from unittest.mock import AsyncMock, MagicMock
+        from unittest.mock import MagicMock
 
         # Create mock SDK monitor object
         mock_monitor = MagicMock()
@@ -263,7 +263,7 @@ class ExaCreateMonitorBlock(Block):
         return {
             "_get_client": lambda *args, **kwargs: MagicMock(
                 websets=MagicMock(
-                    monitors=MagicMock(create=AsyncMock(return_value=mock_monitor))
+                    monitors=MagicMock(create=lambda *args, **kwargs: mock_monitor)
                 )
             )
         }
@@ -320,7 +320,7 @@ class ExaCreateMonitorBlock(Block):
         if input_data.metadata:
             payload["metadata"] = input_data.metadata
 
-        sdk_monitor = await aexa.websets.monitors.create(params=payload)
+        sdk_monitor = aexa.websets.monitors.create(params=payload)
 
         monitor = MonitorModel.from_sdk(sdk_monitor)
 
@@ -384,7 +384,7 @@ class ExaGetMonitorBlock(Block):
         # Use AsyncExa SDK
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        sdk_monitor = await aexa.websets.monitors.get(monitor_id=input_data.monitor_id)
+        sdk_monitor = aexa.websets.monitors.get(monitor_id=input_data.monitor_id)
 
         monitor = MonitorModel.from_sdk(sdk_monitor)
 
@@ -476,7 +476,7 @@ class ExaUpdateMonitorBlock(Block):
         if input_data.metadata is not None:
             payload["metadata"] = input_data.metadata
 
-        sdk_monitor = await aexa.websets.monitors.update(
+        sdk_monitor = aexa.websets.monitors.update(
             monitor_id=input_data.monitor_id, params=payload
         )
 
@@ -522,9 +522,7 @@ class ExaDeleteMonitorBlock(Block):
         # Use AsyncExa SDK
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        deleted_monitor = await aexa.websets.monitors.delete(
-            monitor_id=input_data.monitor_id
-        )
+        deleted_monitor = aexa.websets.monitors.delete(monitor_id=input_data.monitor_id)
 
         yield "monitor_id", deleted_monitor.id
         yield "success", "true"
@@ -581,7 +579,7 @@ class ExaListMonitorsBlock(Block):
         # Use AsyncExa SDK
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        response = await aexa.websets.monitors.list(
+        response = aexa.websets.monitors.list(
             cursor=input_data.cursor,
             limit=input_data.limit,
             webset_id=input_data.webset_id,

autogpt_platform/backend/backend/blocks/exa/websets_polling.py

@@ -121,7 +121,7 @@ class ExaWaitForWebsetBlock(Block):
                 WebsetTargetStatus.IDLE,
                 WebsetTargetStatus.ANY_COMPLETE,
             ]:
-                final_webset = await aexa.websets.wait_until_idle(
+                final_webset = aexa.websets.wait_until_idle(
                     id=input_data.webset_id,
                     timeout=input_data.timeout,
                     poll_interval=input_data.check_interval,
@@ -164,7 +164,7 @@ class ExaWaitForWebsetBlock(Block):
                 interval = input_data.check_interval
                 while time.time() - start_time < input_data.timeout:
                     # Get current webset status
-                    webset = await aexa.websets.get(id=input_data.webset_id)
+                    webset = aexa.websets.get(id=input_data.webset_id)
                     current_status = (
                         webset.status.value
                         if hasattr(webset.status, "value")
@@ -209,7 +209,7 @@ class ExaWaitForWebsetBlock(Block):
 
                 # Timeout reached
                 elapsed = time.time() - start_time
-                webset = await aexa.websets.get(id=input_data.webset_id)
+                webset = aexa.websets.get(id=input_data.webset_id)
                 final_status = (
                     webset.status.value
                     if hasattr(webset.status, "value")
@@ -345,7 +345,7 @@ class ExaWaitForSearchBlock(Block):
         try:
             while time.time() - start_time < input_data.timeout:
                 # Get current search status using SDK
-                search = await aexa.websets.searches.get(
+                search = aexa.websets.searches.get(
                     webset_id=input_data.webset_id, id=input_data.search_id
                 )
 
@@ -401,7 +401,7 @@ class ExaWaitForSearchBlock(Block):
             elapsed = time.time() - start_time
 
             # Get last known status
-            search = await aexa.websets.searches.get(
+            search = aexa.websets.searches.get(
                 webset_id=input_data.webset_id, id=input_data.search_id
             )
             final_status = (
@@ -503,7 +503,7 @@ class ExaWaitForEnrichmentBlock(Block):
         try:
             while time.time() - start_time < input_data.timeout:
                 # Get current enrichment status using SDK
-                enrichment = await aexa.websets.enrichments.get(
+                enrichment = aexa.websets.enrichments.get(
                     webset_id=input_data.webset_id, id=input_data.enrichment_id
                 )
 
@@ -548,7 +548,7 @@ class ExaWaitForEnrichmentBlock(Block):
             elapsed = time.time() - start_time
 
             # Get last known status
-            enrichment = await aexa.websets.enrichments.get(
+            enrichment = aexa.websets.enrichments.get(
                 webset_id=input_data.webset_id, id=input_data.enrichment_id
             )
             final_status = (
@@ -575,7 +575,7 @@ class ExaWaitForEnrichmentBlock(Block):
     ) -> tuple[list[SampleEnrichmentModel], int]:
         """Get sample enriched data and count."""
         # Get a few items to see enrichment results using SDK
-        response = await aexa.websets.items.list(webset_id=webset_id, limit=5)
+        response = aexa.websets.items.list(webset_id=webset_id, limit=5)
 
         sample_data: list[SampleEnrichmentModel] = []
         enriched_count = 0

autogpt_platform/backend/backend/blocks/exa/websets_search.py

@@ -317,7 +317,7 @@ class ExaCreateWebsetSearchBlock(Block):
 
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        sdk_search = await aexa.websets.searches.create(
+        sdk_search = aexa.websets.searches.create(
             webset_id=input_data.webset_id, params=payload
         )
 
@@ -350,7 +350,7 @@ class ExaCreateWebsetSearchBlock(Block):
             poll_start = time.time()
 
             while time.time() - poll_start < input_data.polling_timeout:
-                current_search = await aexa.websets.searches.get(
+                current_search = aexa.websets.searches.get(
                     webset_id=input_data.webset_id, id=search_id
                 )
                 current_status = (
@@ -442,7 +442,7 @@ class ExaGetWebsetSearchBlock(Block):
         # Use AsyncExa SDK
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        sdk_search = await aexa.websets.searches.get(
+        sdk_search = aexa.websets.searches.get(
             webset_id=input_data.webset_id, id=input_data.search_id
         )
 
@@ -523,7 +523,7 @@ class ExaCancelWebsetSearchBlock(Block):
         # Use AsyncExa SDK
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
-        canceled_search = await aexa.websets.searches.cancel(
+        canceled_search = aexa.websets.searches.cancel(
             webset_id=input_data.webset_id, id=input_data.search_id
         )
 
@@ -604,7 +604,7 @@ class ExaFindOrCreateSearchBlock(Block):
         aexa = AsyncExa(api_key=credentials.api_key.get_secret_value())
 
         # Get webset to check existing searches
-        webset = await aexa.websets.get(id=input_data.webset_id)
+        webset = aexa.websets.get(id=input_data.webset_id)
 
         # Look for existing search with same query
         existing_search = None
@@ -636,7 +636,7 @@ class ExaFindOrCreateSearchBlock(Block):
             if input_data.entity_type != SearchEntityType.AUTO:
                 payload["entity"] = {"type": input_data.entity_type.value}
 
-            sdk_search = await aexa.websets.searches.create(
+            sdk_search = aexa.websets.searches.create(
                 webset_id=input_data.webset_id, params=payload
             )
 

autogpt_platform/backend/backend/blocks/llm.py

@@ -596,10 +596,10 @@ def extract_openai_tool_calls(response) -> list[ToolContentBlock] | None:
 
 def get_parallel_tool_calls_param(
     llm_model: LlmModel, parallel_tool_calls: bool | None
-) -> bool | openai.Omit:
+):
     """Get the appropriate parallel_tool_calls parameter for OpenAI-compatible APIs."""
     if llm_model.startswith("o") or parallel_tool_calls is None:
-        return openai.omit
+        return openai.NOT_GIVEN
     return parallel_tool_calls
 
 

autogpt_platform/backend/backend/data/block.py

@@ -246,9 +246,7 @@ class BlockSchema(BaseModel):
                         f"is not of type {CredentialsMetaInput.__name__}"
                     )
 
-                CredentialsMetaInput.validate_credentials_field_schema(
-                    cls.get_field_schema(field_name), field_name
-                )
+                credentials_fields[field_name].validate_credentials_field_schema(cls)
 
             elif field_name in credentials_fields:
                 raise KeyError(

autogpt_platform/backend/backend/data/graph.py

@@ -3,7 +3,7 @@ import logging
 import uuid
 from collections import defaultdict
 from datetime import datetime, timezone
-from typing import TYPE_CHECKING, Annotated, Any, Literal, Optional, Self, cast
+from typing import TYPE_CHECKING, Annotated, Any, Literal, Optional, cast
 
 from prisma.enums import SubmissionStatus
 from prisma.models import (
@@ -20,7 +20,7 @@ from prisma.types import (
     AgentNodeLinkCreateInput,
     StoreListingVersionWhereInput,
 )
-from pydantic import BaseModel, BeforeValidator, Field
+from pydantic import BaseModel, BeforeValidator, Field, create_model
 from pydantic.fields import computed_field
 
 from backend.blocks.agent import AgentExecutorBlock
@@ -30,6 +30,7 @@ from backend.data.db import prisma as db
 from backend.data.dynamic_fields import is_tool_pin, sanitize_pin_name
 from backend.data.includes import MAX_GRAPH_VERSIONS_FETCH
 from backend.data.model import (
+    CredentialsField,
     CredentialsFieldInfo,
     CredentialsMetaInput,
     is_credentials_field_name,
@@ -44,6 +45,7 @@ from .block import (
     AnyBlockSchema,
     Block,
     BlockInput,
+    BlockSchema,
     BlockType,
     EmptySchema,
     get_block,
@@ -111,12 +113,10 @@ class Link(BaseDbModel):
 
 class Node(BaseDbModel):
     block_id: str
-    input_default: BlockInput = Field(  # dict[input_name, default_value]
-        default_factory=dict
-    )
-    metadata: dict[str, Any] = Field(default_factory=dict)
-    input_links: list[Link] = Field(default_factory=list)
-    output_links: list[Link] = Field(default_factory=list)
+    input_default: BlockInput = {}  # dict[input_name, default_value]
+    metadata: dict[str, Any] = {}
+    input_links: list[Link] = []
+    output_links: list[Link] = []
 
     @property
     def credentials_optional(self) -> bool:
@@ -221,33 +221,18 @@ class NodeModel(Node):
         return result
 
 
-class GraphBaseMeta(BaseDbModel):
-    """
-    Shared base for `GraphMeta` and `BaseGraph`, with core graph metadata fields.
-    """
-
+class BaseGraph(BaseDbModel):
     version: int = 1
     is_active: bool = True
     name: str
     description: str
     instructions: str | None = None
     recommended_schedule_cron: str | None = None
+    nodes: list[Node] = []
+    links: list[Link] = []
     forked_from_id: str | None = None
     forked_from_version: int | None = None
 
-
-class BaseGraph(GraphBaseMeta):
-    """
-    Graph with nodes, links, and computed I/O schema fields.
-
-    Used to represent sub-graphs within a `Graph`. Contains the full graph
-    structure including nodes and links, plus computed fields for schemas
-    and trigger info. Does NOT include user_id or created_at (see GraphModel).
-    """
-
-    nodes: list[Node] = Field(default_factory=list)
-    links: list[Link] = Field(default_factory=list)
-
     @computed_field
     @property
     def input_schema(self) -> dict[str, Any]:
@@ -376,79 +361,44 @@ class GraphTriggerInfo(BaseModel):
 
 
 class Graph(BaseGraph):
-    """Creatable graph model used in API create/update endpoints."""
-
-    sub_graphs: list[BaseGraph] = Field(default_factory=list)  # Flattened sub-graphs
-
-
-class GraphMeta(GraphBaseMeta):
-    """
-    Lightweight graph metadata model representing an existing graph from the database,
-    for use in listings and summaries.
-
-    Lacks `GraphModel`'s nodes, links, and expensive computed fields.
-    Use for list endpoints where full graph data is not needed and performance matters.
-    """
-
-    id: str  # type: ignore
-    version: int  # type: ignore
-    user_id: str
-    created_at: datetime
-
-    @classmethod
-    def from_db(cls, graph: "AgentGraph") -> Self:
-        return cls(
-            id=graph.id,
-            version=graph.version,
-            is_active=graph.isActive,
-            name=graph.name or "",
-            description=graph.description or "",
-            instructions=graph.instructions,
-            recommended_schedule_cron=graph.recommendedScheduleCron,
-            forked_from_id=graph.forkedFromId,
-            forked_from_version=graph.forkedFromVersion,
-            user_id=graph.userId,
-            created_at=graph.createdAt,
-        )
-
-
-class GraphModel(Graph, GraphMeta):
-    """
-    Full graph model representing an existing graph from the database.
-
-    This is the primary model for working with persisted graphs. Includes all
-    graph data (nodes, links, sub_graphs) plus user ownership and timestamps.
-    Provides computed fields (input_schema, output_schema, etc.) used during
-    set-up (frontend) and execution (backend).
-
-    Inherits from:
-    - `Graph`: provides structure (nodes, links, sub_graphs) and computed schemas
-    - `GraphMeta`: provides user_id, created_at for database records
-    """
-
-    nodes: list[NodeModel] = Field(default_factory=list)  # type: ignore
-
-    @property
-    def starting_nodes(self) -> list[NodeModel]:
-        outbound_nodes = {link.sink_id for link in self.links}
-        input_nodes = {
-            node.id for node in self.nodes if node.block.block_type == BlockType.INPUT
-        }
-        return [
-            node
-            for node in self.nodes
-            if node.id not in outbound_nodes or node.id in input_nodes
-        ]
-
-    @property
-    def webhook_input_node(self) -> NodeModel | None:  # type: ignore
-        return cast(NodeModel, super().webhook_input_node)
+    sub_graphs: list[BaseGraph] = []  # Flattened sub-graphs
 
     @computed_field
     @property
     def credentials_input_schema(self) -> dict[str, Any]:
-        graph_credentials_inputs = self.aggregate_credentials_inputs()
+        schema = self._credentials_input_schema.jsonschema()
 
+        # Determine which credential fields are required based on credentials_optional metadata
+        graph_credentials_inputs = self.aggregate_credentials_inputs()
+        required_fields = []
+
+        # Build a map of node_id -> node for quick lookup
+        all_nodes = {node.id: node for node in self.nodes}
+        for sub_graph in self.sub_graphs:
+            for node in sub_graph.nodes:
+                all_nodes[node.id] = node
+
+        for field_key, (
+            _field_info,
+            node_field_pairs,
+        ) in graph_credentials_inputs.items():
+            # A field is required if ANY node using it has credentials_optional=False
+            is_required = False
+            for node_id, _field_name in node_field_pairs:
+                node = all_nodes.get(node_id)
+                if node and not node.credentials_optional:
+                    is_required = True
+                    break
+
+            if is_required:
+                required_fields.append(field_key)
+
+        schema["required"] = required_fields
+        return schema
+
+    @property
+    def _credentials_input_schema(self) -> type[BlockSchema]:
+        graph_credentials_inputs = self.aggregate_credentials_inputs()
         logger.debug(
             f"Combined credentials input fields for graph #{self.id} ({self.name}): "
             f"{graph_credentials_inputs}"
@@ -456,8 +406,8 @@ class GraphModel(Graph, GraphMeta):
 
         # Warn if same-provider credentials inputs can't be combined (= bad UX)
         graph_cred_fields = list(graph_credentials_inputs.values())
-        for i, (field, keys, _) in enumerate(graph_cred_fields):
-            for other_field, other_keys, _ in list(graph_cred_fields)[i + 1 :]:
+        for i, (field, keys) in enumerate(graph_cred_fields):
+            for other_field, other_keys in list(graph_cred_fields)[i + 1 :]:
                 if field.provider != other_field.provider:
                     continue
                 if ProviderName.HTTP in field.provider:
@@ -473,78 +423,31 @@ class GraphModel(Graph, GraphMeta):
                     f"keys: {keys} <> {other_keys}."
                 )
 
-        # Build JSON schema directly to avoid expensive create_model + validation overhead
-        properties = {}
-        required_fields = []
-
-        for agg_field_key, (
-            field_info,
-            _,
-            is_required,
-        ) in graph_credentials_inputs.items():
-            providers = list(field_info.provider)
-            cred_types = list(field_info.supported_types)
-
-            field_schema: dict[str, Any] = {
-                "credentials_provider": providers,
-                "credentials_types": cred_types,
-                "type": "object",
-                "properties": {
-                    "id": {"title": "Id", "type": "string"},
-                    "title": {
-                        "anyOf": [{"type": "string"}, {"type": "null"}],
-                        "default": None,
-                        "title": "Title",
-                    },
-                    "provider": {
-                        "title": "Provider",
-                        "type": "string",
-                        **(
-                            {"enum": providers}
-                            if len(providers) > 1
-                            else {"const": providers[0]}
-                        ),
-                    },
-                    "type": {
-                        "title": "Type",
-                        "type": "string",
-                        **(
-                            {"enum": cred_types}
-                            if len(cred_types) > 1
-                            else {"const": cred_types[0]}
-                        ),
-                    },
-                },
-                "required": ["id", "provider", "type"],
-            }
-
-            # Add other (optional) field info items
-            field_schema.update(
-                field_info.model_dump(
-                    by_alias=True,
-                    exclude_defaults=True,
-                    exclude={"provider", "supported_types"},  # already included above
-                )
+        fields: dict[str, tuple[type[CredentialsMetaInput], CredentialsMetaInput]] = {
+            agg_field_key: (
+                CredentialsMetaInput[
+                    Literal[tuple(field_info.provider)],  # type: ignore
+                    Literal[tuple(field_info.supported_types)],  # type: ignore
+                ],
+                CredentialsField(
+                    required_scopes=set(field_info.required_scopes or []),
+                    discriminator=field_info.discriminator,
+                    discriminator_mapping=field_info.discriminator_mapping,
+                    discriminator_values=field_info.discriminator_values,
+                ),
             )
-
-            # Ensure field schema is well-formed
-            CredentialsMetaInput.validate_credentials_field_schema(
-                field_schema, agg_field_key
-            )
-
-            properties[agg_field_key] = field_schema
-            if is_required:
-                required_fields.append(agg_field_key)
-
-        return {
-            "type": "object",
-            "properties": properties,
-            "required": required_fields,
+            for agg_field_key, (field_info, _) in graph_credentials_inputs.items()
         }
 
+        return create_model(
+            self.name.replace(" ", "") + "CredentialsInputSchema",
+            __base__=BlockSchema,
+            **fields,  # type: ignore
+        )
+
     def aggregate_credentials_inputs(
         self,
-    ) -> dict[str, tuple[CredentialsFieldInfo, set[tuple[str, str]], bool]]:
+    ) -> dict[str, tuple[CredentialsFieldInfo, set[tuple[str, str]]]]:
         """
         Returns:
             dict[aggregated_field_key, tuple(
@@ -552,19 +455,13 @@ class GraphModel(Graph, GraphMeta):
                     (now includes discriminator_values from matching nodes)
                 set[(node_id, field_name)]: Node credentials fields that are
                     compatible with this aggregated field spec
-                bool: True if the field is required (any node has credentials_optional=False)
             )]
         """
         # First collect all credential field data with input defaults
-        # Track (field_info, (node_id, field_name), is_required) for each credential field
-        node_credential_data: list[tuple[CredentialsFieldInfo, tuple[str, str]]] = []
-        node_required_map: dict[str, bool] = {}  # node_id -> is_required
+        node_credential_data = []
 
         for graph in [self] + self.sub_graphs:
             for node in graph.nodes:
-                # Track if this node requires credentials (credentials_optional=False means required)
-                node_required_map[node.id] = not node.credentials_optional
-
                 for (
                     field_name,
                     field_info,
@@ -588,21 +485,37 @@ class GraphModel(Graph, GraphMeta):
                     )
 
         # Combine credential field info (this will merge discriminator_values automatically)
-        combined = CredentialsFieldInfo.combine(*node_credential_data)
+        return CredentialsFieldInfo.combine(*node_credential_data)
 
-        # Add is_required flag to each aggregated field
-        # A field is required if ANY node using it has credentials_optional=False
-        return {
-            key: (
-                field_info,
-                node_field_pairs,
-                any(
-                    node_required_map.get(node_id, True)
-                    for node_id, _ in node_field_pairs
-                ),
-            )
-            for key, (field_info, node_field_pairs) in combined.items()
+
+class GraphModel(Graph):
+    user_id: str
+    nodes: list[NodeModel] = []  # type: ignore
+
+    created_at: datetime
+
+    @property
+    def starting_nodes(self) -> list[NodeModel]:
+        outbound_nodes = {link.sink_id for link in self.links}
+        input_nodes = {
+            node.id for node in self.nodes if node.block.block_type == BlockType.INPUT
         }
+        return [
+            node
+            for node in self.nodes
+            if node.id not in outbound_nodes or node.id in input_nodes
+        ]
+
+    @property
+    def webhook_input_node(self) -> NodeModel | None:  # type: ignore
+        return cast(NodeModel, super().webhook_input_node)
+
+    def meta(self) -> "GraphMeta":
+        """
+        Returns a GraphMeta object with metadata about the graph.
+        This is used to return metadata about the graph without exposing nodes and links.
+        """
+        return GraphMeta.from_graph(self)
 
     def reassign_ids(self, user_id: str, reassign_graph_id: bool = False):
         """
@@ -886,14 +799,13 @@ class GraphModel(Graph, GraphMeta):
             if is_static_output_block(link.source_id):
                 link.is_static = True  # Each value block output should be static.
 
-    @classmethod
-    def from_db(  # type: ignore[reportIncompatibleMethodOverride]
-        cls,
+    @staticmethod
+    def from_db(
         graph: AgentGraph,
         for_export: bool = False,
         sub_graphs: list[AgentGraph] | None = None,
-    ) -> Self:
-        return cls(
+    ) -> "GraphModel":
+        return GraphModel(
             id=graph.id,
             user_id=graph.userId if not for_export else "",
             version=graph.version,
@@ -919,28 +831,17 @@ class GraphModel(Graph, GraphMeta):
             ],
         )
 
-    def hide_nodes(self) -> "GraphModelWithoutNodes":
-        """
-        Returns a copy of the `GraphModel` with nodes, links, and sub-graphs hidden
-        (excluded from serialization). They are still present in the model instance
-        so all computed fields (e.g. `credentials_input_schema`) still work.
-        """
-        return GraphModelWithoutNodes.model_validate(self, from_attributes=True)
 
+class GraphMeta(Graph):
+    user_id: str
 
-class GraphModelWithoutNodes(GraphModel):
-    """
-    GraphModel variant that excludes nodes, links, and sub-graphs from serialization.
+    # Easy work-around to prevent exposing nodes and links in the API response
+    nodes: list[NodeModel] = Field(default=[], exclude=True)  # type: ignore
+    links: list[Link] = Field(default=[], exclude=True)
 
-    Used in contexts like the store where exposing internal graph structure
-    is not desired. Inherits all computed fields from GraphModel but marks
-    nodes and links as excluded from JSON output.
-    """
-
-    nodes: list[NodeModel] = Field(default_factory=list, exclude=True)
-    links: list[Link] = Field(default_factory=list, exclude=True)
-
-    sub_graphs: list[BaseGraph] = Field(default_factory=list, exclude=True)
+    @staticmethod
+    def from_graph(graph: GraphModel) -> "GraphMeta":
+        return GraphMeta(**graph.model_dump())
 
 
 class GraphsPaginated(BaseModel):
@@ -1011,11 +912,21 @@ async def list_graphs_paginated(
         where=where_clause,
         distinct=["id"],
         order={"version": "desc"},
+        include=AGENT_GRAPH_INCLUDE,
         skip=offset,
         take=page_size,
     )
 
-    graph_models = [GraphMeta.from_db(graph) for graph in graphs]
+    graph_models: list[GraphMeta] = []
+    for graph in graphs:
+        try:
+            graph_meta = GraphModel.from_db(graph).meta()
+            # Trigger serialization to validate that the graph is well formed
+            graph_meta.model_dump()
+            graph_models.append(graph_meta)
+        except Exception as e:
+            logger.error(f"Error processing graph {graph.id}: {e}")
+            continue
 
     return GraphsPaginated(
         graphs=graph_models,

autogpt_platform/backend/backend/data/model.py

@@ -163,6 +163,7 @@ class User(BaseModel):
 if TYPE_CHECKING:
     from prisma.models import User as PrismaUser
 
+    from backend.data.block import BlockSchema
 
 T = TypeVar("T")
 logger = logging.getLogger(__name__)
@@ -507,13 +508,15 @@ class CredentialsMetaInput(BaseModel, Generic[CP, CT]):
     def allowed_cred_types(cls) -> tuple[CredentialsType, ...]:
         return get_args(cls.model_fields["type"].annotation)
 
-    @staticmethod
-    def validate_credentials_field_schema(
-        field_schema: dict[str, Any], field_name: str
-    ):
+    @classmethod
+    def validate_credentials_field_schema(cls, model: type["BlockSchema"]):
         """Validates the schema of a credentials input field"""
+        field_name = next(
+            name for name, type in model.get_credentials_fields().items() if type is cls
+        )
+        field_schema = model.jsonschema()["properties"][field_name]
         try:
-            field_info = CredentialsFieldInfo[CP, CT].model_validate(field_schema)
+            schema_extra = CredentialsFieldInfo[CP, CT].model_validate(field_schema)
         except ValidationError as e:
             if "Field required [type=missing" not in str(e):
                 raise
@@ -523,11 +526,11 @@ class CredentialsMetaInput(BaseModel, Generic[CP, CT]):
                 f"{field_schema}"
             ) from e
 
-        providers = field_info.provider
+        providers = cls.allowed_providers()
         if (
             providers is not None
             and len(providers) > 1
-            and not field_info.discriminator
+            and not schema_extra.discriminator
         ):
             raise TypeError(
                 f"Multi-provider CredentialsField '{field_name}' "

autogpt_platform/backend/backend/executor/utils.py

@@ -373,7 +373,7 @@ def make_node_credentials_input_map(
     # Get aggregated credentials fields for the graph
     graph_cred_inputs = graph.aggregate_credentials_inputs()
 
-    for graph_input_name, (_, compatible_node_fields, _) in graph_cred_inputs.items():
+    for graph_input_name, (_, compatible_node_fields) in graph_cred_inputs.items():
         # Best-effort map: skip missing items
         if graph_input_name not in graph_credentials_input:
             continue

autogpt_platform/backend/backend/util/workspace.py

@@ -188,7 +188,6 @@ class WorkspaceManager:
                 f"{Config().max_file_size_mb}MB limit"
             )
 
-        # Virus scan content before persisting (defense in depth)
         await scan_content_safe(content, filename=filename)
 
         # Determine path with session scoping

autogpt_platform/backend/pyproject.toml

@@ -21,7 +21,7 @@ cryptography = "^45.0"
 discord-py = "^2.5.2"
 e2b-code-interpreter = "^1.5.2"
 elevenlabs = "^1.50.0"
-fastapi = "^0.128.0"
+fastapi = "^0.116.1"
 feedparser = "^6.0.11"
 flake8 = "^7.3.0"
 google-api-python-client = "^2.177.0"
@@ -35,7 +35,7 @@ jinja2 = "^3.1.6"
 jsonref = "^1.1.0"
 jsonschema = "^4.25.0"
 langfuse = "^3.11.0"
-launchdarkly-server-sdk = "^9.14.1"
+launchdarkly-server-sdk = "^9.12.0"
 mem0ai = "^0.1.115"
 moviepy = "^2.1.2"
 ollama = "^0.5.1"
@@ -52,8 +52,8 @@ prometheus-client = "^0.22.1"
 prometheus-fastapi-instrumentator = "^7.0.0"
 psutil = "^7.0.0"
 psycopg2-binary = "^2.9.10"
-pydantic = { extras = ["email"], version = "^2.12.5" }
-pydantic-settings = "^2.12.0"
+pydantic = { extras = ["email"], version = "^2.11.7" }
+pydantic-settings = "^2.10.1"
 pytest = "^8.4.1"
 pytest-asyncio = "^1.1.0"
 python-dotenv = "^1.1.1"
@@ -65,11 +65,11 @@ sentry-sdk = {extras = ["anthropic", "fastapi", "launchdarkly", "openai", "sqlal
 sqlalchemy = "^2.0.40"
 strenum = "^0.4.9"
 stripe = "^11.5.0"
-supabase = "2.27.2"
+supabase = "2.17.0"
 tenacity = "^9.1.2"
 todoist-api-python = "^2.1.7"
 tweepy = "^4.16.0"
-uvicorn = { extras = ["standard"], version = "^0.40.0" }
+uvicorn = { extras = ["standard"], version = "^0.35.0" }
 websockets = "^15.0"
 youtube-transcript-api = "^1.2.1"
 yt-dlp = "2025.12.08"

autogpt_platform/backend/snapshots/grph_single

@@ -3,6 +3,7 @@
   "credentials_input_schema": {
     "properties": {},
     "required": [],
+    "title": "TestGraphCredentialsInputSchema",
     "type": "object"
   },
   "description": "A test graph",

autogpt_platform/backend/snapshots/grphs_all

@@ -1,14 +1,34 @@
 [
   {
-    "created_at": "2025-09-04T13:37:00",
+    "credentials_input_schema": {
+      "properties": {},
+      "required": [],
+      "title": "TestGraphCredentialsInputSchema",
+      "type": "object"
+    },
     "description": "A test graph",
     "forked_from_id": null,
     "forked_from_version": null,
+    "has_external_trigger": false,
+    "has_human_in_the_loop": false,
+    "has_sensitive_action": false,
     "id": "graph-123",
+    "input_schema": {
+      "properties": {},
+      "required": [],
+      "type": "object"
+    },
     "instructions": null,
     "is_active": true,
     "name": "Test Graph",
+    "output_schema": {
+      "properties": {},
+      "required": [],
+      "type": "object"
+    },
     "recommended_schedule_cron": null,
+    "sub_graphs": [],
+    "trigger_setup_info": null,
     "user_id": "3e53486c-cf57-477e-ba2a-cb02dc828e1a",
     "version": 1
   }

autogpt_platform/frontend/src/app/(no-navbar)/onboarding/5-run/components/AgentOnboardingCredentials/AgentOnboardingCredentials.tsx

@@ -1,5 +1,5 @@
 import { CredentialsMetaInput } from "@/app/api/__generated__/models/credentialsMetaInput";
-import { GraphModel } from "@/app/api/__generated__/models/graphModel";
+import { GraphMeta } from "@/app/api/__generated__/models/graphMeta";
 import { CredentialsInput } from "@/components/contextual/CredentialsInput/CredentialsInput";
 import { useState } from "react";
 import { getSchemaDefaultCredentials } from "../../helpers";
@@ -9,7 +9,7 @@ type Credential = CredentialsMetaInput | undefined;
 type Credentials = Record<string, Credential>;
 
 type Props = {
-  agent: GraphModel | null;
+  agent: GraphMeta | null;
   siblingInputs?: Record<string, any>;
   onCredentialsChange: (
     credentials: Record<string, CredentialsMetaInput>,

autogpt_platform/frontend/src/app/(no-navbar)/onboarding/5-run/components/AgentOnboardingCredentials/helpers.ts

@@ -1,9 +1,9 @@
 import { CredentialsMetaInput } from "@/app/api/__generated__/models/credentialsMetaInput";
-import { GraphModel } from "@/app/api/__generated__/models/graphModel";
+import { GraphMeta } from "@/app/api/__generated__/models/graphMeta";
 import { BlockIOCredentialsSubSchema } from "@/lib/autogpt-server-api/types";
 
 export function getCredentialFields(
-  agent: GraphModel | null,
+  agent: GraphMeta | null,
 ): AgentCredentialsFields {
   if (!agent) return {};
 

autogpt_platform/frontend/src/app/(no-navbar)/onboarding/5-run/helpers.ts

@@ -3,10 +3,10 @@ import type {
   CredentialsMetaInput,
 } from "@/lib/autogpt-server-api/types";
 import type { InputValues } from "./types";
-import { GraphModel } from "@/app/api/__generated__/models/graphModel";
+import { GraphMeta } from "@/app/api/__generated__/models/graphMeta";
 
 export function computeInitialAgentInputs(
-  agent: GraphModel | null,
+  agent: GraphMeta | null,
   existingInputs?: InputValues | null,
 ): InputValues {
   const properties = agent?.input_schema?.properties || {};
@@ -29,7 +29,7 @@ export function computeInitialAgentInputs(
 }
 
 type IsRunDisabledParams = {
-  agent: GraphModel | null;
+  agent: GraphMeta | null;
   isRunning: boolean;
   agentInputs: InputValues | null | undefined;
 };

autogpt_platform/frontend/src/app/(platform)/build/components/legacy-builder/BlocksControl.tsx

@@ -30,8 +30,6 @@ import {
 } from "@/components/atoms/Tooltip/BaseTooltip";
 import { GraphMeta } from "@/lib/autogpt-server-api";
 import jaro from "jaro-winkler";
-import { getV1GetSpecificGraph } from "@/app/api/__generated__/endpoints/graphs/graphs";
-import { okData } from "@/app/api/helpers";
 
 type _Block = Omit<Block, "inputSchema" | "outputSchema"> & {
   uiKey?: string;
@@ -109,8 +107,6 @@ export function BlocksControl({
       .filter((b) => b.uiType !== BlockUIType.AGENT)
       .sort((a, b) => a.name.localeCompare(b.name));
 
-    // Agent blocks are created from GraphMeta which doesn't include schemas.
-    // Schemas will be fetched on-demand when the block is actually added.
     const agentBlockList = flows
       .map((flow): _Block => {
         return {
@@ -120,9 +116,8 @@ export function BlocksControl({
             `Ver.${flow.version}` +
             (flow.description ? ` | ${flow.description}` : ""),
           categories: [{ category: "AGENT", description: "" }],
-          // Empty schemas - will be populated when block is added
-          inputSchema: { type: "object", properties: {} },
-          outputSchema: { type: "object", properties: {} },
+          inputSchema: flow.input_schema,
+          outputSchema: flow.output_schema,
           staticOutput: false,
           uiType: BlockUIType.AGENT,
           costs: [],
@@ -130,7 +125,8 @@ export function BlocksControl({
           hardcodedValues: {
             graph_id: flow.id,
             graph_version: flow.version,
-            // Schemas will be fetched on-demand when block is added
+            input_schema: flow.input_schema,
+            output_schema: flow.output_schema,
           },
         };
       })
@@ -186,37 +182,6 @@ export function BlocksControl({
     setSelectedCategory(null);
   }, []);
 
-  // Handler to add a block, fetching graph data on-demand for agent blocks
-  const handleAddBlock = useCallback(
-    async (block: _Block & { notAvailable: string | null }) => {
-      if (block.notAvailable) return;
-
-      // For agent blocks, fetch the full graph to get schemas
-      if (block.uiType === BlockUIType.AGENT && block.hardcodedValues) {
-        const graphID = block.hardcodedValues.graph_id as string;
-        const graphVersion = block.hardcodedValues.graph_version as number;
-        const graphData = okData(
-          await getV1GetSpecificGraph(graphID, { version: graphVersion }),
-        );
-
-        if (graphData) {
-          addBlock(block.id, block.name, {
-            ...block.hardcodedValues,
-            input_schema: graphData.input_schema,
-            output_schema: graphData.output_schema,
-          });
-        } else {
-          // Fallback: add without schemas (will be incomplete)
-          console.error("Failed to fetch graph data for agent block");
-          addBlock(block.id, block.name, block.hardcodedValues || {});
-        }
-      } else {
-        addBlock(block.id, block.name, block.hardcodedValues || {});
-      }
-    },
-    [addBlock],
-  );
-
   // Extract unique categories from blocks
   const categories = useMemo(() => {
     return Array.from(
@@ -338,7 +303,10 @@ export function BlocksControl({
                       }),
                     );
                   }}
-                  onClick={() => handleAddBlock(block)}
+                  onClick={() =>
+                    !block.notAvailable &&
+                    addBlock(block.id, block.name, block?.hardcodedValues || {})
+                  }
                   title={block.notAvailable ?? undefined}
                 >
                   <div

autogpt_platform/frontend/src/app/(platform)/build/components/legacy-builder/Flow/Flow.tsx

@@ -29,17 +29,13 @@ import "@xyflow/react/dist/style.css";
 import { ConnectedEdge, CustomNode } from "../CustomNode/CustomNode";
 import "./flow.css";
 import {
-  BlockIORootSchema,
   BlockUIType,
   formatEdgeID,
   GraphExecutionID,
   GraphID,
   GraphMeta,
   LibraryAgent,
-  SpecialBlockID,
 } from "@/lib/autogpt-server-api";
-import { getV1GetSpecificGraph } from "@/app/api/__generated__/endpoints/graphs/graphs";
-import { okData } from "@/app/api/helpers";
 import { IncompatibilityInfo } from "../../../hooks/useSubAgentUpdate/types";
 import { Key, storage } from "@/services/storage/local-storage";
 import { findNewlyAddedBlockCoordinates, getTypeColor } from "@/lib/utils";
@@ -691,94 +687,8 @@ const FlowEditor: React.FC<{
     [getNode, updateNode, nodes],
   );
 
-  /* Shared helper to create and add a node */
-  const createAndAddNode = useCallback(
-    async (
-      blockID: string,
-      blockName: string,
-      hardcodedValues: Record<string, any>,
-      position: { x: number; y: number },
-    ): Promise<CustomNode | null> => {
-      const nodeSchema = availableBlocks.find((node) => node.id === blockID);
-      if (!nodeSchema) {
-        console.error(`Schema not found for block ID: ${blockID}`);
-        return null;
-      }
-
-      // For agent blocks, fetch the full graph to get schemas
-      let inputSchema: BlockIORootSchema = nodeSchema.inputSchema;
-      let outputSchema: BlockIORootSchema = nodeSchema.outputSchema;
-      let finalHardcodedValues = hardcodedValues;
-
-      if (blockID === SpecialBlockID.AGENT) {
-        const graphID = hardcodedValues.graph_id as string;
-        const graphVersion = hardcodedValues.graph_version as number;
-        const graphData = okData(
-          await getV1GetSpecificGraph(graphID, { version: graphVersion }),
-        );
-
-        if (graphData) {
-          inputSchema = graphData.input_schema as BlockIORootSchema;
-          outputSchema = graphData.output_schema as BlockIORootSchema;
-          finalHardcodedValues = {
-            ...hardcodedValues,
-            input_schema: graphData.input_schema,
-            output_schema: graphData.output_schema,
-          };
-        } else {
-          console.error("Failed to fetch graph data for agent block");
-        }
-      }
-
-      const newNode: CustomNode = {
-        id: nodeId.toString(),
-        type: "custom",
-        position,
-        data: {
-          blockType: blockName,
-          blockCosts: nodeSchema.costs || [],
-          title: `${blockName} ${nodeId}`,
-          description: nodeSchema.description,
-          categories: nodeSchema.categories,
-          inputSchema: inputSchema,
-          outputSchema: outputSchema,
-          hardcodedValues: finalHardcodedValues,
-          connections: [],
-          isOutputOpen: false,
-          block_id: blockID,
-          isOutputStatic: nodeSchema.staticOutput,
-          uiType: nodeSchema.uiType,
-        },
-      };
-
-      addNodes(newNode);
-      setNodeId((prevId) => prevId + 1);
-      clearNodesStatusAndOutput();
-
-      history.push({
-        type: "ADD_NODE",
-        payload: { node: { ...newNode, ...newNode.data } },
-        undo: () => deleteElements({ nodes: [{ id: newNode.id }] }),
-        redo: () => addNodes(newNode),
-      });
-
-      return newNode;
-    },
-    [
-      availableBlocks,
-      nodeId,
-      addNodes,
-      deleteElements,
-      clearNodesStatusAndOutput,
-    ],
-  );
-
   const addNode = useCallback(
-    async (
-      blockId: string,
-      nodeType: string,
-      hardcodedValues: Record<string, any> = {},
-    ) => {
+    (blockId: string, nodeType: string, hardcodedValues: any = {}) => {
       const nodeSchema = availableBlocks.find((node) => node.id === blockId);
       if (!nodeSchema) {
         console.error(`Schema not found for block ID: ${blockId}`);
@@ -797,42 +707,73 @@ const FlowEditor: React.FC<{
       // Alternative: We could also use D3 force, Intersection for this (React flow Pro examples)
 
       const { x, y } = getViewport();
-      const position =
+      const viewportCoordinates =
         nodeDimensions && Object.keys(nodeDimensions).length > 0
-          ? findNewlyAddedBlockCoordinates(
+          ? // we will get all the dimension of nodes, then store
+            findNewlyAddedBlockCoordinates(
               nodeDimensions,
               nodeSchema.uiType == BlockUIType.NOTE ? 300 : 500,
               60,
               1.0,
             )
-          : {
+          : // we will get all the dimension of nodes, then store
+            {
               x: window.innerWidth / 2 - x,
               y: window.innerHeight / 2 - y,
             };
 
-      const newNode = await createAndAddNode(
-        blockId,
-        nodeType,
-        hardcodedValues,
-        position,
-      );
-      if (!newNode) return;
+      const newNode: CustomNode = {
+        id: nodeId.toString(),
+        type: "custom",
+        position: viewportCoordinates, // Set the position to the calculated viewport center
+        data: {
+          blockType: nodeType,
+          blockCosts: nodeSchema.costs,
+          title: `${nodeType} ${nodeId}`,
+          description: nodeSchema.description,
+          categories: nodeSchema.categories,
+          inputSchema: nodeSchema.inputSchema,
+          outputSchema: nodeSchema.outputSchema,
+          hardcodedValues: hardcodedValues,
+          connections: [],
+          isOutputOpen: false,
+          block_id: blockId,
+          isOutputStatic: nodeSchema.staticOutput,
+          uiType: nodeSchema.uiType,
+        },
+      };
+
+      addNodes(newNode);
+      setNodeId((prevId) => prevId + 1);
+      clearNodesStatusAndOutput(); // Clear status and output when a new node is added
 
       setViewport(
         {
-          x: -position.x * 0.8 + (window.innerWidth - 0.0) / 2,
-          y: -position.y * 0.8 + (window.innerHeight - 400) / 2,
+          // Rough estimate of the dimension of the node is: 500x400px.
+          // Though we skip shifting the X, considering the block menu side-bar.
+          x: -viewportCoordinates.x * 0.8 + (window.innerWidth - 0.0) / 2,
+          y: -viewportCoordinates.y * 0.8 + (window.innerHeight - 400) / 2,
           zoom: 0.8,
         },
         { duration: 500 },
       );
+
+      history.push({
+        type: "ADD_NODE",
+        payload: { node: { ...newNode, ...newNode.data } },
+        undo: () => deleteElements({ nodes: [{ id: newNode.id }] }),
+        redo: () => addNodes(newNode),
+      });
     },
     [
+      nodeId,
       getViewport,
       setViewport,
       availableBlocks,
+      addNodes,
       nodeDimensions,
-      createAndAddNode,
+      deleteElements,
+      clearNodesStatusAndOutput,
     ],
   );
 
@@ -979,7 +920,7 @@ const FlowEditor: React.FC<{
   }, []);
 
   const onDrop = useCallback(
-    async (event: React.DragEvent) => {
+    (event: React.DragEvent) => {
       event.preventDefault();
 
       const blockData = event.dataTransfer.getData("application/reactflow");
@@ -994,17 +935,62 @@ const FlowEditor: React.FC<{
           y: event.clientY,
         });
 
-        await createAndAddNode(
-          blockId,
-          blockName,
-          hardcodedValues || {},
+        // Find the block schema
+        const nodeSchema = availableBlocks.find((node) => node.id === blockId);
+        if (!nodeSchema) {
+          console.error(`Schema not found for block ID: ${blockId}`);
+          return;
+        }
+
+        // Create the new node at the drop position
+        const newNode: CustomNode = {
+          id: nodeId.toString(),
+          type: "custom",
           position,
-        );
+          data: {
+            blockType: blockName,
+            blockCosts: nodeSchema.costs || [],
+            title: `${blockName} ${nodeId}`,
+            description: nodeSchema.description,
+            categories: nodeSchema.categories,
+            inputSchema: nodeSchema.inputSchema,
+            outputSchema: nodeSchema.outputSchema,
+            hardcodedValues: hardcodedValues,
+            connections: [],
+            isOutputOpen: false,
+            block_id: blockId,
+            uiType: nodeSchema.uiType,
+          },
+        };
+
+        history.push({
+          type: "ADD_NODE",
+          payload: { node: { ...newNode, ...newNode.data } },
+          undo: () => {
+            deleteElements({ nodes: [{ id: newNode.id } as any], edges: [] });
+          },
+          redo: () => {
+            addNodes([newNode]);
+          },
+        });
+        addNodes([newNode]);
+        clearNodesStatusAndOutput();
+
+        setNodeId((prevId) => prevId + 1);
       } catch (error) {
         console.error("Failed to drop block:", error);
       }
     },
-    [screenToFlowPosition, createAndAddNode],
+    [
+      nodeId,
+      availableBlocks,
+      nodes,
+      edges,
+      addNodes,
+      screenToFlowPosition,
+      deleteElements,
+      clearNodesStatusAndOutput,
+    ],
   );
 
   const buildContextValue: BuilderContextType = useMemo(

autogpt_platform/frontend/src/app/(platform)/build/components/legacy-builder/RunnerInputUI.tsx

@@ -4,13 +4,13 @@ import { AgentRunDraftView } from "@/app/(platform)/library/agents/[id]/componen
 import { Dialog } from "@/components/molecules/Dialog/Dialog";
 import type {
   CredentialsMetaInput,
-  Graph,
+  GraphMeta,
 } from "@/lib/autogpt-server-api/types";
 
 interface RunInputDialogProps {
   isOpen: boolean;
   doClose: () => void;
-  graph: Graph;
+  graph: GraphMeta;
   doRun?: (
     inputs: Record<string, any>,
     credentialsInputs: Record<string, CredentialsMetaInput>,

autogpt_platform/frontend/src/app/(platform)/build/components/legacy-builder/RunnerUIWrapper.tsx

@@ -9,13 +9,13 @@ import { CustomNodeData } from "@/app/(platform)/build/components/legacy-builder
 import {
   BlockUIType,
   CredentialsMetaInput,
-  Graph,
+  GraphMeta,
 } from "@/lib/autogpt-server-api/types";
 import RunnerOutputUI, { OutputNodeInfo } from "./RunnerOutputUI";
 import { RunnerInputDialog } from "./RunnerInputUI";
 
 interface RunnerUIWrapperProps {
-  graph: Graph;
+  graph: GraphMeta;
   nodes: Node<CustomNodeData>[];
   graphExecutionError?: string | null;
   saveAndRun: (

autogpt_platform/frontend/src/app/(platform)/build/hooks/useSubAgentUpdate/helpers.ts

@@ -1,5 +1,5 @@
 import { GraphInputSchema } from "@/lib/autogpt-server-api";
-import { GraphLike, IncompatibilityInfo } from "./types";
+import { GraphMetaLike, IncompatibilityInfo } from "./types";
 
 // Helper type for schema properties - the generated types are too loose
 type SchemaProperties = Record<string, GraphInputSchema["properties"][string]>;
@@ -36,7 +36,7 @@ export function getSchemaRequired(schema: unknown): SchemaRequired {
  */
 export function createUpdatedAgentNodeInputs(
   currentInputs: Record<string, unknown>,
-  latestSubGraphVersion: GraphLike,
+  latestSubGraphVersion: GraphMetaLike,
 ): Record<string, unknown> {
   return {
     ...currentInputs,

autogpt_platform/frontend/src/app/(platform)/build/hooks/useSubAgentUpdate/types.ts

@@ -1,11 +1,7 @@
-import type {
-  Graph as LegacyGraph,
-  GraphMeta as LegacyGraphMeta,
-} from "@/lib/autogpt-server-api";
-import type { GraphModel as GeneratedGraph } from "@/app/api/__generated__/models/graphModel";
+import type { GraphMeta as LegacyGraphMeta } from "@/lib/autogpt-server-api";
 import type { GraphMeta as GeneratedGraphMeta } from "@/app/api/__generated__/models/graphMeta";
 
-export type SubAgentUpdateInfo<T extends GraphLike = GraphLike> = {
+export type SubAgentUpdateInfo<T extends GraphMetaLike = GraphMetaLike> = {
   hasUpdate: boolean;
   currentVersion: number;
   latestVersion: number;
@@ -14,10 +10,7 @@ export type SubAgentUpdateInfo<T extends GraphLike = GraphLike> = {
   incompatibilities: IncompatibilityInfo | null;
 };
 
-// Union type for Graph (with schemas) that works with both legacy and new builder
-export type GraphLike = LegacyGraph | GeneratedGraph;
-
-// Union type for GraphMeta (without schemas) for version detection
+// Union type for GraphMeta that works with both legacy and new builder
 export type GraphMetaLike = LegacyGraphMeta | GeneratedGraphMeta;
 
 export type IncompatibilityInfo = {

autogpt_platform/frontend/src/app/(platform)/build/hooks/useSubAgentUpdate/useSubAgentUpdate.ts

@@ -1,11 +1,5 @@
 import { useMemo } from "react";
-import type {
-  GraphInputSchema,
-  GraphOutputSchema,
-} from "@/lib/autogpt-server-api";
-import type { GraphModel } from "@/app/api/__generated__/models/graphModel";
-import { useGetV1GetSpecificGraph } from "@/app/api/__generated__/endpoints/graphs/graphs";
-import { okData } from "@/app/api/helpers";
+import { GraphInputSchema, GraphOutputSchema } from "@/lib/autogpt-server-api";
 import { getEffectiveType } from "@/lib/utils";
 import { EdgeLike, getSchemaProperties, getSchemaRequired } from "./helpers";
 import {
@@ -17,38 +11,26 @@ import {
 /**
  * Checks if a newer version of a sub-agent is available and determines compatibility
  */
-export function useSubAgentUpdate(
+export function useSubAgentUpdate<T extends GraphMetaLike>(
   nodeID: string,
   graphID: string | undefined,
   graphVersion: number | undefined,
   currentInputSchema: GraphInputSchema | undefined,
   currentOutputSchema: GraphOutputSchema | undefined,
   connections: EdgeLike[],
-  availableGraphs: GraphMetaLike[],
-): SubAgentUpdateInfo<GraphModel> {
+  availableGraphs: T[],
+): SubAgentUpdateInfo<T> {
   // Find the latest version of the same graph
-  const latestGraphInfo = useMemo(() => {
+  const latestGraph = useMemo(() => {
     if (!graphID) return null;
     return availableGraphs.find((graph) => graph.id === graphID) || null;
   }, [graphID, availableGraphs]);
 
-  // Check if there's a newer version available
+  // Check if there's an update available
   const hasUpdate = useMemo(() => {
-    if (!latestGraphInfo || graphVersion === undefined) return false;
-    return latestGraphInfo.version! > graphVersion;
-  }, [latestGraphInfo, graphVersion]);
-
-  // Fetch full graph IF an update is detected
-  const { data: latestGraph } = useGetV1GetSpecificGraph(
-    graphID ?? "",
-    { version: latestGraphInfo?.version },
-    {
-      query: {
-        enabled: hasUpdate && !!graphID && !!latestGraphInfo?.version,
-        select: okData,
-      },
-    },
-  );
+    if (!latestGraph || graphVersion === undefined) return false;
+    return latestGraph.version! > graphVersion;
+  }, [latestGraph, graphVersion]);
 
   // Get connected input and output handles for this specific node
   const connectedHandles = useMemo(() => {
@@ -170,8 +152,8 @@ export function useSubAgentUpdate(
   return {
     hasUpdate,
     currentVersion: graphVersion || 0,
-    latestVersion: latestGraphInfo?.version || 0,
-    latestGraph: latestGraph || null,
+    latestVersion: latestGraph?.version || 0,
+    latestGraph,
     isCompatible: compatibilityResult.isCompatible,
     incompatibilities: compatibilityResult.incompatibilities,
   };

autogpt_platform/frontend/src/app/(platform)/build/stores/graphStore.ts

@@ -18,7 +18,7 @@ interface GraphStore {
     outputSchema: Record<string, any> | null,
   ) => void;
 
-  // Available graphs; used for sub-graph updated version detection
+  // Available graphs; used for sub-graph updates
   availableSubGraphs: GraphMeta[];
   setAvailableSubGraphs: (graphs: GraphMeta[]) => void;
 

autogpt_platform/frontend/src/app/(platform)/library/agents/[id]/components/OldAgentLibraryView/components/agent-run-draft-view.tsx

@@ -10,8 +10,8 @@ import React, {
 import {
   CredentialsMetaInput,
   CredentialsType,
-  Graph,
   GraphExecutionID,
+  GraphMeta,
   LibraryAgentPreset,
   LibraryAgentPresetID,
   LibraryAgentPresetUpdatable,
@@ -69,7 +69,7 @@ export function AgentRunDraftView({
   className,
   recommendedScheduleCron,
 }: {
-  graph: Graph;
+  graph: GraphMeta;
   agentActions?: ButtonAction[];
   recommendedScheduleCron?: string | null;
   doRun?: (

autogpt_platform/frontend/src/app/(platform)/library/agents/[id]/components/OldAgentLibraryView/components/agent-schedule-details-view.tsx

@@ -2,8 +2,8 @@
 import React, { useCallback, useMemo } from "react";
 
 import {
-  Graph,
   GraphExecutionID,
+  GraphMeta,
   Schedule,
   ScheduleID,
 } from "@/lib/autogpt-server-api";
@@ -35,7 +35,7 @@ export function AgentScheduleDetailsView({
   onForcedRun,
   doDeleteSchedule,
 }: {
-  graph: Graph;
+  graph: GraphMeta;
   schedule: Schedule;
   agentActions: ButtonAction[];
   onForcedRun: (runID: GraphExecutionID) => void;

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

@@ -5629,9 +5629,7 @@
             "description": "Successful Response",
             "content": {
               "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/GraphModelWithoutNodes"
-                }
+                "schema": { "$ref": "#/components/schemas/GraphMeta" }
               }
             }
           },
@@ -6497,6 +6495,18 @@
             "anyOf": [{ "type": "string" }, { "type": "null" }],
             "title": "Recommended Schedule Cron"
           },
+          "nodes": {
+            "items": { "$ref": "#/components/schemas/Node" },
+            "type": "array",
+            "title": "Nodes",
+            "default": []
+          },
+          "links": {
+            "items": { "$ref": "#/components/schemas/Link" },
+            "type": "array",
+            "title": "Links",
+            "default": []
+          },
           "forked_from_id": {
             "anyOf": [{ "type": "string" }, { "type": "null" }],
             "title": "Forked From Id"
@@ -6504,22 +6514,11 @@
           "forked_from_version": {
             "anyOf": [{ "type": "integer" }, { "type": "null" }],
             "title": "Forked From Version"
-          },
-          "nodes": {
-            "items": { "$ref": "#/components/schemas/Node" },
-            "type": "array",
-            "title": "Nodes"
-          },
-          "links": {
-            "items": { "$ref": "#/components/schemas/Link" },
-            "type": "array",
-            "title": "Links"
           }
         },
         "type": "object",
         "required": ["name", "description"],
-        "title": "BaseGraph",
-        "description": "Graph with nodes, links, and computed I/O schema fields.\n\nUsed to represent sub-graphs within a `Graph`. Contains the full graph\nstructure including nodes and links, plus computed fields for schemas\nand trigger info. Does NOT include user_id or created_at (see GraphModel)."
+        "title": "BaseGraph"
       },
       "BaseGraph-Output": {
         "properties": {
@@ -6540,6 +6539,18 @@
             "anyOf": [{ "type": "string" }, { "type": "null" }],
             "title": "Recommended Schedule Cron"
           },
+          "nodes": {
+            "items": { "$ref": "#/components/schemas/Node" },
+            "type": "array",
+            "title": "Nodes",
+            "default": []
+          },
+          "links": {
+            "items": { "$ref": "#/components/schemas/Link" },
+            "type": "array",
+            "title": "Links",
+            "default": []
+          },
           "forked_from_id": {
             "anyOf": [{ "type": "string" }, { "type": "null" }],
             "title": "Forked From Id"
@@ -6548,16 +6559,6 @@
             "anyOf": [{ "type": "integer" }, { "type": "null" }],
             "title": "Forked From Version"
           },
-          "nodes": {
-            "items": { "$ref": "#/components/schemas/Node" },
-            "type": "array",
-            "title": "Nodes"
-          },
-          "links": {
-            "items": { "$ref": "#/components/schemas/Link" },
-            "type": "array",
-            "title": "Links"
-          },
           "input_schema": {
             "additionalProperties": true,
             "type": "object",
@@ -6604,8 +6605,7 @@
           "has_sensitive_action",
           "trigger_setup_info"
         ],
-        "title": "BaseGraph",
-        "description": "Graph with nodes, links, and computed I/O schema fields.\n\nUsed to represent sub-graphs within a `Graph`. Contains the full graph\nstructure including nodes and links, plus computed fields for schemas\nand trigger info. Does NOT include user_id or created_at (see GraphModel)."
+        "title": "BaseGraph"
       },
       "BlockCategoryResponse": {
         "properties": {
@@ -7399,6 +7399,18 @@
             "anyOf": [{ "type": "string" }, { "type": "null" }],
             "title": "Recommended Schedule Cron"
           },
+          "nodes": {
+            "items": { "$ref": "#/components/schemas/Node" },
+            "type": "array",
+            "title": "Nodes",
+            "default": []
+          },
+          "links": {
+            "items": { "$ref": "#/components/schemas/Link" },
+            "type": "array",
+            "title": "Links",
+            "default": []
+          },
           "forked_from_id": {
             "anyOf": [{ "type": "string" }, { "type": "null" }],
             "title": "Forked From Id"
@@ -7407,26 +7419,16 @@
             "anyOf": [{ "type": "integer" }, { "type": "null" }],
             "title": "Forked From Version"
           },
-          "nodes": {
-            "items": { "$ref": "#/components/schemas/Node" },
-            "type": "array",
-            "title": "Nodes"
-          },
-          "links": {
-            "items": { "$ref": "#/components/schemas/Link" },
-            "type": "array",
-            "title": "Links"
-          },
           "sub_graphs": {
             "items": { "$ref": "#/components/schemas/BaseGraph-Input" },
             "type": "array",
-            "title": "Sub Graphs"
+            "title": "Sub Graphs",
+            "default": []
           }
         },
         "type": "object",
         "required": ["name", "description"],
-        "title": "Graph",
-        "description": "Creatable graph model used in API create/update endpoints."
+        "title": "Graph"
       },
       "GraphExecution": {
         "properties": {
@@ -7778,7 +7780,7 @@
       "GraphMeta": {
         "properties": {
           "id": { "type": "string", "title": "Id" },
-          "version": { "type": "integer", "title": "Version" },
+          "version": { "type": "integer", "title": "Version", "default": 1 },
           "is_active": {
             "type": "boolean",
             "title": "Is Active",
@@ -7802,24 +7804,68 @@
             "anyOf": [{ "type": "integer" }, { "type": "null" }],
             "title": "Forked From Version"
           },
+          "sub_graphs": {
+            "items": { "$ref": "#/components/schemas/BaseGraph-Output" },
+            "type": "array",
+            "title": "Sub Graphs",
+            "default": []
+          },
           "user_id": { "type": "string", "title": "User Id" },
-          "created_at": {
-            "type": "string",
-            "format": "date-time",
-            "title": "Created At"
+          "input_schema": {
+            "additionalProperties": true,
+            "type": "object",
+            "title": "Input Schema",
+            "readOnly": true
+          },
+          "output_schema": {
+            "additionalProperties": true,
+            "type": "object",
+            "title": "Output Schema",
+            "readOnly": true
+          },
+          "has_external_trigger": {
+            "type": "boolean",
+            "title": "Has External Trigger",
+            "readOnly": true
+          },
+          "has_human_in_the_loop": {
+            "type": "boolean",
+            "title": "Has Human In The Loop",
+            "readOnly": true
+          },
+          "has_sensitive_action": {
+            "type": "boolean",
+            "title": "Has Sensitive Action",
+            "readOnly": true
+          },
+          "trigger_setup_info": {
+            "anyOf": [
+              { "$ref": "#/components/schemas/GraphTriggerInfo" },
+              { "type": "null" }
+            ],
+            "readOnly": true
+          },
+          "credentials_input_schema": {
+            "additionalProperties": true,
+            "type": "object",
+            "title": "Credentials Input Schema",
+            "readOnly": true
           }
         },
         "type": "object",
         "required": [
-          "id",
-          "version",
           "name",
           "description",
           "user_id",
-          "created_at"
+          "input_schema",
+          "output_schema",
+          "has_external_trigger",
+          "has_human_in_the_loop",
+          "has_sensitive_action",
+          "trigger_setup_info",
+          "credentials_input_schema"
         ],
-        "title": "GraphMeta",
-        "description": "Lightweight graph metadata model representing an existing graph from the database,\nfor use in listings and summaries.\n\nLacks `GraphModel`'s nodes, links, and expensive computed fields.\nUse for list endpoints where full graph data is not needed and performance matters."
+        "title": "GraphMeta"
       },
       "GraphModel": {
         "properties": {
@@ -7840,111 +7886,17 @@
             "anyOf": [{ "type": "string" }, { "type": "null" }],
             "title": "Recommended Schedule Cron"
           },
-          "forked_from_id": {
-            "anyOf": [{ "type": "string" }, { "type": "null" }],
-            "title": "Forked From Id"
-          },
-          "forked_from_version": {
-            "anyOf": [{ "type": "integer" }, { "type": "null" }],
-            "title": "Forked From Version"
-          },
-          "user_id": { "type": "string", "title": "User Id" },
-          "created_at": {
-            "type": "string",
-            "format": "date-time",
-            "title": "Created At"
-          },
           "nodes": {
             "items": { "$ref": "#/components/schemas/NodeModel" },
             "type": "array",
-            "title": "Nodes"
+            "title": "Nodes",
+            "default": []
           },
           "links": {
             "items": { "$ref": "#/components/schemas/Link" },
             "type": "array",
-            "title": "Links"
-          },
-          "sub_graphs": {
-            "items": { "$ref": "#/components/schemas/BaseGraph-Output" },
-            "type": "array",
-            "title": "Sub Graphs"
-          },
-          "input_schema": {
-            "additionalProperties": true,
-            "type": "object",
-            "title": "Input Schema",
-            "readOnly": true
-          },
-          "output_schema": {
-            "additionalProperties": true,
-            "type": "object",
-            "title": "Output Schema",
-            "readOnly": true
-          },
-          "has_external_trigger": {
-            "type": "boolean",
-            "title": "Has External Trigger",
-            "readOnly": true
-          },
-          "has_human_in_the_loop": {
-            "type": "boolean",
-            "title": "Has Human In The Loop",
-            "readOnly": true
-          },
-          "has_sensitive_action": {
-            "type": "boolean",
-            "title": "Has Sensitive Action",
-            "readOnly": true
-          },
-          "trigger_setup_info": {
-            "anyOf": [
-              { "$ref": "#/components/schemas/GraphTriggerInfo" },
-              { "type": "null" }
-            ],
-            "readOnly": true
-          },
-          "credentials_input_schema": {
-            "additionalProperties": true,
-            "type": "object",
-            "title": "Credentials Input Schema",
-            "readOnly": true
-          }
-        },
-        "type": "object",
-        "required": [
-          "name",
-          "description",
-          "user_id",
-          "created_at",
-          "input_schema",
-          "output_schema",
-          "has_external_trigger",
-          "has_human_in_the_loop",
-          "has_sensitive_action",
-          "trigger_setup_info",
-          "credentials_input_schema"
-        ],
-        "title": "GraphModel",
-        "description": "Full graph model representing an existing graph from the database.\n\nThis is the primary model for working with persisted graphs. Includes all\ngraph data (nodes, links, sub_graphs) plus user ownership and timestamps.\nProvides computed fields (input_schema, output_schema, etc.) used during\nset-up (frontend) and execution (backend).\n\nInherits from:\n- `Graph`: provides structure (nodes, links, sub_graphs) and computed schemas\n- `GraphMeta`: provides user_id, created_at for database records"
-      },
-      "GraphModelWithoutNodes": {
-        "properties": {
-          "id": { "type": "string", "title": "Id" },
-          "version": { "type": "integer", "title": "Version", "default": 1 },
-          "is_active": {
-            "type": "boolean",
-            "title": "Is Active",
-            "default": true
-          },
-          "name": { "type": "string", "title": "Name" },
-          "description": { "type": "string", "title": "Description" },
-          "instructions": {
-            "anyOf": [{ "type": "string" }, { "type": "null" }],
-            "title": "Instructions"
-          },
-          "recommended_schedule_cron": {
-            "anyOf": [{ "type": "string" }, { "type": "null" }],
-            "title": "Recommended Schedule Cron"
+            "title": "Links",
+            "default": []
           },
           "forked_from_id": {
             "anyOf": [{ "type": "string" }, { "type": "null" }],
@@ -7954,6 +7906,12 @@
             "anyOf": [{ "type": "integer" }, { "type": "null" }],
             "title": "Forked From Version"
           },
+          "sub_graphs": {
+            "items": { "$ref": "#/components/schemas/BaseGraph-Output" },
+            "type": "array",
+            "title": "Sub Graphs",
+            "default": []
+          },
           "user_id": { "type": "string", "title": "User Id" },
           "created_at": {
             "type": "string",
@@ -8015,8 +7973,7 @@
           "trigger_setup_info",
           "credentials_input_schema"
         ],
-        "title": "GraphModelWithoutNodes",
-        "description": "GraphModel variant that excludes nodes, links, and sub-graphs from serialization.\n\nUsed in contexts like the store where exposing internal graph structure\nis not desired. Inherits all computed fields from GraphModel but marks\nnodes and links as excluded from JSON output."
+        "title": "GraphModel"
       },
       "GraphSettings": {
         "properties": {
@@ -8656,22 +8613,26 @@
           "input_default": {
             "additionalProperties": true,
             "type": "object",
-            "title": "Input Default"
+            "title": "Input Default",
+            "default": {}
           },
           "metadata": {
             "additionalProperties": true,
             "type": "object",
-            "title": "Metadata"
+            "title": "Metadata",
+            "default": {}
           },
           "input_links": {
             "items": { "$ref": "#/components/schemas/Link" },
             "type": "array",
-            "title": "Input Links"
+            "title": "Input Links",
+            "default": []
           },
           "output_links": {
             "items": { "$ref": "#/components/schemas/Link" },
             "type": "array",
-            "title": "Output Links"
+            "title": "Output Links",
+            "default": []
           }
         },
         "type": "object",
@@ -8751,22 +8712,26 @@
           "input_default": {
             "additionalProperties": true,
             "type": "object",
-            "title": "Input Default"
+            "title": "Input Default",
+            "default": {}
           },
           "metadata": {
             "additionalProperties": true,
             "type": "object",
-            "title": "Metadata"
+            "title": "Metadata",
+            "default": {}
           },
           "input_links": {
             "items": { "$ref": "#/components/schemas/Link" },
             "type": "array",
-            "title": "Input Links"
+            "title": "Input Links",
+            "default": []
           },
           "output_links": {
             "items": { "$ref": "#/components/schemas/Link" },
             "type": "array",
-            "title": "Output Links"
+            "title": "Output Links",
+            "default": []
           },
           "graph_id": { "type": "string", "title": "Graph Id" },
           "graph_version": { "type": "integer", "title": "Graph Version" },
@@ -12307,9 +12272,7 @@
             "title": "Location"
           },
           "msg": { "type": "string", "title": "Message" },
-          "type": { "type": "string", "title": "Error Type" },
-          "input": { "title": "Input" },
-          "ctx": { "type": "object", "title": "Context" }
+          "type": { "type": "string", "title": "Error Type" }
         },
         "type": "object",
         "required": ["loc", "msg", "type"],

autogpt_platform/frontend/src/lib/autogpt-server-api/types.ts

@@ -362,14 +362,25 @@ export type GraphMeta = {
   user_id: UserID;
   version: number;
   is_active: boolean;
-  created_at: Date;
   name: string;
   description: string;
   instructions?: string | null;
   recommended_schedule_cron: string | null;
   forked_from_id?: GraphID | null;
   forked_from_version?: number | null;
-};
+  input_schema: GraphInputSchema;
+  output_schema: GraphOutputSchema;
+  credentials_input_schema: CredentialsInputSchema;
+} & (
+  | {
+      has_external_trigger: true;
+      trigger_setup_info: GraphTriggerInfo;
+    }
+  | {
+      has_external_trigger: false;
+      trigger_setup_info: null;
+    }
+);
 
 export type GraphID = Brand<string, "GraphID">;
 
@@ -436,22 +447,11 @@ export type GraphTriggerInfo = {
 
 /* Mirror of backend/data/graph.py:Graph */
 export type Graph = GraphMeta & {
+  created_at: Date;
   nodes: Node[];
   links: Link[];
   sub_graphs: Omit<Graph, "sub_graphs">[]; // Flattened sub-graphs
-  input_schema: GraphInputSchema;
-  output_schema: GraphOutputSchema;
-  credentials_input_schema: CredentialsInputSchema;
-} & (
-    | {
-        has_external_trigger: true;
-        trigger_setup_info: GraphTriggerInfo;
-      }
-    | {
-        has_external_trigger: false;
-        trigger_setup_info: null;
-      }
-  );
+};
 
 export type GraphUpdateable = Omit<
   Graph,

docs/platform/workspace-media-architecture.md

@@ -0,0 +1,325 @@
+# Workspace & Media File Architecture
+
+This document describes the architecture for handling user files in AutoGPT Platform, covering persistent user storage (Workspace) and ephemeral media processing pipelines.
+
+## Overview
+
+The platform has two distinct file-handling layers:
+
+| Layer | Purpose | Persistence | Scope |
+|-------|---------|-------------|-------|
+| **Workspace** | Long-term user file storage | Persistent (DB + GCS/local) | Per-user, session-scoped access |
+| **Media Pipeline** | Ephemeral file processing for blocks | Temporary (local disk) | Per-execution |
+
+## Database Models
+
+### UserWorkspace
+
+Represents a user's file storage space. Created on-demand (one per user).
+
+```prisma
+model UserWorkspace {
+  id        String   @id @default(uuid())
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  userId    String   @unique
+  Files     UserWorkspaceFile[]
+}
+```
+
+**Key points:**
+- One workspace per user (enforced by `@unique` on `userId`)
+- Created lazily via `get_or_create_workspace()` 
+- Uses upsert to handle race conditions
+
+### UserWorkspaceFile
+
+Represents a file stored in a user's workspace.
+
+```prisma
+model UserWorkspaceFile {
+  id          String    @id @default(uuid())
+  workspaceId String
+  name        String    // User-visible filename
+  path        String    // Virtual path (e.g., "/sessions/abc123/image.png")
+  storagePath String    // Actual storage path (gcs://... or local://...)
+  mimeType    String
+  sizeBytes   BigInt
+  checksum    String?   // SHA256 for integrity
+  isDeleted   Boolean   @default(false)
+  deletedAt   DateTime?
+  metadata    Json      @default("{}")
+
+  @@unique([workspaceId, path])  // Enforce unique paths within workspace
+}
+```
+
+**Key points:**
+- `path` is a virtual path for organizing files (not actual filesystem path)
+- `storagePath` contains the actual GCS or local storage location
+- Soft-delete pattern: `isDeleted` flag with `deletedAt` timestamp
+- Path is modified on delete to free up the virtual path for reuse
+
+---
+
+## WorkspaceManager
+
+**Location:** `backend/util/workspace.py`
+
+High-level API for workspace file operations. Combines storage backend operations with database record management.
+
+### Initialization
+
+```python
+from backend.util.workspace import WorkspaceManager
+
+# Basic usage
+manager = WorkspaceManager(user_id="user-123", workspace_id="ws-456")
+
+# With session scoping (CoPilot sessions)
+manager = WorkspaceManager(
+    user_id="user-123",
+    workspace_id="ws-456", 
+    session_id="session-789"
+)
+```
+
+### Session Scoping
+
+When `session_id` is provided, files are isolated to `/sessions/{session_id}/`:
+
+```python
+# With session_id="abc123":
+manager.write_file(content, "image.png")  
+# → stored at /sessions/abc123/image.png
+
+# Cross-session access is explicit:
+manager.read_file("/sessions/other-session/file.txt")  # Works
+```
+
+**Why session scoping?**
+- CoPilot conversations need file isolation
+- Prevents file collisions between concurrent sessions
+- Allows session cleanup without affecting other sessions
+
+### Core Methods
+
+| Method | Description |
+|--------|-------------|
+| `write_file(content, filename, path?, mime_type?, overwrite?)` | Write file to workspace |
+| `read_file(path)` | Read file by virtual path |
+| `read_file_by_id(file_id)` | Read file by ID |
+| `list_files(path?, limit?, offset?, include_all_sessions?)` | List files |
+| `delete_file(file_id)` | Soft-delete a file |
+| `get_download_url(file_id, expires_in?)` | Get signed download URL |
+| `get_file_info(file_id)` | Get file metadata |
+| `get_file_count(path?, include_all_sessions?)` | Count files |
+
+### Storage Backends
+
+WorkspaceManager delegates to `WorkspaceStorageBackend`:
+
+| Backend | When Used | Storage Path Format |
+|---------|-----------|---------------------|
+| `GCSWorkspaceStorage` | `media_gcs_bucket_name` is configured | `gcs://bucket/workspaces/{ws_id}/{file_id}/{filename}` |
+| `LocalWorkspaceStorage` | No GCS bucket configured | `local://{ws_id}/{file_id}/{filename}` |
+
+---
+
+## store_media_file()
+
+**Location:** `backend/util/file.py`
+
+The media normalization pipeline. Handles various input types and normalizes them for processing or output.
+
+### Purpose
+
+Blocks receive files in many formats (URLs, data URIs, workspace references, local paths). `store_media_file()` normalizes these to a consistent format based on what the block needs.
+
+### Input Types Handled
+
+| Input Format | Example | How It's Processed |
+|--------------|---------|-------------------|
+| Data URI | `data:image/png;base64,iVBOR...` | Decoded, virus scanned, written locally |
+| HTTP(S) URL | `https://example.com/image.png` | Downloaded, virus scanned, written locally |
+| Workspace URI | `workspace://abc123` or `workspace:///path/to/file` | Read from workspace, virus scanned, written locally |
+| Cloud path | `gcs://bucket/path` | Downloaded, virus scanned, written locally |
+| Local path | `image.png` | Verified to exist in exec_file directory |
+
+### Return Formats
+
+The `return_format` parameter determines what you get back:
+
+```python
+from backend.util.file import store_media_file
+
+# For local processing (ffmpeg, MoviePy, PIL)
+local_path = await store_media_file(
+    file=input_file,
+    execution_context=ctx,
+    return_format="for_local_processing"
+)
+# Returns: "image.png" (relative path in exec_file dir)
+
+# For external APIs (Replicate, OpenAI, etc.)
+data_uri = await store_media_file(
+    file=input_file,
+    execution_context=ctx,
+    return_format="for_external_api"
+)
+# Returns: "data:image/png;base64,iVBOR..."
+
+# For block output (adapts to execution context)
+output = await store_media_file(
+    file=input_file,
+    execution_context=ctx,
+    return_format="for_block_output"
+)
+# In CoPilot: Returns "workspace://file-id#image/png"
+# In graphs:  Returns "data:image/png;base64,..."
+```
+
+### Execution Context
+
+`store_media_file()` requires an `ExecutionContext` with:
+- `graph_exec_id` - Required for temp file location
+- `user_id` - Required for workspace access
+- `workspace_id` - Optional; enables workspace features
+- `session_id` - Optional; for session scoping in CoPilot
+
+---
+
+## Responsibility Boundaries
+
+### Virus Scanning
+
+| Component | Scans? | Notes |
+|-----------|--------|-------|
+| `store_media_file()` | ✅ Yes | Scans **all** content before writing to local disk |
+| `WorkspaceManager.write_file()` | ✅ Yes | Scans content before persisting |
+
+**Scanning happens at:**
+1. `store_media_file()` — scans everything it downloads/decodes
+2. `WorkspaceManager.write_file()` — scans before persistence
+
+Tools like `WriteWorkspaceFileTool` don't need to scan because `WorkspaceManager.write_file()` handles it.
+
+### Persistence
+
+| Component | Persists To | Lifecycle |
+|-----------|-------------|-----------|
+| `store_media_file()` | Temp dir (`/tmp/exec_file/{exec_id}/`) | Cleaned after execution |
+| `WorkspaceManager` | GCS or local storage + DB | Persistent until deleted |
+
+**Automatic cleanup:** `clean_exec_files(graph_exec_id)` removes temp files after execution completes.
+
+---
+
+## Decision Tree: WorkspaceManager vs store_media_file
+
+```
+┌─────────────────────────────────────────────────────┐
+│ What do you need to do with the file?               │
+└─────────────────────────────────────────────────────┘
+                         │
+           ┌─────────────┴─────────────┐
+           ▼                           ▼
+    Process in a block          Store for user access
+    (ffmpeg, PIL, etc.)         (CoPilot files, uploads)
+           │                           │
+           ▼                           ▼
+    store_media_file()           WorkspaceManager
+    with appropriate             
+    return_format                
+           │                           
+           │                           
+    ┌──────┴──────┐                    
+    ▼             ▼                    
+ "for_local_   "for_block_             
+ processing"   output"                 
+    │             │                    
+    ▼             ▼                    
+ Get local    Auto-saves to            
+ path for     workspace in             
+ tools        CoPilot context          
+```
+
+### Quick Reference
+
+| Scenario | Use |
+|----------|-----|
+| Block needs to process a file with ffmpeg | `store_media_file(..., return_format="for_local_processing")` |
+| Block needs to send file to external API | `store_media_file(..., return_format="for_external_api")` |
+| Block returning a generated file | `store_media_file(..., return_format="for_block_output")` |
+| API endpoint handling file upload | `WorkspaceManager.write_file()` (after virus scan) |
+| API endpoint serving file download | `WorkspaceManager.get_download_url()` |
+| Listing user's files | `WorkspaceManager.list_files()` |
+
+---
+
+## Key Files Reference
+
+| File | Purpose |
+|------|---------|
+| `backend/data/workspace.py` | Database CRUD operations for UserWorkspace and UserWorkspaceFile |
+| `backend/util/workspace.py` | `WorkspaceManager` class - high-level workspace API |
+| `backend/util/workspace_storage.py` | Storage backends (GCS, local) and `WorkspaceStorageBackend` interface |
+| `backend/util/file.py` | `store_media_file()` and media processing utilities |
+| `backend/util/virus_scanner.py` | `VirusScannerService` and `scan_content_safe()` |
+| `schema.prisma` | Database model definitions |
+
+---
+
+## Common Patterns
+
+### Block Processing a User's File
+
+```python
+async def run(self, input_data, *, execution_context, **kwargs):
+    # Normalize input to local path
+    local_path = await store_media_file(
+        file=input_data.video,
+        execution_context=execution_context,
+        return_format="for_local_processing",
+    )
+    
+    # Process with local tools
+    output_path = process_video(local_path)
+    
+    # Return (auto-saves to workspace in CoPilot)
+    result = await store_media_file(
+        file=output_path,
+        execution_context=execution_context,
+        return_format="for_block_output",
+    )
+    yield "output", result
+```
+
+### API Upload Endpoint
+
+```python
+async def upload_file(file: UploadFile, user_id: str, workspace_id: str):
+    content = await file.read()
+    
+    # write_file handles virus scanning
+    manager = WorkspaceManager(user_id, workspace_id)
+    workspace_file = await manager.write_file(
+        content=content,
+        filename=file.filename,
+    )
+    
+    return {"file_id": workspace_file.id}
+```
+
+---
+
+## Configuration
+
+| Setting | Purpose | Default |
+|---------|---------|---------|
+| `media_gcs_bucket_name` | GCS bucket for workspace storage | None (uses local) |
+| `workspace_storage_dir` | Local storage directory | `{app_data}/workspaces` |
+| `max_file_size_mb` | Maximum file size in MB | 100 |
+| `clamav_service_enabled` | Enable virus scanning | true |
+| `clamav_service_host` | ClamAV daemon host | localhost |
+| `clamav_service_port` | ClamAV daemon port | 3310 |