fix(frontend): use case-insensitive regex in getBlockCardByName

beautifyString capitalizes each word (e.g. "Add To Dictionary") but
tests may pass names with different casing (e.g. "Add to Dictionary").
Playwright hasText with a string is case-insensitive but with a regex
it is case-sensitive, so add the "i" flag.

autogpt_platform/backend/backend/blocks/github/commits.py

@@ -11,10 +11,7 @@ from backend.blocks._base import (
     BlockSchemaInput,
     BlockSchemaOutput,
 )
-from backend.data.execution import ExecutionContext
 from backend.data.model import SchemaField
-from backend.util.file import parse_data_uri, resolve_media_content
-from backend.util.type import MediaFileType
 
 from ._api import get_api
 from ._auth import (
@@ -181,8 +178,7 @@ class FileOperation(StrEnum):
 
 class FileOperationInput(TypedDict):
     path: str
-    # MediaFileType is a str NewType — no runtime breakage for existing callers.
-    content: MediaFileType
+    content: str
     operation: FileOperation
 
 
@@ -279,11 +275,11 @@ class GithubMultiFileCommitBlock(Block):
         base_tree_sha = commit_data["tree"]["sha"]
 
         # 3. Build tree entries for each file operation (blobs created concurrently)
-        async def _create_blob(content: str, encoding: str = "utf-8") -> str:
+        async def _create_blob(content: str) -> str:
             blob_url = repo_url + "/git/blobs"
             blob_response = await api.post(
                 blob_url,
-                json={"content": content, "encoding": encoding},
+                json={"content": content, "encoding": "utf-8"},
             )
             return blob_response.json()["sha"]
 
@@ -305,19 +301,10 @@ class GithubMultiFileCommitBlock(Block):
             else:
                 upsert_files.append((path, file_op.get("content", "")))
 
-        # Create all blobs concurrently. Data URIs (from store_media_file)
-        # are sent as base64 blobs to preserve binary content.
+        # Create all blobs concurrently
         if upsert_files:
-
-            async def _make_blob(content: str) -> str:
-                parsed = parse_data_uri(content)
-                if parsed is not None:
-                    _, b64_payload = parsed
-                    return await _create_blob(b64_payload, encoding="base64")
-                return await _create_blob(content)
-
             blob_shas = await asyncio.gather(
-                *[_make_blob(content) for _, content in upsert_files]
+                *[_create_blob(content) for _, content in upsert_files]
             )
             for (path, _), blob_sha in zip(upsert_files, blob_shas):
                 tree_entries.append(
@@ -371,36 +358,15 @@ class GithubMultiFileCommitBlock(Block):
         input_data: Input,
         *,
         credentials: GithubCredentials,
-        execution_context: ExecutionContext,
         **kwargs,
     ) -> BlockOutput:
         try:
-            # Resolve media references (workspace://, data:, URLs) to data
-            # URIs so _make_blob can send binary content correctly.
-            resolved_files: list[FileOperationInput] = []
-            for file_op in input_data.files:
-                content = file_op.get("content", "")
-                operation = FileOperation(file_op.get("operation", "upsert"))
-                if operation != FileOperation.DELETE:
-                    content = await resolve_media_content(
-                        MediaFileType(content),
-                        execution_context,
-                        return_format="for_external_api",
-                    )
-                resolved_files.append(
-                    FileOperationInput(
-                        path=file_op["path"],
-                        content=MediaFileType(content),
-                        operation=operation,
-                    )
-                )
-
             sha, url = await self.multi_file_commit(
                 credentials,
                 input_data.repo_url,
                 input_data.branch,
                 input_data.commit_message,
-                resolved_files,
+                input_data.files,
             )
             yield "sha", sha
             yield "url", url

autogpt_platform/backend/backend/blocks/github/test_github_blocks.py

@@ -8,7 +8,6 @@ from backend.blocks.github.pull_requests import (
     GithubMergePullRequestBlock,
     prepare_pr_api_url,
 )
-from backend.data.execution import ExecutionContext
 from backend.util.exceptions import BlockExecutionError
 
 # ── prepare_pr_api_url tests ──
@@ -98,11 +97,7 @@ async def test_multi_file_commit_error_path():
         "credentials": TEST_CREDENTIALS_INPUT,
     }
     with pytest.raises(BlockExecutionError, match="ref update failed"):
-        async for _ in block.execute(
-            input_data,
-            credentials=TEST_CREDENTIALS,
-            execution_context=ExecutionContext(),
-        ):
+        async for _ in block.execute(input_data, credentials=TEST_CREDENTIALS):
             pass
 
 

autogpt_platform/backend/backend/copilot/context.py

@@ -11,8 +11,6 @@ from contextvars import ContextVar
 from typing import TYPE_CHECKING
 
 from backend.copilot.model import ChatSession
-from backend.data.db_accessors import workspace_db
-from backend.util.workspace import WorkspaceManager
 
 if TYPE_CHECKING:
     from e2b import AsyncSandbox
@@ -84,17 +82,6 @@ def resolve_sandbox_path(path: str) -> str:
     return normalized
 
 
-async def get_workspace_manager(user_id: str, session_id: str) -> WorkspaceManager:
-    """Create a session-scoped :class:`WorkspaceManager`.
-
-    Placed here (rather than in ``tools/workspace_files``) so that modules
-    like ``sdk/file_ref`` can import it without triggering the heavy
-    ``tools/__init__`` import chain.
-    """
-    workspace = await workspace_db().get_or_create_workspace(user_id)
-    return WorkspaceManager(user_id, workspace.id, session_id)
-
-
 def is_allowed_local_path(path: str, sdk_cwd: str | None = None) -> bool:
     """Return True if *path* is within an allowed host-filesystem location.
 

autogpt_platform/backend/backend/copilot/prompting.py

@@ -11,18 +11,34 @@ from backend.copilot.tools import TOOL_REGISTRY
 # Shared technical notes that apply to both SDK and baseline modes
 _SHARED_TOOL_NOTES = """\
 
-### Sharing files
-After `write_workspace_file`, embed the `download_url` in Markdown:
-- File: `[report.csv](workspace://file_id#text/csv)`
-- Image: `![chart](workspace://file_id#image/png)`
-- Video: `![recording](workspace://file_id#video/mp4)`
+### Sharing files with the user
+After saving a file to the persistent workspace with `write_workspace_file`,
+share it with the user by embedding the `download_url` from the response in
+your message as a Markdown link or image:
 
-### File references — @@agptfile:
-Pass large file content to tools by reference: `@@agptfile:<uri>[<start>-<end>]`
-- `workspace://<file_id>` or `workspace:///<path>` — workspace files
-- `/absolute/path` — local/sandbox files
-- `[start-end]` — optional 1-indexed line range
-- Multiple refs per argument supported. Only `workspace://` and absolute paths are expanded.
+- **Any file** — shows as a clickable download link:
+  `[report.csv](workspace://file_id#text/csv)`
+- **Image** — renders inline in chat:
+  `![chart](workspace://file_id#image/png)`
+- **Video** — renders inline in chat with player controls:
+  `![recording](workspace://file_id#video/mp4)`
+
+The `download_url` field in the `write_workspace_file` response is already
+in the correct format — paste it directly after the `(` in the Markdown.
+
+### Passing file content to tools — @@agptfile: references
+Instead of copying large file contents into a tool argument, pass a file
+reference and the platform will load the content for you.
+
+Syntax: `@@agptfile:<uri>[<start>-<end>]`
+
+- `<uri>` **must** start with `workspace://` or `/` (absolute path):
+  - `workspace://<file_id>` — workspace file by ID
+  - `workspace:///<path>` — workspace file by virtual path
+  - `/absolute/local/path` — ephemeral or sdk_cwd file
+  - E2B sandbox absolute path (e.g. `/home/user/script.py`)
+- `[<start>-<end>]` is an optional 1-indexed inclusive line range.
+- URIs that do not start with `workspace://` or `/` are **not** expanded.
 
 Examples:
 ```
@@ -33,16 +49,18 @@ Examples:
 @@agptfile:/home/user/script.py
 ```
 
-**Structured data**: When the entire argument is a single file reference, the platform auto-parses by extension/MIME. Supported: JSON, JSONL, CSV, TSV, YAML, TOML, Parquet, Excel (.xlsx only). Unrecognised formats return plain string.
+You can embed a reference inside any string argument, or use it as the entire
+value.  Multiple references in one argument are all expanded.
 
-**Type coercion**: The platform auto-coerces expanded string values to match block input types (e.g. JSON string → `list[list[str]]`).
+**Type coercion**: The platform automatically coerces expanded string values
+to match the block's expected input types.  For example, if a block expects
+`list[list[str]]` and you pass a string containing a JSON array (e.g. from
+an @@agptfile: expansion), the string will be parsed into the correct type.
 
-### Media file inputs (format: "file")
-Inputs with `"format": "file"` accept `workspace://<file_id>` or `data:<mime>;base64,<payload>`.
-Pass the `workspace://` URI directly (do NOT wrap in `@@agptfile:`). This avoids large payloads and preserves binary content.
 
 ### Sub-agent tasks
-- Task tool: NEVER set `run_in_background` to true.
+- When using the Task tool, NEVER set `run_in_background` to true.
+  All tasks must run in the foreground.
 """
 
 
@@ -78,18 +96,30 @@ def _build_storage_supplement(
 
 ## Tool notes
 
-### Shell & filesystem
-- Use `bash_exec` for shell commands ({sandbox_type}). Working dir: `{working_dir}`
-- All file tools share the same filesystem. Use relative or absolute paths under this dir.
+### Shell commands
+- The SDK built-in Bash tool is NOT available.  Use the `bash_exec` MCP tool
+  for shell commands — it runs {sandbox_type}.
+
+### Working directory
+- Your working directory is: `{working_dir}`
+- All SDK file tools AND `bash_exec` operate on the same filesystem
+- Use relative paths or absolute paths under `{working_dir}` for all file operations
+
+### Two storage systems — CRITICAL to understand
 
-### Storage — important
 1. **{storage_system_1_name}** (`{working_dir}`):
 {characteristics}
 {persistence}
-2. **Persistent workspace** (cloud) — survives across sessions.
-   - {file_move_name_1_to_2}: use `write_workspace_file`
-   - {file_move_name_2_to_1}: use `read_workspace_file` with save_to_path
-   - Save important files to workspace for persistence.
+
+2. **Persistent workspace** (cloud storage):
+   - Files here **survive across sessions indefinitely**
+
+### Moving files between storages
+- **{file_move_name_1_to_2}**: Copy to persistent workspace
+- **{file_move_name_2_to_1}**: Download for processing
+
+### File persistence
+Important files (code, configs, outputs) should be saved to workspace to ensure they persist.
 {_SHARED_TOOL_NOTES}"""
 
 

autogpt_platform/backend/backend/copilot/sdk/__init__.py

@@ -3,45 +3,12 @@
 This module provides the integration layer between the Claude Agent SDK
 and the existing CoPilot tool system, enabling drop-in replacement of
 the current LLM orchestration with the battle-tested Claude Agent SDK.
-
-Submodule imports are deferred via PEP 562 ``__getattr__`` to break a
-circular import cycle::
-
-    sdk/__init__ → tool_adapter → copilot.tools (TOOL_REGISTRY)
-    copilot.tools → run_block → sdk.file_ref  (no cycle here, but…)
-    sdk/__init__ → service → copilot.prompting → copilot.tools  (cycle!)
-
-``tool_adapter`` uses ``TOOL_REGISTRY`` at **module level** to build the
-static ``COPILOT_TOOL_NAMES`` list, so the import cannot be deferred to
-function scope without a larger refactor (moving tool-name registration
-to a separate lightweight module).  The lazy-import pattern here is the
-least invasive way to break the cycle while keeping module-level constants
-intact.
 """
 
-from typing import Any
+from .service import stream_chat_completion_sdk
+from .tool_adapter import create_copilot_mcp_server
 
 __all__ = [
     "stream_chat_completion_sdk",
     "create_copilot_mcp_server",
 ]
-
-# Dispatch table for PEP 562 lazy imports.  Each entry is a (module, attr)
-# pair so new exports can be added without touching __getattr__ itself.
-_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
-    "stream_chat_completion_sdk": (".service", "stream_chat_completion_sdk"),
-    "create_copilot_mcp_server": (".tool_adapter", "create_copilot_mcp_server"),
-}
-
-
-def __getattr__(name: str) -> Any:
-    entry = _LAZY_IMPORTS.get(name)
-    if entry is not None:
-        module_path, attr = entry
-        import importlib
-
-        module = importlib.import_module(module_path, package=__name__)
-        value = getattr(module, attr)
-        globals()[name] = value
-        return value
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

autogpt_platform/backend/backend/copilot/sdk/file_ref.py

@@ -41,20 +41,12 @@ from typing import Any
 from backend.copilot.context import (
     get_current_sandbox,
     get_sdk_cwd,
-    get_workspace_manager,
     is_allowed_local_path,
     resolve_sandbox_path,
 )
 from backend.copilot.model import ChatSession
+from backend.copilot.tools.workspace_files import get_manager
 from backend.util.file import parse_workspace_uri
-from backend.util.file_content_parser import (
-    BINARY_FORMATS,
-    MIME_TO_FORMAT,
-    PARSE_EXCEPTIONS,
-    infer_format_from_uri,
-    parse_file_content,
-)
-from backend.util.type import MediaFileType
 
 
 class FileRefExpansionError(Exception):
@@ -82,8 +74,6 @@ _FILE_REF_RE = re.compile(
 _MAX_EXPAND_CHARS = 200_000
 # Maximum total characters across all @@agptfile: expansions in one string.
 _MAX_TOTAL_EXPAND_CHARS = 1_000_000
-# Maximum raw byte size for bare ref structured parsing (10 MB).
-_MAX_BARE_REF_BYTES = 10_000_000
 
 
 @dataclass
@@ -93,11 +83,6 @@ class FileRef:
     end_line: int | None  # 1-indexed, inclusive
 
 
-# ---------------------------------------------------------------------------
-# Public API  (top-down: main functions first, helpers below)
-# ---------------------------------------------------------------------------
-
-
 def parse_file_ref(text: str) -> FileRef | None:
     """Return a :class:`FileRef` if *text* is a bare file reference token.
 
@@ -119,6 +104,17 @@ def parse_file_ref(text: str) -> FileRef | None:
     return FileRef(uri=m.group(1), start_line=start, end_line=end)
 
 
+def _apply_line_range(text: str, start: int | None, end: int | None) -> str:
+    """Slice *text* to the requested 1-indexed line range (inclusive)."""
+    if start is None and end is None:
+        return text
+    lines = text.splitlines(keepends=True)
+    s = (start - 1) if start is not None else 0
+    e = end if end is not None else len(lines)
+    selected = list(itertools.islice(lines, s, e))
+    return "".join(selected)
+
+
 async def read_file_bytes(
     uri: str,
     user_id: str | None,
@@ -134,47 +130,27 @@ async def read_file_bytes(
     if plain.startswith("workspace://"):
         if not user_id:
             raise ValueError("workspace:// file references require authentication")
-        manager = await get_workspace_manager(user_id, session.session_id)
+        manager = await get_manager(user_id, session.session_id)
         ws = parse_workspace_uri(plain)
         try:
-            data = await (
+            return await (
                 manager.read_file(ws.file_ref)
                 if ws.is_path
                 else manager.read_file_by_id(ws.file_ref)
             )
         except FileNotFoundError:
             raise ValueError(f"File not found: {plain}")
-        except (PermissionError, OSError) as exc:
+        except Exception as exc:
             raise ValueError(f"Failed to read {plain}: {exc}") from exc
-        except (AttributeError, TypeError, RuntimeError) as exc:
-            # AttributeError/TypeError: workspace manager returned an
-            # unexpected type or interface; RuntimeError: async runtime issues.
-            logger.warning("Unexpected error reading %s: %s", plain, exc)
-            raise ValueError(f"Failed to read {plain}: {exc}") from exc
-        # NOTE: Workspace API does not support pre-read size checks;
-        # the full file is loaded before the size guard below.
-        if len(data) > _MAX_BARE_REF_BYTES:
-            raise ValueError(
-                f"File too large ({len(data)} bytes, limit {_MAX_BARE_REF_BYTES})"
-            )
-        return data
 
     if is_allowed_local_path(plain, get_sdk_cwd()):
         resolved = os.path.realpath(os.path.expanduser(plain))
         try:
-            # Read with a one-byte overshoot to detect files that exceed the limit
-            # without a separate os.path.getsize call (avoids TOCTOU race).
             with open(resolved, "rb") as fh:
-                data = fh.read(_MAX_BARE_REF_BYTES + 1)
-            if len(data) > _MAX_BARE_REF_BYTES:
-                raise ValueError(
-                    f"File too large (>{_MAX_BARE_REF_BYTES} bytes, "
-                    f"limit {_MAX_BARE_REF_BYTES})"
-                )
-            return data
+                return fh.read()
         except FileNotFoundError:
             raise ValueError(f"File not found: {plain}")
-        except OSError as exc:
+        except Exception as exc:
             raise ValueError(f"Failed to read {plain}: {exc}") from exc
 
     sandbox = get_current_sandbox()
@@ -186,33 +162,9 @@ async def read_file_bytes(
                 f"Path is not allowed (not in workspace, sdk_cwd, or sandbox): {plain}"
             ) from exc
         try:
-            data = bytes(await sandbox.files.read(remote, format="bytes"))
-        except (FileNotFoundError, OSError, UnicodeDecodeError) as exc:
-            raise ValueError(f"Failed to read from sandbox: {plain}: {exc}") from exc
+            return bytes(await sandbox.files.read(remote, format="bytes"))
         except Exception as exc:
-            # E2B SDK raises SandboxException subclasses (NotFoundException,
-            # TimeoutException, NotEnoughSpaceException, etc.) which don't
-            # inherit from standard exceptions.  Import lazily to avoid a
-            # hard dependency on e2b at module level.
-            try:
-                from e2b.exceptions import SandboxException  # noqa: PLC0415
-
-                if isinstance(exc, SandboxException):
-                    raise ValueError(
-                        f"Failed to read from sandbox: {plain}: {exc}"
-                    ) from exc
-            except ImportError:
-                pass
-            # Re-raise unexpected exceptions (TypeError, AttributeError, etc.)
-            # so they surface as real bugs rather than being silently masked.
-            raise
-        # NOTE: E2B sandbox API does not support pre-read size checks;
-        # the full file is loaded before the size guard below.
-        if len(data) > _MAX_BARE_REF_BYTES:
-            raise ValueError(
-                f"File too large ({len(data)} bytes, limit {_MAX_BARE_REF_BYTES})"
-            )
-        return data
+            raise ValueError(f"Failed to read from sandbox: {plain}: {exc}") from exc
 
     raise ValueError(
         f"Path is not allowed (not in workspace, sdk_cwd, or sandbox): {plain}"
@@ -226,13 +178,15 @@ async def resolve_file_ref(
 ) -> str:
     """Resolve a :class:`FileRef` to its text content."""
     raw = await read_file_bytes(ref.uri, user_id, session)
-    return _apply_line_range(_to_str(raw), ref.start_line, ref.end_line)
+    return _apply_line_range(
+        raw.decode("utf-8", errors="replace"), ref.start_line, ref.end_line
+    )
 
 
 async def expand_file_refs_in_string(
     text: str,
     user_id: str | None,
-    session: ChatSession,
+    session: "ChatSession",
     *,
     raise_on_error: bool = False,
 ) -> str:
@@ -278,9 +232,6 @@ async def expand_file_refs_in_string(
             if len(content) > _MAX_EXPAND_CHARS:
                 content = content[:_MAX_EXPAND_CHARS] + "\n... [truncated]"
             remaining = _MAX_TOTAL_EXPAND_CHARS - total_chars
-            # remaining == 0 means the budget was exactly exhausted by the
-            # previous ref.  The elif below (len > remaining) won't catch
-            # this since 0 > 0 is false, so we need the <= 0 check.
             if remaining <= 0:
                 content = "[file-ref budget exhausted: total expansion limit reached]"
             elif len(content) > remaining:
@@ -301,31 +252,13 @@ async def expand_file_refs_in_string(
 async def expand_file_refs_in_args(
     args: dict[str, Any],
     user_id: str | None,
-    session: ChatSession,
-    *,
-    input_schema: dict[str, Any] | None = None,
+    session: "ChatSession",
 ) -> dict[str, Any]:
     """Recursively expand ``@@agptfile:...`` references in tool call arguments.
 
     String values are expanded in-place.  Nested dicts and lists are
     traversed.  Non-string scalars are returned unchanged.
 
-    **Bare references** (the entire argument value is a single
-    ``@@agptfile:...`` token with no surrounding text) are resolved and then
-    parsed according to the file's extension or MIME type.  See
-    :mod:`backend.util.file_content_parser` for the full list of supported
-    formats (JSON, JSONL, CSV, TSV, YAML, TOML, Parquet, Excel).
-
-    When *input_schema* is provided and the target property has
-    ``"type": "string"``, structured parsing is skipped — the raw file content
-    is returned as a plain string so blocks receive the original text.
-
-    If the format is unrecognised or parsing fails, the content is returned as
-    a plain string (the fallback).
-
-    **Embedded references** (``@@agptfile:`` mixed with other text) always
-    produce a plain string — structured parsing only applies to bare refs.
-
     Raises :class:`FileRefExpansionError` if any reference fails to resolve,
     so the tool is *not* executed with an error string as its input.  The
     caller (the MCP tool wrapper) should convert this into an MCP error
@@ -334,382 +267,15 @@ async def expand_file_refs_in_args(
     if not args:
         return args
 
-    properties = (input_schema or {}).get("properties", {})
-
-    async def _expand(
-        value: Any,
-        *,
-        prop_schema: dict[str, Any] | None = None,
-    ) -> Any:
-        """Recursively expand a single argument value.
-
-        Strings are checked for ``@@agptfile:`` references and expanded
-        (bare refs get structured parsing; embedded refs get inline
-        substitution).  Dicts and lists are traversed recursively,
-        threading the corresponding sub-schema from *prop_schema* so
-        that nested fields also receive correct type-aware expansion.
-        Non-string scalars pass through unchanged.
-        """
+    async def _expand(value: Any) -> Any:
         if isinstance(value, str):
-            ref = parse_file_ref(value)
-            if ref is not None:
-                # MediaFileType fields: return the raw URI immediately —
-                # no file reading, no format inference, no content parsing.
-                if _is_media_file_field(prop_schema):
-                    return ref.uri
-
-                fmt = infer_format_from_uri(ref.uri)
-                # Workspace URIs by ID (workspace://abc123) have no extension.
-                # When the MIME fragment is also missing, fall back to the
-                # workspace file manager's metadata for format detection.
-                if fmt is None and ref.uri.startswith("workspace://"):
-                    fmt = await _infer_format_from_workspace(ref.uri, user_id, session)
-                return await _expand_bare_ref(ref, fmt, user_id, session, prop_schema)
-
-            # Not a bare ref — do normal inline expansion.
             return await expand_file_refs_in_string(
                 value, user_id, session, raise_on_error=True
             )
         if isinstance(value, dict):
-            # When the schema says this is an object but doesn't define
-            # inner properties, skip expansion — the caller (e.g.
-            # RunBlockTool) will expand with the actual nested schema.
-            if (
-                prop_schema is not None
-                and prop_schema.get("type") == "object"
-                and "properties" not in prop_schema
-            ):
-                return value
-            nested_props = (prop_schema or {}).get("properties", {})
-            return {
-                k: await _expand(v, prop_schema=nested_props.get(k))
-                for k, v in value.items()
-            }
+            return {k: await _expand(v) for k, v in value.items()}
         if isinstance(value, list):
-            items_schema = (prop_schema or {}).get("items")
-            return [await _expand(item, prop_schema=items_schema) for item in value]
+            return [await _expand(item) for item in value]
         return value
 
-    return {k: await _expand(v, prop_schema=properties.get(k)) for k, v in args.items()}
-
-
-# ---------------------------------------------------------------------------
-# Private helpers  (used by the public functions above)
-# ---------------------------------------------------------------------------
-
-
-def _apply_line_range(text: str, start: int | None, end: int | None) -> str:
-    """Slice *text* to the requested 1-indexed line range (inclusive).
-
-    When the requested range extends beyond the file, a note is appended
-    so the LLM knows it received the entire remaining content.
-    """
-    if start is None and end is None:
-        return text
-    lines = text.splitlines(keepends=True)
-    total = len(lines)
-    s = (start - 1) if start is not None else 0
-    e = end if end is not None else total
-    selected = list(itertools.islice(lines, s, e))
-    result = "".join(selected)
-    if end is not None and end > total:
-        result += f"\n[Note: file has only {total} lines]\n"
-    return result
-
-
-def _to_str(content: str | bytes) -> str:
-    """Decode *content* to a string if it is bytes, otherwise return as-is."""
-    if isinstance(content, str):
-        return content
-    return content.decode("utf-8", errors="replace")
-
-
-def _check_content_size(content: str | bytes) -> None:
-    """Raise :class:`ValueError` if *content* exceeds the byte limit.
-
-    Raises ``ValueError`` (not ``FileRefExpansionError``) so that the caller
-    (``_expand_bare_ref``) can unify all resolution errors into a single
-    ``except ValueError`` → ``FileRefExpansionError`` handler, keeping the
-    error-flow consistent with ``read_file_bytes`` and ``resolve_file_ref``.
-
-    For ``bytes``, the length is the byte count directly.  For ``str``,
-    we encode to UTF-8 first because multi-byte characters (e.g. emoji)
-    mean the byte size can be up to 4x the character count.
-    """
-    if isinstance(content, bytes):
-        size = len(content)
-    else:
-        char_len = len(content)
-        # Fast lower bound: UTF-8 byte count >= char count.
-        # If char count already exceeds the limit, reject immediately
-        # without allocating an encoded copy.
-        if char_len > _MAX_BARE_REF_BYTES:
-            size = char_len  # real byte size is even larger
-        # Fast upper bound: each char is at most 4 UTF-8 bytes.
-        # If worst-case is still under the limit, skip encoding entirely.
-        elif char_len * 4 <= _MAX_BARE_REF_BYTES:
-            return
-        else:
-            # Edge case: char count is under limit but multibyte chars
-            # might push byte count over. Encode to get exact size.
-            size = len(content.encode("utf-8"))
-    if size > _MAX_BARE_REF_BYTES:
-        raise ValueError(
-            f"File too large for structured parsing "
-            f"({size} bytes, limit {_MAX_BARE_REF_BYTES})"
-        )
-
-
-async def _infer_format_from_workspace(
-    uri: str,
-    user_id: str | None,
-    session: ChatSession,
-) -> str | None:
-    """Look up workspace file metadata to infer the format.
-
-    Workspace URIs by ID (``workspace://abc123``) have no file extension.
-    When the MIME fragment is also absent, we query the workspace file
-    manager for the file's stored MIME type and original filename.
-    """
-    if not user_id:
-        return None
-    try:
-        ws = parse_workspace_uri(uri)
-        manager = await get_workspace_manager(user_id, session.session_id)
-        info = await (
-            manager.get_file_info(ws.file_ref)
-            if not ws.is_path
-            else manager.get_file_info_by_path(ws.file_ref)
-        )
-        if info is None:
-            return None
-        # Try MIME type first, then filename extension.
-        mime = (info.mime_type or "").split(";", 1)[0].strip().lower()
-        return MIME_TO_FORMAT.get(mime) or infer_format_from_uri(info.name)
-    except (
-        ValueError,
-        FileNotFoundError,
-        OSError,
-        PermissionError,
-        AttributeError,
-        TypeError,
-    ):
-        # Expected failures: bad URI, missing file, permission denied, or
-        # workspace manager returning unexpected types.  Propagate anything
-        # else (e.g. programming errors) so they don't get silently swallowed.
-        logger.debug("workspace metadata lookup failed for %s", uri, exc_info=True)
-        return None
-
-
-def _is_media_file_field(prop_schema: dict[str, Any] | None) -> bool:
-    """Return True if *prop_schema* describes a MediaFileType field (format: file)."""
-    if prop_schema is None:
-        return False
-    return (
-        prop_schema.get("type") == "string"
-        and prop_schema.get("format") == MediaFileType.string_format
-    )
-
-
-async def _expand_bare_ref(
-    ref: FileRef,
-    fmt: str | None,
-    user_id: str | None,
-    session: ChatSession,
-    prop_schema: dict[str, Any] | None,
-) -> Any:
-    """Resolve and parse a bare ``@@agptfile:`` reference.
-
-    This is the structured-parsing path: the file is read, optionally parsed
-    according to *fmt*, and adapted to the target *prop_schema*.
-
-    Raises :class:`FileRefExpansionError` on resolution or parsing failure.
-
-    Note: MediaFileType fields (format: "file") are handled earlier in
-    ``_expand`` to avoid unnecessary format inference and file I/O.
-    """
-    try:
-        if fmt is not None and fmt in BINARY_FORMATS:
-            # Binary formats need raw bytes, not UTF-8 text.
-            # Line ranges are meaningless for binary formats (parquet/xlsx)
-            # — ignore them and parse full bytes.  Warn so the caller/model
-            # knows the range was silently dropped.
-            if ref.start_line is not None or ref.end_line is not None:
-                logger.warning(
-                    "Line range [%s-%s] ignored for binary format %s (%s); "
-                    "binary formats are always parsed in full.",
-                    ref.start_line,
-                    ref.end_line,
-                    fmt,
-                    ref.uri,
-                )
-            content: str | bytes = await read_file_bytes(ref.uri, user_id, session)
-        else:
-            content = await resolve_file_ref(ref, user_id, session)
-    except ValueError as exc:
-        raise FileRefExpansionError(str(exc)) from exc
-
-    # For known formats this rejects files >10 MB before parsing.
-    # For unknown formats _MAX_EXPAND_CHARS (200K chars) below is stricter,
-    # but this check still guards the parsing path which has no char limit.
-    # _check_content_size raises ValueError, which we unify here just like
-    # resolution errors above.
-    try:
-        _check_content_size(content)
-    except ValueError as exc:
-        raise FileRefExpansionError(str(exc)) from exc
-
-    # When the schema declares this parameter as "string",
-    # return raw file content — don't parse into a structured
-    # type that would need json.dumps() serialisation.
-    expect_string = (prop_schema or {}).get("type") == "string"
-    if expect_string:
-        if isinstance(content, bytes):
-            raise FileRefExpansionError(
-                f"Cannot use {fmt} file as text input: "
-                f"binary formats (parquet, xlsx) must be passed "
-                f"to a block that accepts structured data (list/object), "
-                f"not a string-typed parameter."
-            )
-        return content
-
-    if fmt is not None:
-        # Use strict mode for binary formats so we surface the
-        # actual error (e.g. missing pyarrow/openpyxl, corrupt
-        # file) instead of silently returning garbled bytes.
-        strict = fmt in BINARY_FORMATS
-        try:
-            parsed = parse_file_content(content, fmt, strict=strict)
-        except PARSE_EXCEPTIONS as exc:
-            raise FileRefExpansionError(f"Failed to parse {fmt} file: {exc}") from exc
-        # Normalize bytes fallback to str so tools never
-        # receive raw bytes when parsing fails.
-        if isinstance(parsed, bytes):
-            parsed = _to_str(parsed)
-        return _adapt_to_schema(parsed, prop_schema)
-
-    # Unknown format — return as plain string, but apply
-    # the same per-ref character limit used by inline refs
-    # to prevent injecting unexpectedly large content.
-    text = _to_str(content)
-    if len(text) > _MAX_EXPAND_CHARS:
-        text = text[:_MAX_EXPAND_CHARS] + "\n... [truncated]"
-    return text
-
-
-def _adapt_to_schema(parsed: Any, prop_schema: dict[str, Any] | None) -> Any:
-    """Adapt a parsed file value to better fit the target schema type.
-
-    When the parser returns a natural type (e.g. dict from YAML, list from CSV)
-    that doesn't match the block's expected type, this function converts it to
-    a more useful representation instead of relying on pydantic's generic
-    coercion (which can produce awkward results like flattened dicts → lists).
-
-    Returns *parsed* unchanged when no adaptation is needed.
-    """
-    if prop_schema is None:
-        return parsed
-
-    target_type = prop_schema.get("type")
-
-    # Dict → array: delegate to helper.
-    if isinstance(parsed, dict) and target_type == "array":
-        return _adapt_dict_to_array(parsed, prop_schema)
-
-    # List → object: delegate to helper (raises for non-tabular lists).
-    if isinstance(parsed, list) and target_type == "object":
-        return _adapt_list_to_object(parsed)
-
-    # Tabular list → Any (no type): convert to list of dicts.
-    # Blocks like FindInDictionaryBlock have `input: Any` which produces
-    # a schema with no "type" key.  Tabular [[header],[rows]] is unusable
-    # for key lookup, but [{col: val}, ...] works with FindInDict's
-    # list-of-dicts branch (line 195-199 in data_manipulation.py).
-    if isinstance(parsed, list) and target_type is None and _is_tabular(parsed):
-        return _tabular_to_list_of_dicts(parsed)
-
-    return parsed
-
-
-def _adapt_dict_to_array(parsed: dict, prop_schema: dict[str, Any]) -> Any:
-    """Adapt a parsed dict to an array-typed field.
-
-    Extracts list-valued entries when the target item type is ``array``,
-    passes through unchanged when item type is ``string`` (lets pydantic error),
-    or wraps in ``[parsed]`` as a fallback.
-    """
-    items_type = (prop_schema.get("items") or {}).get("type")
-    if items_type == "array":
-        # Target is List[List[Any]] — extract list-typed values from the
-        # dict as inner lists.  E.g. YAML {"fruits": [{...},...]}} with
-        # ConcatenateLists (List[List[Any]]) → [[{...},...]].
-        list_values = [v for v in parsed.values() if isinstance(v, list)]
-        if list_values:
-            return list_values
-    if items_type == "string":
-        # Target is List[str] — wrapping a dict would give [dict]
-        # which can't coerce to strings.  Return unchanged and let
-        # pydantic surface a clear validation error.
-        return parsed
-    # Fallback: wrap in a single-element list so the block gets [dict]
-    # instead of pydantic flattening keys/values into a flat list.
-    return [parsed]
-
-
-def _adapt_list_to_object(parsed: list) -> Any:
-    """Adapt a parsed list to an object-typed field.
-
-    Converts tabular lists to column-dicts; raises for non-tabular lists.
-    """
-    if _is_tabular(parsed):
-        return _tabular_to_column_dict(parsed)
-    # Non-tabular list (e.g. a plain Python list from a YAML file) cannot
-    # be meaningfully coerced to an object.  Raise explicitly so callers
-    # get a clear error rather than pydantic silently wrapping the list.
-    raise FileRefExpansionError(
-        "Cannot adapt a non-tabular list to an object-typed field. "
-        "Expected a tabular structure ([[header], [row1], ...]) or a dict."
-    )
-
-
-def _is_tabular(parsed: Any) -> bool:
-    """Check if parsed data is in tabular format: [[header], [row1], ...].
-
-    Uses isinstance checks because this is a structural type guard on
-    opaque parser output (Any), not duck typing.  A Protocol wouldn't
-    help here — we need to verify exact list-of-lists shape.
-    """
-    if not isinstance(parsed, list) or len(parsed) < 2:
-        return False
-    header = parsed[0]
-    if not isinstance(header, list) or not header:
-        return False
-    if not all(isinstance(h, str) for h in header):
-        return False
-    return all(isinstance(row, list) for row in parsed[1:])
-
-
-def _tabular_to_list_of_dicts(parsed: list) -> list[dict[str, Any]]:
-    """Convert [[header], [row1], ...] → [{header[0]: row[0], ...}, ...].
-
-    Ragged rows (fewer columns than the header) get None for missing values.
-    Extra values beyond the header length are silently dropped.
-    """
-    header = parsed[0]
-    return [
-        dict(itertools.zip_longest(header, row[: len(header)], fillvalue=None))
-        for row in parsed[1:]
-    ]
-
-
-def _tabular_to_column_dict(parsed: list) -> dict[str, list]:
-    """Convert [[header], [row1], ...] → {"col1": [val1, ...], ...}.
-
-    Ragged rows (fewer columns than the header) get None for missing values,
-    ensuring all columns have equal length.
-    """
-    header = parsed[0]
-    return {
-        col: [row[i] if i < len(row) else None for row in parsed[1:]]
-        for i, col in enumerate(header)
-    }
+    return {k: await _expand(v) for k, v in args.items()}

autogpt_platform/backend/backend/copilot/sdk/file_ref_integration_test.py

@@ -175,199 +175,6 @@ async def test_expand_args_replaces_file_ref_in_nested_dict():
         assert result["count"] == 42
 
 
-# ---------------------------------------------------------------------------
-# expand_file_refs_in_args — bare ref structured parsing
-# ---------------------------------------------------------------------------
-
-
-@pytest.mark.asyncio
-async def test_bare_ref_json_returns_parsed_dict():
-    """Bare ref to a .json file returns parsed dict, not raw string."""
-    with tempfile.TemporaryDirectory() as sdk_cwd:
-        json_file = os.path.join(sdk_cwd, "data.json")
-        with open(json_file, "w") as f:
-            f.write('{"key": "value", "count": 42}')
-
-        with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd_var:
-            mock_cwd_var.get.return_value = sdk_cwd
-
-            result = await expand_file_refs_in_args(
-                {"data": f"@@agptfile:{json_file}"},
-                user_id="u1",
-                session=_make_session(),
-            )
-
-        assert result["data"] == {"key": "value", "count": 42}
-
-
-@pytest.mark.asyncio
-async def test_bare_ref_csv_returns_parsed_table():
-    """Bare ref to a .csv file returns list[list[str]] table."""
-    with tempfile.TemporaryDirectory() as sdk_cwd:
-        csv_file = os.path.join(sdk_cwd, "data.csv")
-        with open(csv_file, "w") as f:
-            f.write("Name,Score\nAlice,90\nBob,85")
-
-        with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd_var:
-            mock_cwd_var.get.return_value = sdk_cwd
-
-            result = await expand_file_refs_in_args(
-                {"input": f"@@agptfile:{csv_file}"},
-                user_id="u1",
-                session=_make_session(),
-            )
-
-        assert result["input"] == [
-            ["Name", "Score"],
-            ["Alice", "90"],
-            ["Bob", "85"],
-        ]
-
-
-@pytest.mark.asyncio
-async def test_bare_ref_unknown_extension_returns_string():
-    """Bare ref to a file with unknown extension returns plain string."""
-    with tempfile.TemporaryDirectory() as sdk_cwd:
-        txt_file = os.path.join(sdk_cwd, "readme.txt")
-        with open(txt_file, "w") as f:
-            f.write("plain text content")
-
-        with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd_var:
-            mock_cwd_var.get.return_value = sdk_cwd
-
-            result = await expand_file_refs_in_args(
-                {"data": f"@@agptfile:{txt_file}"},
-                user_id="u1",
-                session=_make_session(),
-            )
-
-        assert result["data"] == "plain text content"
-        assert isinstance(result["data"], str)
-
-
-@pytest.mark.asyncio
-async def test_bare_ref_invalid_json_falls_back_to_string():
-    """Bare ref to a .json file with invalid JSON falls back to string."""
-    with tempfile.TemporaryDirectory() as sdk_cwd:
-        json_file = os.path.join(sdk_cwd, "bad.json")
-        with open(json_file, "w") as f:
-            f.write("not valid json {{{")
-
-        with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd_var:
-            mock_cwd_var.get.return_value = sdk_cwd
-
-            result = await expand_file_refs_in_args(
-                {"data": f"@@agptfile:{json_file}"},
-                user_id="u1",
-                session=_make_session(),
-            )
-
-        assert result["data"] == "not valid json {{{"
-        assert isinstance(result["data"], str)
-
-
-@pytest.mark.asyncio
-async def test_embedded_ref_always_returns_string_even_for_json():
-    """Embedded ref (text around it) returns plain string, not parsed JSON."""
-    with tempfile.TemporaryDirectory() as sdk_cwd:
-        json_file = os.path.join(sdk_cwd, "data.json")
-        with open(json_file, "w") as f:
-            f.write('{"key": "value"}')
-
-        with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd_var:
-            mock_cwd_var.get.return_value = sdk_cwd
-
-            result = await expand_file_refs_in_args(
-                {"data": f"prefix @@agptfile:{json_file} suffix"},
-                user_id="u1",
-                session=_make_session(),
-            )
-
-        assert isinstance(result["data"], str)
-        assert result["data"].startswith("prefix ")
-        assert result["data"].endswith(" suffix")
-
-
-@pytest.mark.asyncio
-async def test_bare_ref_yaml_returns_parsed_dict():
-    """Bare ref to a .yaml file returns parsed dict."""
-    with tempfile.TemporaryDirectory() as sdk_cwd:
-        yaml_file = os.path.join(sdk_cwd, "config.yaml")
-        with open(yaml_file, "w") as f:
-            f.write("name: test\ncount: 42\n")
-
-        with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd_var:
-            mock_cwd_var.get.return_value = sdk_cwd
-
-            result = await expand_file_refs_in_args(
-                {"config": f"@@agptfile:{yaml_file}"},
-                user_id="u1",
-                session=_make_session(),
-            )
-
-        assert result["config"] == {"name": "test", "count": 42}
-
-
-@pytest.mark.asyncio
-async def test_bare_ref_binary_with_line_range_ignores_range():
-    """Bare ref to a binary file (.parquet) with line range parses the full file.
-
-    Binary formats (parquet, xlsx) ignore line ranges — the full content is
-    parsed and the range is silently dropped with a log warning.
-    """
-    try:
-        import pandas as pd
-    except ImportError:
-        pytest.skip("pandas not installed")
-    try:
-        import pyarrow  # noqa: F401  # pyright: ignore[reportMissingImports]
-    except ImportError:
-        pytest.skip("pyarrow not installed")
-
-    with tempfile.TemporaryDirectory() as sdk_cwd:
-        parquet_file = os.path.join(sdk_cwd, "data.parquet")
-        import io as _io
-
-        df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})
-        buf = _io.BytesIO()
-        df.to_parquet(buf, index=False)
-        with open(parquet_file, "wb") as f:
-            f.write(buf.getvalue())
-
-        with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd_var:
-            mock_cwd_var.get.return_value = sdk_cwd
-
-            # Line range [1-2] should be silently ignored for binary formats.
-            result = await expand_file_refs_in_args(
-                {"data": f"@@agptfile:{parquet_file}[1-2]"},
-                user_id="u1",
-                session=_make_session(),
-            )
-
-        # Full file is returned despite the line range.
-        assert result["data"] == [["A", "B"], [1, 4], [2, 5], [3, 6]]
-
-
-@pytest.mark.asyncio
-async def test_bare_ref_toml_returns_parsed_dict():
-    """Bare ref to a .toml file returns parsed dict."""
-    with tempfile.TemporaryDirectory() as sdk_cwd:
-        toml_file = os.path.join(sdk_cwd, "config.toml")
-        with open(toml_file, "w") as f:
-            f.write('name = "test"\ncount = 42\n')
-
-        with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd_var:
-            mock_cwd_var.get.return_value = sdk_cwd
-
-            result = await expand_file_refs_in_args(
-                {"config": f"@@agptfile:{toml_file}"},
-                user_id="u1",
-                session=_make_session(),
-            )
-
-        assert result["config"] == {"name": "test", "count": 42}
-
-
 # ---------------------------------------------------------------------------
 # _read_file_handler — extended to accept workspace:// and local paths
 # ---------------------------------------------------------------------------
@@ -412,7 +219,7 @@ async def test_read_file_handler_workspace_uri():
         "backend.copilot.sdk.tool_adapter.get_execution_context",
         return_value=("user-1", mock_session),
     ), patch(
-        "backend.copilot.sdk.file_ref.get_workspace_manager",
+        "backend.copilot.sdk.file_ref.get_manager",
         new=AsyncMock(return_value=mock_manager),
     ):
         result = await _read_file_handler(
@@ -469,7 +276,7 @@ async def test_read_file_bytes_workspace_virtual_path():
     mock_manager.read_file.return_value = b"virtual path content"
 
     with patch(
-        "backend.copilot.sdk.file_ref.get_workspace_manager",
+        "backend.copilot.sdk.file_ref.get_manager",
         new=AsyncMock(return_value=mock_manager),
     ):
         result = await read_file_bytes("workspace:///reports/q1.md", "user-1", session)

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

@@ -29,7 +29,6 @@ from langfuse import propagate_attributes
 from langsmith.integrations.claude_agent_sdk import configure_claude_agent_sdk
 from pydantic import BaseModel
 
-from backend.copilot.context import get_workspace_manager
 from backend.data.redis_client import get_redis_async
 from backend.executor.cluster_lock import AsyncClusterLock
 from backend.util.exceptions import NotFoundError
@@ -63,6 +62,7 @@ from ..service import (
 )
 from ..tools.e2b_sandbox import get_or_create_sandbox, pause_sandbox_direct
 from ..tools.sandbox import WORKSPACE_PREFIX, make_session_path
+from ..tools.workspace_files import get_manager
 from ..tracking import track_user_message
 from .compaction import CompactionTracker, filter_compaction_messages
 from .response_adapter import SDKResponseAdapter
@@ -565,7 +565,7 @@ async def _prepare_file_attachments(
         return empty
 
     try:
-        manager = await get_workspace_manager(user_id, session_id)
+        manager = await get_manager(user_id, session_id)
     except Exception:
         logger.warning(
             "Failed to create workspace manager for file attachments",

autogpt_platform/backend/backend/copilot/sdk/service_test.py

@@ -20,7 +20,7 @@ class _FakeFileInfo:
     size_bytes: int
 
 
-_PATCH_TARGET = "backend.copilot.sdk.service.get_workspace_manager"
+_PATCH_TARGET = "backend.copilot.sdk.service.get_manager"
 
 
 class TestPrepareFileAttachments:

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

@@ -347,7 +347,7 @@ def create_copilot_mcp_server(*, use_e2b: bool = False):
     :func:`get_sdk_disallowed_tools`.
     """
 
-    def _truncating(fn, tool_name: str, input_schema: dict[str, Any] | None = None):
+    def _truncating(fn, tool_name: str):
         """Wrap a tool handler so its response is truncated to stay under the
         SDK's 10 MB JSON buffer, and stash the (truncated) output for the
         response adapter before the SDK can apply its own head-truncation.
@@ -361,9 +361,7 @@ def create_copilot_mcp_server(*, use_e2b: bool = False):
             user_id, session = get_execution_context()
             if session is not None:
                 try:
-                    args = await expand_file_refs_in_args(
-                        args, user_id, session, input_schema=input_schema
-                    )
+                    args = await expand_file_refs_in_args(args, user_id, session)
                 except FileRefExpansionError as exc:
                     return _mcp_error(
                         f"@@agptfile: reference could not be resolved: {exc}. "
@@ -391,12 +389,11 @@ def create_copilot_mcp_server(*, use_e2b: bool = False):
 
     for tool_name, base_tool in TOOL_REGISTRY.items():
         handler = create_tool_handler(base_tool)
-        schema = _build_input_schema(base_tool)
         decorated = tool(
             tool_name,
             base_tool.description,
-            schema,
-        )(_truncating(handler, tool_name, input_schema=schema))
+            _build_input_schema(base_tool),
+        )(_truncating(handler, tool_name))
         sdk_tools.append(decorated)
 
     # E2B file tools replace SDK built-in Read/Write/Edit/Glob/Grep.

autogpt_platform/backend/backend/copilot/tools/add_understanding.py

@@ -22,11 +22,13 @@ class AddUnderstandingTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return (
-            "Store user's business context, workflows, pain points, and automation goals. "
-            "Call whenever the user shares business info. Each call incrementally merges "
-            "with existing data — provide only the fields you have."
-        )
+        return """Capture and store information about the user's business context,
+workflows, pain points, and automation goals. Call this tool whenever the user
+shares information about their business. Each call incrementally adds to the
+existing understanding - you don't need to provide all fields at once.
+
+Use this to build a comprehensive profile that helps recommend better agents
+and automations for the user's specific needs."""
 
     @property
     def parameters(self) -> dict[str, Any]:

autogpt_platform/backend/backend/copilot/tools/agent_browser.py

@@ -32,7 +32,6 @@ import shutil
 import tempfile
 from typing import Any
 
-from backend.copilot.context import get_workspace_manager
 from backend.copilot.model import ChatSession
 from backend.util.request import validate_url_host
 
@@ -44,6 +43,7 @@ from .models import (
     ErrorResponse,
     ToolResponseBase,
 )
+from .workspace_files import get_manager
 
 logger = logging.getLogger(__name__)
 
@@ -194,7 +194,7 @@ async def _save_browser_state(
             ),
         }
 
-        manager = await get_workspace_manager(user_id, session.session_id)
+        manager = await get_manager(user_id, session.session_id)
         await manager.write_file(
             content=json.dumps(state).encode("utf-8"),
             filename=_STATE_FILENAME,
@@ -218,7 +218,7 @@ async def _restore_browser_state(
     Returns True on success (or no state to restore), False on failure.
     """
     try:
-        manager = await get_workspace_manager(user_id, session.session_id)
+        manager = await get_manager(user_id, session.session_id)
 
         file_info = await manager.get_file_info_by_path(_STATE_FILENAME)
         if file_info is None:
@@ -360,7 +360,7 @@ async def close_browser_session(session_name: str, user_id: str | None = None) -
     # Delete persisted browser state (cookies, localStorage) from workspace.
     if user_id:
         try:
-            manager = await get_workspace_manager(user_id, session_name)
+            manager = await get_manager(user_id, session_name)
             file_info = await manager.get_file_info_by_path(_STATE_FILENAME)
             if file_info is not None:
                 await manager.delete_file(file_info.id)
@@ -408,11 +408,18 @@ class BrowserNavigateTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Navigate to a URL in a real browser. Returns accessibility tree with @ref IDs "
-            "for browser_act. Session persists (cookies/auth carry over). "
-            "For static pages, prefer web_fetch. "
-            "For SPAs, elements may load late — use browser_act with wait + browser_screenshot to verify. "
-            "For auth: navigate to login, fill creds with browser_act, then navigate to target."
+            "Navigate to a URL using a real browser. Returns an accessibility "
+            "tree snapshot listing the page's interactive elements with @ref IDs "
+            "(e.g. @e3) that can be used with browser_act. "
+            "Session persists — cookies and login state carry over between calls. "
+            "Use this (with browser_act) for multi-step interaction: login flows, "
+            "form filling, button clicks, or anything requiring page interaction. "
+            "For plain static pages, prefer web_fetch — no browser overhead. "
+            "For authenticated pages: navigate to the login page first, use browser_act "
+            "to fill credentials and submit, then navigate to the target page. "
+            "Note: for slow SPAs, the returned snapshot may reflect a partially-loaded "
+            "state. If elements seem missing, use browser_act with action='wait' and a "
+            "CSS selector or millisecond delay, then take a browser_screenshot to verify."
         )
 
     @property
@@ -422,13 +429,13 @@ class BrowserNavigateTool(BaseTool):
             "properties": {
                 "url": {
                     "type": "string",
-                    "description": "HTTP/HTTPS URL to navigate to.",
+                    "description": "The HTTP/HTTPS URL to navigate to.",
                 },
                 "wait_for": {
                     "type": "string",
                     "enum": ["networkidle", "load", "domcontentloaded"],
                     "default": "networkidle",
-                    "description": "Navigation completion strategy (default: networkidle).",
+                    "description": "When to consider navigation complete. Use 'networkidle' for SPAs (default).",
                 },
             },
             "required": ["url"],
@@ -547,12 +554,14 @@ class BrowserActTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Interact with the current browser page using @ref IDs from the snapshot. "
-            "Actions: click, dblclick, fill, type, scroll, hover, press, "
+            "Interact with the current browser page. Use @ref IDs from the "
+            "snapshot (e.g. '@e3') to target elements. Returns an updated snapshot. "
+            "Supported actions: click, dblclick, fill, type, scroll, hover, press, "
             "check, uncheck, select, wait, back, forward, reload. "
-            "fill clears field first; type appends. "
-            "wait accepts CSS selector or milliseconds (e.g. '1000'). "
-            "Returns updated snapshot."
+            "fill clears the field before typing; type appends without clearing. "
+            "wait accepts a CSS selector (waits for element) or milliseconds string (e.g. '1000'). "
+            "Example login flow: fill @e1 with email → fill @e2 with password → "
+            "click @e3 (submit) → browser_navigate to the target page."
         )
 
     @property
@@ -578,21 +587,30 @@ class BrowserActTool(BaseTool):
                         "forward",
                         "reload",
                     ],
-                    "description": "Action to perform.",
+                    "description": "The action to perform.",
                 },
                 "target": {
                     "type": "string",
-                    "description": "@ref ID (e.g. '@e3'), CSS selector, or text description.",
+                    "description": (
+                        "Element to target. Use @ref from snapshot (e.g. '@e3'), "
+                        "a CSS selector, or a text description. "
+                        "Required for: click, dblclick, fill, type, hover, check, uncheck, select. "
+                        "For wait: a CSS selector to wait for, or milliseconds as a string (e.g. '1000')."
+                    ),
                 },
                 "value": {
                     "type": "string",
-                    "description": "Text for fill/type, key for press (e.g. 'Enter'), option for select.",
+                    "description": (
+                        "For fill/type: the text to enter. "
+                        "For press: key name (e.g. 'Enter', 'Tab', 'Control+a'). "
+                        "For select: the option value to select."
+                    ),
                 },
                 "direction": {
                     "type": "string",
                     "enum": ["up", "down", "left", "right"],
                     "default": "down",
-                    "description": "Scroll direction (default: down).",
+                    "description": "For scroll: direction to scroll.",
                 },
             },
             "required": ["action"],
@@ -739,10 +757,12 @@ class BrowserScreenshotTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Screenshot the current browser page and save to workspace. "
-            "annotate=true overlays @ref labels on elements. "
-            "IMPORTANT: After calling, you MUST immediately call read_workspace_file with the "
-            "returned file_id to display the image inline."
+            "Take a screenshot of the current browser page and save it to the workspace. "
+            "IMPORTANT: After calling this tool, immediately call read_workspace_file "
+            "with the returned file_id to display the image inline to the user — "
+            "the screenshot is not visible until you do this. "
+            "With annotate=true (default), @ref labels are overlaid on interactive "
+            "elements, making it easy to see which @ref ID maps to which element on screen."
         )
 
     @property
@@ -753,12 +773,12 @@ class BrowserScreenshotTool(BaseTool):
                 "annotate": {
                     "type": "boolean",
                     "default": True,
-                    "description": "Overlay @ref labels (default: true).",
+                    "description": "Overlay @ref labels on interactive elements (default: true).",
                 },
                 "filename": {
                     "type": "string",
                     "default": "screenshot.png",
-                    "description": "Workspace filename (default: screenshot.png).",
+                    "description": "Filename to save in the workspace.",
                 },
             },
         }

autogpt_platform/backend/backend/copilot/tools/agent_browser_test.py

@@ -897,7 +897,7 @@ class TestHasLocalSession:
 # _save_browser_state
 # ---------------------------------------------------------------------------
 
-_GET_MANAGER = "backend.copilot.tools.agent_browser.get_workspace_manager"
+_GET_MANAGER = "backend.copilot.tools.agent_browser.get_manager"
 
 
 def _make_mock_manager():

autogpt_platform/backend/backend/copilot/tools/agent_output.py

@@ -108,12 +108,22 @@ class AgentOutputTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return (
-            "Retrieve execution outputs from a library agent. "
-            "Identify by agent_name, library_agent_id, or store_slug. "
-            "Filter by execution_id or run_time. "
-            "Optionally wait for running executions."
-        )
+        return """Retrieve execution outputs from agents in the user's library.
+
+        Identify the agent using one of:
+        - agent_name: Fuzzy search in user's library
+        - library_agent_id: Exact library agent ID
+        - store_slug: Marketplace format 'username/agent-name'
+
+        Select which run to retrieve using:
+        - execution_id: Specific execution ID
+        - run_time: 'latest' (default), 'yesterday', 'last week', or ISO date 'YYYY-MM-DD'
+
+        Wait for completion (optional):
+        - wait_if_running: Max seconds to wait if execution is still running (0-300).
+          If the execution is running/queued, waits up to this many seconds for completion.
+          Returns current status on timeout. If already finished, returns immediately.
+        """
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -122,27 +132,32 @@ class AgentOutputTool(BaseTool):
             "properties": {
                 "agent_name": {
                     "type": "string",
-                    "description": "Agent name (fuzzy match).",
+                    "description": "Agent name to search for in user's library (fuzzy match)",
                 },
                 "library_agent_id": {
                     "type": "string",
-                    "description": "Library agent ID.",
+                    "description": "Exact library agent ID",
                 },
                 "store_slug": {
                     "type": "string",
-                    "description": "Marketplace 'username/agent-slug'.",
+                    "description": "Marketplace identifier: 'username/agent-slug'",
                 },
                 "execution_id": {
                     "type": "string",
-                    "description": "Specific execution ID.",
+                    "description": "Specific execution ID to retrieve",
                 },
                 "run_time": {
                     "type": "string",
-                    "description": "Time filter: 'latest', today/yesterday/last week/last 7 days/last month/last 30 days, 'YYYY-MM-DD', or ISO datetime.",
+                    "description": (
+                        "Time filter: 'latest', 'yesterday', 'last week', or 'YYYY-MM-DD'"
+                    ),
                 },
                 "wait_if_running": {
                     "type": "integer",
-                    "description": "Max seconds to wait if still running (0-300). Returns current state on timeout.",
+                    "description": (
+                        "Max seconds to wait if execution is still running (0-300). "
+                        "If running, waits for completion. Returns current state on timeout."
+                    ),
                 },
             },
             "required": [],

autogpt_platform/backend/backend/copilot/tools/bash_exec.py

@@ -41,9 +41,15 @@ class BashExecTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Execute a Bash command or script. Shares filesystem with SDK file tools. "
-            "Useful for scripts, data processing, and package installation. "
-            "Killed after timeout (default 30s, max 120s)."
+            "Execute a Bash command or script. "
+            "Full Bash scripting is supported (loops, conditionals, pipes, "
+            "functions, etc.). "
+            "The working directory is shared with the SDK Read/Write/Edit/Glob/Grep "
+            "tools — files created by either are immediately visible to both. "
+            "Execution is killed after the timeout (default 30s, max 120s). "
+            "Returns stdout and stderr. "
+            "Useful for file manipulation, data processing, running scripts, "
+            "and installing packages."
         )
 
     @property
@@ -53,11 +59,13 @@ class BashExecTool(BaseTool):
             "properties": {
                 "command": {
                     "type": "string",
-                    "description": "Bash command or script.",
+                    "description": "Bash command or script to execute.",
                 },
                 "timeout": {
                     "type": "integer",
-                    "description": "Max seconds (default 30, max 120).",
+                    "description": (
+                        "Max execution time in seconds (default 30, max 120)."
+                    ),
                     "default": 30,
                 },
             },

autogpt_platform/backend/backend/copilot/tools/continue_run_block.py

@@ -30,7 +30,12 @@ class ContinueRunBlockTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Resume block execution after human review approval. Pass the review_id."
+        return (
+            "Continue executing a block after human review approval. "
+            "Use this after a run_block call returned review_required. "
+            "Pass the review_id from the review_required response. "
+            "The block will execute with the original pre-approved input data."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -39,7 +44,10 @@ class ContinueRunBlockTool(BaseTool):
             "properties": {
                 "review_id": {
                     "type": "string",
-                    "description": "review_id from the review_required response.",
+                    "description": (
+                        "The review_id from a previous review_required response. "
+                        "This resumes execution with the pre-approved input data."
+                    ),
                 },
             },
             "required": ["review_id"],

autogpt_platform/backend/backend/copilot/tools/create_agent.py

@@ -23,8 +23,12 @@ class CreateAgentTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Create a new agent from JSON (nodes + links). Validates, auto-fixes, and saves. "
-            "Before calling, search for existing agents with find_library_agent."
+            "Create a new agent workflow. Pass `agent_json` with the complete "
+            "agent graph JSON you generated using block schemas from find_block. "
+            "The tool validates, auto-fixes, and saves.\n\n"
+            "IMPORTANT: Before calling this tool, search for relevant existing agents "
+            "using find_library_agent that could be used as building blocks. "
+            "Pass their IDs in the library_agent_ids parameter."
         )
 
     @property
@@ -38,21 +42,34 @@ class CreateAgentTool(BaseTool):
             "properties": {
                 "agent_json": {
                     "type": "object",
-                    "description": "Agent graph with 'nodes' and 'links' arrays.",
+                    "description": (
+                        "The agent JSON to validate and save. "
+                        "Must contain 'nodes' and 'links' arrays, and optionally "
+                        "'name' and 'description'."
+                    ),
                 },
                 "library_agent_ids": {
                     "type": "array",
                     "items": {"type": "string"},
-                    "description": "Library agent IDs as building blocks.",
+                    "description": (
+                        "List of library agent IDs to use as building blocks."
+                    ),
                 },
                 "save": {
                     "type": "boolean",
-                    "description": "Save the agent (default: true). False for preview.",
+                    "description": (
+                        "Whether to save the agent. Default is true. "
+                        "Set to false for preview only."
+                    ),
                     "default": True,
                 },
                 "folder_id": {
                     "type": "string",
-                    "description": "Folder ID to save into (default: root).",
+                    "description": (
+                        "Optional folder ID to save the agent into. "
+                        "If not provided, the agent is saved at root level. "
+                        "Use list_folders to find available folders."
+                    ),
                 },
             },
             "required": ["agent_json"],

autogpt_platform/backend/backend/copilot/tools/customize_agent.py

@@ -23,7 +23,9 @@ class CustomizeAgentTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Customize a marketplace/template agent. Validates, auto-fixes, and saves."
+            "Customize a marketplace or template agent. Pass `agent_json` "
+            "with the complete customized agent JSON. The tool validates, "
+            "auto-fixes, and saves."
         )
 
     @property
@@ -37,21 +39,32 @@ class CustomizeAgentTool(BaseTool):
             "properties": {
                 "agent_json": {
                     "type": "object",
-                    "description": "Customized agent JSON with nodes and links.",
+                    "description": (
+                        "Complete customized agent JSON to validate and save. "
+                        "Optionally include 'name' and 'description'."
+                    ),
                 },
                 "library_agent_ids": {
                     "type": "array",
                     "items": {"type": "string"},
-                    "description": "Library agent IDs as building blocks.",
+                    "description": (
+                        "List of library agent IDs to use as building blocks."
+                    ),
                 },
                 "save": {
                     "type": "boolean",
-                    "description": "Save the agent (default: true). False for preview.",
+                    "description": (
+                        "Whether to save the customized agent. Default is true."
+                    ),
                     "default": True,
                 },
                 "folder_id": {
                     "type": "string",
-                    "description": "Folder ID to save into (default: root).",
+                    "description": (
+                        "Optional folder ID to save the agent into. "
+                        "If not provided, the agent is saved at root level. "
+                        "Use list_folders to find available folders."
+                    ),
                 },
             },
             "required": ["agent_json"],

autogpt_platform/backend/backend/copilot/tools/edit_agent.py

@@ -23,8 +23,12 @@ class EditAgentTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Edit an existing agent. Validates, auto-fixes, and saves. "
-            "Before calling, search for existing agents with find_library_agent."
+            "Edit an existing agent. Pass `agent_json` with the complete "
+            "updated agent JSON you generated. The tool validates, auto-fixes, "
+            "and saves.\n\n"
+            "IMPORTANT: Before calling this tool, if the changes involve adding new "
+            "functionality, search for relevant existing agents using find_library_agent "
+            "that could be used as building blocks."
         )
 
     @property
@@ -38,20 +42,33 @@ class EditAgentTool(BaseTool):
             "properties": {
                 "agent_id": {
                     "type": "string",
-                    "description": "Graph ID or library agent ID to edit.",
+                    "description": (
+                        "The ID of the agent to edit. "
+                        "Can be a graph ID or library agent ID."
+                    ),
                 },
                 "agent_json": {
                     "type": "object",
-                    "description": "Updated agent JSON with nodes and links.",
+                    "description": (
+                        "Complete updated agent JSON to validate and save. "
+                        "Must contain 'nodes' and 'links'. "
+                        "Include 'name' and/or 'description' if they need "
+                        "to be updated."
+                    ),
                 },
                 "library_agent_ids": {
                     "type": "array",
                     "items": {"type": "string"},
-                    "description": "Library agent IDs as building blocks.",
+                    "description": (
+                        "List of library agent IDs to use as building blocks for the changes."
+                    ),
                 },
                 "save": {
                     "type": "boolean",
-                    "description": "Save changes (default: true). False for preview.",
+                    "description": (
+                        "Whether to save the changes. "
+                        "Default is true. Set to false for preview only."
+                    ),
                     "default": True,
                 },
             },

autogpt_platform/backend/backend/copilot/tools/feature_requests.py

@@ -134,7 +134,11 @@ class SearchFeatureRequestsTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Search existing feature requests. Check before creating a new one."
+        return (
+            "Search existing feature requests to check if a similar request "
+            "already exists before creating a new one. Returns matching feature "
+            "requests with their ID, title, and description."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -230,9 +234,14 @@ class CreateFeatureRequestTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Create a feature request or add need to existing one. "
-            "Search first to avoid duplicates. Pass existing_issue_id to add to existing. "
-            "Never include PII (names, emails, phone numbers, company names) in title/description."
+            "Create a new feature request or add a customer need to an existing one. "
+            "Always search first with search_feature_requests to avoid duplicates. "
+            "If a matching request exists, pass its ID as existing_issue_id to add "
+            "the user's need to it instead of creating a duplicate. "
+            "IMPORTANT: Never include personally identifiable information (PII) in "
+            "the title or description — no names, emails, phone numbers, company "
+            "names, or other identifying details. Write titles and descriptions in "
+            "generic, feature-focused language."
         )
 
     @property
@@ -242,15 +251,28 @@ class CreateFeatureRequestTool(BaseTool):
             "properties": {
                 "title": {
                     "type": "string",
-                    "description": "Feature request title. No PII.",
+                    "description": (
+                        "Title for the feature request. Must be generic and "
+                        "feature-focused — do not include any user names, emails, "
+                        "company names, or other PII."
+                    ),
                 },
                 "description": {
                     "type": "string",
-                    "description": "What the user wants and why. No PII.",
+                    "description": (
+                        "Detailed description of what the user wants and why. "
+                        "Must not contain any personally identifiable information "
+                        "(PII) — describe the feature need generically without "
+                        "referencing specific users, companies, or contact details."
+                    ),
                 },
                 "existing_issue_id": {
                     "type": "string",
-                    "description": "Linear issue ID to add need to (from search results).",
+                    "description": (
+                        "If adding a need to an existing feature request, "
+                        "provide its Linear issue ID (from search results). "
+                        "Omit to create a new feature request."
+                    ),
                 },
             },
             "required": ["title", "description"],

autogpt_platform/backend/backend/copilot/tools/find_agent.py

@@ -18,7 +18,9 @@ class FindAgentTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Search marketplace agents by capability."
+        return (
+            "Discover agents from the marketplace based on capabilities and user needs."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -27,7 +29,7 @@ class FindAgentTool(BaseTool):
             "properties": {
                 "query": {
                     "type": "string",
-                    "description": "Search keywords (single keywords work best).",
+                    "description": "Search query describing what the user wants to accomplish. Use single keywords for best results.",
                 },
             },
             "required": ["query"],

autogpt_platform/backend/backend/copilot/tools/find_block.py

@@ -51,7 +51,14 @@ class FindBlockTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Search blocks by name or description. Returns block IDs for run_block. Always call this FIRST to get block IDs before using run_block."
+        return (
+            "Search for available blocks by name or description. "
+            "Blocks are reusable components that perform specific tasks like "
+            "sending emails, making API calls, processing text, etc. "
+            "IMPORTANT: Use this tool FIRST to get the block's 'id' before calling run_block. "
+            "The response includes each block's id, name, and description. "
+            "Call run_block with the block's id **with no inputs** to see detailed inputs/outputs and execute it."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -60,11 +67,18 @@ class FindBlockTool(BaseTool):
             "properties": {
                 "query": {
                     "type": "string",
-                    "description": "Search keywords (e.g. 'email', 'http', 'ai').",
+                    "description": (
+                        "Search query to find blocks by name or description. "
+                        "Use keywords like 'email', 'http', 'text', 'ai', etc."
+                    ),
                 },
                 "include_schemas": {
                     "type": "boolean",
-                    "description": "Include full input/output schemas (for agent JSON generation).",
+                    "description": (
+                        "If true, include full input_schema and output_schema "
+                        "for each block. Use when generating agent JSON that "
+                        "needs block schemas. Default is false."
+                    ),
                     "default": False,
                 },
             },

autogpt_platform/backend/backend/copilot/tools/find_library_agent.py

@@ -19,8 +19,13 @@ class FindLibraryAgentTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Search user's library agents. Returns graph_id, schemas for sub-agent composition. "
-            "Omit query to list all."
+            "Search for or list agents in the user's library. Use this to find "
+            "agents the user has already added to their library, including agents "
+            "they created or added from the marketplace. "
+            "When creating agents with sub-agent composition, use this to get "
+            "the agent's graph_id, graph_version, input_schema, and output_schema "
+            "needed for AgentExecutorBlock nodes. "
+            "Omit the query to list all agents."
         )
 
     @property
@@ -30,7 +35,10 @@ class FindLibraryAgentTool(BaseTool):
             "properties": {
                 "query": {
                     "type": "string",
-                    "description": "Search by name/description. Omit to list all.",
+                    "description": (
+                        "Search query to find agents by name or description. "
+                        "Omit to list all agents in the library."
+                    ),
                 },
             },
             "required": [],

autogpt_platform/backend/backend/copilot/tools/fix_agent.py

@@ -22,8 +22,20 @@ class FixAgentGraphTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Auto-fix common agent JSON issues (UUIDs, types, credentials, spacing, etc.). "
-            "Returns fixed JSON and list of fixes applied."
+            "Auto-fix common issues in an agent JSON graph. Applies fixes for:\n"
+            "- Missing or invalid UUIDs on nodes and links\n"
+            "- StoreValueBlock prerequisites for ConditionBlock\n"
+            "- Double curly brace escaping in prompt templates\n"
+            "- AddToList/AddToDictionary prerequisite blocks\n"
+            "- CodeExecutionBlock output field naming\n"
+            "- Missing credentials configuration\n"
+            "- Node X coordinate spacing (800+ units apart)\n"
+            "- AI model default parameters\n"
+            "- Link static properties based on input schema\n"
+            "- Type mismatches (inserts conversion blocks)\n\n"
+            "Returns the fixed agent JSON plus a list of fixes applied. "
+            "After fixing, the agent is re-validated. If still invalid, "
+            "the remaining errors are included in the response."
         )
 
     @property

autogpt_platform/backend/backend/copilot/tools/get_agent_building_guide.py

@@ -42,7 +42,12 @@ class GetAgentBuildingGuideTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Get the agent JSON building guide (nodes, links, AgentExecutorBlock, MCPToolBlock usage). Call before generating agent JSON."
+        return (
+            "Returns the complete guide for building agent JSON graphs, including "
+            "block IDs, link structure, AgentInputBlock, AgentOutputBlock, "
+            "AgentExecutorBlock (for sub-agent composition), and MCPToolBlock usage. "
+            "Call this before generating agent JSON to ensure correct structure."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:

autogpt_platform/backend/backend/copilot/tools/get_doc_page.py

@@ -25,7 +25,8 @@ class GetDocPageTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Read full documentation page content by path (from search_docs results)."
+            "Get the full content of a documentation page by its path. "
+            "Use this after search_docs to read the complete content of a relevant page."
         )
 
     @property
@@ -35,7 +36,10 @@ class GetDocPageTool(BaseTool):
             "properties": {
                 "path": {
                     "type": "string",
-                    "description": "Doc file path (e.g. 'platform/block-sdk-guide.md').",
+                    "description": (
+                        "The path to the documentation file, as returned by search_docs. "
+                        "Example: 'platform/block-sdk-guide.md'"
+                    ),
                 },
             },
             "required": ["path"],

autogpt_platform/backend/backend/copilot/tools/get_mcp_guide.py

@@ -38,7 +38,11 @@ class GetMCPGuideTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Get MCP server URLs and auth guide."
+        return (
+            "Returns the MCP tool guide: known hosted server URLs (Notion, Linear, "
+            "Stripe, Intercom, Cloudflare, Atlassian) and authentication workflow. "
+            "Call before using run_mcp_tool if you need a server URL or auth info."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:

autogpt_platform/backend/backend/copilot/tools/manage_folders.py

@@ -88,7 +88,10 @@ class CreateFolderTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Create a library folder. Use parent_id to nest inside another folder."
+        return (
+            "Create a new folder in the user's library to organize agents. "
+            "Optionally nest it inside an existing folder using parent_id."
+        )
 
     @property
     def requires_auth(self) -> bool:
@@ -101,19 +104,22 @@ class CreateFolderTool(BaseTool):
             "properties": {
                 "name": {
                     "type": "string",
-                    "description": "Folder name (max 100 chars).",
+                    "description": "Name for the new folder (max 100 chars).",
                 },
                 "parent_id": {
                     "type": "string",
-                    "description": "Parent folder ID (omit for root).",
+                    "description": (
+                        "ID of the parent folder to nest inside. "
+                        "Omit to create at root level."
+                    ),
                 },
                 "icon": {
                     "type": "string",
-                    "description": "Icon identifier.",
+                    "description": "Optional icon identifier for the folder.",
                 },
                 "color": {
                     "type": "string",
-                    "description": "Hex color (#RRGGBB).",
+                    "description": "Optional hex color code (#RRGGBB).",
                 },
             },
             "required": ["name"],
@@ -169,8 +175,13 @@ class ListFoldersTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "List library folders. Omit parent_id for full tree. "
-            "Set include_agents=true when user asks about agents in folders."
+            "List the user's library folders. "
+            "Omit parent_id to get the full folder tree. "
+            "Provide parent_id to list only direct children of that folder. "
+            "Set include_agents=true to also return the agents inside each folder "
+            "and root-level agents not in any folder. Always set include_agents=true "
+            "when the user asks about agents, wants to see what's in their folders, "
+            "or mentions agents alongside folders."
         )
 
     @property
@@ -184,11 +195,17 @@ class ListFoldersTool(BaseTool):
             "properties": {
                 "parent_id": {
                     "type": "string",
-                    "description": "List children of this folder (omit for full tree).",
+                    "description": (
+                        "List children of this folder. "
+                        "Omit to get the full folder tree."
+                    ),
                 },
                 "include_agents": {
                     "type": "boolean",
-                    "description": "Include agents in each folder (default: false).",
+                    "description": (
+                        "Whether to include the list of agents inside each folder. "
+                        "Defaults to false."
+                    ),
                 },
             },
             "required": [],
@@ -340,7 +357,10 @@ class MoveFolderTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Move a folder. Set target_parent_id to null for root."
+        return (
+            "Move a folder to a different parent folder. "
+            "Set target_parent_id to null to move to root level."
+        )
 
     @property
     def requires_auth(self) -> bool:
@@ -353,11 +373,14 @@ class MoveFolderTool(BaseTool):
             "properties": {
                 "folder_id": {
                     "type": "string",
-                    "description": "Folder ID.",
+                    "description": "ID of the folder to move.",
                 },
                 "target_parent_id": {
                     "type": ["string", "null"],
-                    "description": "New parent folder ID (null for root).",
+                    "description": (
+                        "ID of the new parent folder. "
+                        "Use null to move to root level."
+                    ),
                 },
             },
             "required": ["folder_id"],
@@ -410,7 +433,10 @@ class DeleteFolderTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Delete a folder. Agents inside move to root (not deleted)."
+        return (
+            "Delete a folder from the user's library. "
+            "Agents inside the folder are moved to root level (not deleted)."
+        )
 
     @property
     def requires_auth(self) -> bool:
@@ -473,7 +499,10 @@ class MoveAgentsToFolderTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Move agents to a folder. Set folder_id to null for root."
+        return (
+            "Move one or more agents to a folder. "
+            "Set folder_id to null to move agents to root level."
+        )
 
     @property
     def requires_auth(self) -> bool:
@@ -487,11 +516,13 @@ class MoveAgentsToFolderTool(BaseTool):
                 "agent_ids": {
                     "type": "array",
                     "items": {"type": "string"},
-                    "description": "Library agent IDs to move.",
+                    "description": "List of library agent IDs to move.",
                 },
                 "folder_id": {
                     "type": ["string", "null"],
-                    "description": "Target folder ID (null for root).",
+                    "description": (
+                        "Target folder ID. Use null to move to root level."
+                    ),
                 },
             },
             "required": ["agent_ids"],

autogpt_platform/backend/backend/copilot/tools/run_agent.py

@@ -104,11 +104,19 @@ class RunAgentTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return (
-            "Run or schedule an agent. Automatically checks inputs and credentials. "
-            "Identify by username_agent_slug ('user/agent') or library_agent_id. "
-            "For scheduling, provide schedule_name + cron."
-        )
+        return """Run or schedule an agent from the marketplace or user's library.
+
+        The tool automatically handles the setup flow:
+        - Returns missing inputs if required fields are not provided
+        - Returns missing credentials if user needs to configure them
+        - Executes immediately if all requirements are met
+        - Schedules execution if cron expression is provided
+
+        Identify the agent using either:
+        - username_agent_slug: Marketplace format 'username/agent-name'
+        - library_agent_id: ID of an agent in the user's library
+
+        For scheduled execution, provide: schedule_name, cron, and optionally timezone."""
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -117,36 +125,40 @@ class RunAgentTool(BaseTool):
             "properties": {
                 "username_agent_slug": {
                     "type": "string",
-                    "description": "Marketplace format 'username/agent-name'.",
+                    "description": "Agent identifier in format 'username/agent-name'",
                 },
                 "library_agent_id": {
                     "type": "string",
-                    "description": "Library agent ID.",
+                    "description": "Library agent ID from user's library",
                 },
                 "inputs": {
                     "type": "object",
-                    "description": "Input values for the agent.",
+                    "description": "Input values for the agent",
                     "additionalProperties": True,
                 },
                 "use_defaults": {
                     "type": "boolean",
-                    "description": "Run with default values (confirm with user first).",
+                    "description": "Set to true to run with default values (user must confirm)",
                 },
                 "schedule_name": {
                     "type": "string",
-                    "description": "Name for scheduled execution.",
+                    "description": "Name for scheduled execution (triggers scheduling mode)",
                 },
                 "cron": {
                     "type": "string",
-                    "description": "Cron expression (min hour day month weekday).",
+                    "description": "Cron expression (5 fields: min hour day month weekday)",
                 },
                 "timezone": {
                     "type": "string",
-                    "description": "IANA timezone (default: UTC).",
+                    "description": "IANA timezone for schedule (default: UTC)",
                 },
                 "wait_for_result": {
                     "type": "integer",
-                    "description": "Max seconds to wait for completion (0-300).",
+                    "description": (
+                        "Max seconds to wait for execution to complete (0-300). "
+                        "If >0, blocks until the execution finishes or times out. "
+                        "Returns execution outputs when complete."
+                    ),
                 },
             },
             "required": [],

autogpt_platform/backend/backend/copilot/tools/run_block.py

@@ -12,7 +12,6 @@ from backend.copilot.constants import (
     COPILOT_SESSION_PREFIX,
 )
 from backend.copilot.model import ChatSession
-from backend.copilot.sdk.file_ref import FileRefExpansionError, expand_file_refs_in_args
 from backend.data.db_accessors import review_db
 from backend.data.execution import ExecutionContext
 
@@ -45,10 +44,13 @@ class RunBlockTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Execute a block. IMPORTANT: Always get block_id from find_block first "
-            "— do NOT guess or fabricate IDs. "
-            "Call with empty input_data to see schema, then with data to execute. "
-            "If review_required, use continue_run_block."
+            "Execute a specific block with the provided input data. "
+            "IMPORTANT: You MUST call find_block first to get the block's 'id' - "
+            "do NOT guess or make up block IDs. "
+            "On first attempt (without input_data), returns detailed schema showing "
+            "required inputs and outputs. Then call again with proper input_data to execute. "
+            "If a block requires human review, use continue_run_block with the "
+            "review_id after the user approves."
         )
 
     @property
@@ -58,14 +60,28 @@ class RunBlockTool(BaseTool):
             "properties": {
                 "block_id": {
                     "type": "string",
-                    "description": "Block ID from find_block results.",
+                    "description": (
+                        "The block's 'id' field from find_block results. "
+                        "NEVER guess this - always get it from find_block first."
+                    ),
+                },
+                "block_name": {
+                    "type": "string",
+                    "description": (
+                        "The block's human-readable name from find_block results. "
+                        "Used for display purposes in the UI."
+                    ),
                 },
                 "input_data": {
                     "type": "object",
-                    "description": "Input values. Use {} first to see schema.",
+                    "description": (
+                        "Input values for the block. "
+                        "First call with empty {} to see the block's schema, "
+                        "then call again with proper values to execute."
+                    ),
                 },
             },
-            "required": ["block_id", "input_data"],
+            "required": ["block_id", "block_name", "input_data"],
         }
 
     @property
@@ -181,29 +197,6 @@ class RunBlockTool(BaseTool):
                 session_id=session_id,
             )
 
-        # Expand @@agptfile: refs in input_data with the block's input
-        # schema.  The generic _truncating wrapper skips opaque object
-        # properties (input_data has no declared inner properties in the
-        # tool schema), so file ref tokens are still intact here.
-        # Using the block's schema lets us return raw text for string-typed
-        # fields and parsed structures for list/dict-typed fields.
-        if input_data:
-            try:
-                input_data = await expand_file_refs_in_args(
-                    input_data,
-                    user_id,
-                    session,
-                    input_schema=input_schema,
-                )
-            except FileRefExpansionError as exc:
-                return ErrorResponse(
-                    message=(
-                        f"Failed to resolve file reference: {exc}. "
-                        "Ensure the file exists before referencing it."
-                    ),
-                    session_id=session_id,
-                )
-
         if missing_credentials:
             # Return setup requirements response with missing credentials
             credentials_fields_info = block.input_schema.get_credentials_fields_info()

autogpt_platform/backend/backend/copilot/tools/run_mcp_tool.py

@@ -57,9 +57,10 @@ class RunMCPToolTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Discover and execute MCP server tools. "
-            "Call with server_url only to list tools, then with tool_name + tool_arguments to execute. "
-            "Call get_mcp_guide first for server URLs and auth."
+            "Connect to an MCP (Model Context Protocol) server to discover and execute its tools. "
+            "Two-step: (1) call with server_url to list available tools, "
+            "(2) call again with server_url + tool_name + tool_arguments to execute. "
+            "Call get_mcp_guide for known server URLs and auth details."
         )
 
     @property
@@ -69,15 +70,24 @@ class RunMCPToolTool(BaseTool):
             "properties": {
                 "server_url": {
                     "type": "string",
-                    "description": "MCP server URL (Streamable HTTP endpoint).",
+                    "description": (
+                        "URL of the MCP server (Streamable HTTP endpoint), "
+                        "e.g. https://mcp.example.com/mcp"
+                    ),
                 },
                 "tool_name": {
                     "type": "string",
-                    "description": "Tool to execute. Omit to discover available tools.",
+                    "description": (
+                        "Name of the MCP tool to execute. "
+                        "Omit on first call to discover available tools."
+                    ),
                 },
                 "tool_arguments": {
                     "type": "object",
-                    "description": "Arguments matching the tool's input schema.",
+                    "description": (
+                        "Arguments to pass to the selected tool. "
+                        "Must match the tool's input schema returned during discovery."
+                    ),
                 },
             },
             "required": ["server_url"],

autogpt_platform/backend/backend/copilot/tools/search_docs.py

@@ -38,7 +38,11 @@ class SearchDocsTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Search platform documentation by keyword. Use get_doc_page to read full results."
+        return (
+            "Search the AutoGPT platform documentation for information about "
+            "how to use the platform, build agents, configure blocks, and more. "
+            "Returns relevant documentation sections. Use get_doc_page to read full content."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -47,7 +51,10 @@ class SearchDocsTool(BaseTool):
             "properties": {
                 "query": {
                     "type": "string",
-                    "description": "Documentation search query.",
+                    "description": (
+                        "Search query to find relevant documentation. "
+                        "Use natural language to describe what you're looking for."
+                    ),
                 },
             },
             "required": ["query"],

autogpt_platform/backend/backend/copilot/tools/tool_schema_test.py

@@ -1,81 +0,0 @@
-"""Schema regression tests for all registered CoPilot tools.
-
-Validates that every tool in TOOL_REGISTRY produces a well-formed schema:
-- description is non-empty
-- all `required` fields exist in `properties`
-- every property has a `type` and `description`
-- total token budget does not regress past 8000 tokens
-"""
-
-import json
-
-import pytest
-import tiktoken
-
-from backend.copilot.tools import TOOL_REGISTRY
-
-_TOKEN_BUDGET = 8_000
-
-
-def _get_all_tool_schemas() -> list[tuple[str, object]]:
-    """Return (tool_name, openai_schema) pairs for every registered tool."""
-    return [(name, tool.as_openai_tool()) for name, tool in TOOL_REGISTRY.items()]
-
-
-_ALL_SCHEMAS = _get_all_tool_schemas()
-
-
-@pytest.mark.parametrize(
-    "tool_name,schema",
-    _ALL_SCHEMAS,
-    ids=[name for name, _ in _ALL_SCHEMAS],
-)
-class TestToolSchema:
-    """Validate schema invariants for every registered tool."""
-
-    def test_description_non_empty(self, tool_name: str, schema: dict) -> None:
-        desc = schema["function"].get("description", "")
-        assert desc, f"Tool '{tool_name}' has an empty description"
-
-    def test_required_fields_exist_in_properties(
-        self, tool_name: str, schema: dict
-    ) -> None:
-        params = schema["function"].get("parameters", {})
-        properties = params.get("properties", {})
-        required = params.get("required", [])
-        for field in required:
-            assert field in properties, (
-                f"Tool '{tool_name}': required field '{field}' "
-                f"not found in properties {list(properties.keys())}"
-            )
-
-    def test_every_property_has_type_and_description(
-        self, tool_name: str, schema: dict
-    ) -> None:
-        params = schema["function"].get("parameters", {})
-        properties = params.get("properties", {})
-        for prop_name, prop_def in properties.items():
-            assert (
-                "type" in prop_def
-            ), f"Tool '{tool_name}', property '{prop_name}' is missing 'type'"
-            assert (
-                "description" in prop_def
-            ), f"Tool '{tool_name}', property '{prop_name}' is missing 'description'"
-
-
-def test_total_schema_token_budget() -> None:
-    """Assert total tool schema size stays under the token budget.
-
-    This locks in the 34% token reduction from #12398 and prevents future
-    description bloat from eroding the gains. Budget is set to 8000 tokens.
-    Note: this measures tool JSON only (not the full system prompt); the actual
-    baseline for tool schemas alone is ~6470 tokens, giving ~19% headroom.
-    """
-    schemas = [tool.as_openai_tool() for tool in TOOL_REGISTRY.values()]
-    serialized = json.dumps(schemas)
-    enc = tiktoken.get_encoding("cl100k_base")
-    total_tokens = len(enc.encode(serialized))
-    assert total_tokens < _TOKEN_BUDGET, (
-        f"Tool schemas use {total_tokens} tokens, exceeding budget of {_TOKEN_BUDGET}. "
-        f"Description bloat detected — trim descriptions or raise the budget intentionally."
-    )

autogpt_platform/backend/backend/copilot/tools/validate_agent.py

@@ -21,7 +21,19 @@ class ValidateAgentGraphTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Validate agent JSON for correctness (block_ids, links, types, schemas). On failure, use fix_agent_graph to auto-fix."
+        return (
+            "Validate an agent JSON graph for correctness. Checks:\n"
+            "- All block_ids reference real blocks\n"
+            "- All links reference valid source/sink nodes and fields\n"
+            "- Required input fields are wired or have defaults\n"
+            "- Data types are compatible across links\n"
+            "- Nested sink links use correct notation\n"
+            "- Prompt templates use proper curly brace escaping\n"
+            "- AgentExecutorBlock configurations are valid\n\n"
+            "Call this after generating agent JSON to verify correctness. "
+            "If validation fails, either fix issues manually based on the error "
+            "descriptions, or call fix_agent_graph to auto-fix common problems."
+        )
 
     @property
     def requires_auth(self) -> bool:
@@ -34,7 +46,11 @@ class ValidateAgentGraphTool(BaseTool):
             "properties": {
                 "agent_json": {
                     "type": "object",
-                    "description": "Agent JSON with 'nodes' and 'links' arrays.",
+                    "description": (
+                        "The agent JSON to validate. Must contain 'nodes' and 'links' arrays. "
+                        "Each node needs: id (UUID), block_id, input_default, metadata. "
+                        "Each link needs: id (UUID), source_id, source_name, sink_id, sink_name."
+                    ),
                 },
             },
             "required": ["agent_json"],

autogpt_platform/backend/backend/copilot/tools/web_fetch.py

@@ -59,7 +59,13 @@ class WebFetchTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Fetch a public web page. Public URLs only — internal addresses blocked. Returns readable text from HTML by default."
+        return (
+            "Fetch the content of a public web page by URL. "
+            "Returns readable text extracted from HTML by default. "
+            "Useful for reading documentation, articles, and API responses. "
+            "Only supports HTTP/HTTPS GET requests to public URLs "
+            "(private/internal network addresses are blocked)."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -68,11 +74,14 @@ class WebFetchTool(BaseTool):
             "properties": {
                 "url": {
                     "type": "string",
-                    "description": "Public HTTP/HTTPS URL.",
+                    "description": "The public HTTP/HTTPS URL to fetch.",
                 },
                 "extract_text": {
                     "type": "boolean",
-                    "description": "Extract text from HTML (default: true).",
+                    "description": (
+                        "If true (default), extract readable text from HTML. "
+                        "If false, return raw content."
+                    ),
                     "default": True,
                 },
             },

autogpt_platform/backend/backend/copilot/tools/workspace_files.py

@@ -10,11 +10,11 @@ from pydantic import BaseModel
 from backend.copilot.context import (
     E2B_WORKDIR,
     get_current_sandbox,
-    get_workspace_manager,
     resolve_sandbox_path,
 )
 from backend.copilot.model import ChatSession
 from backend.copilot.tools.sandbox import make_session_path
+from backend.data.db_accessors import workspace_db
 from backend.util.settings import Config
 from backend.util.virus_scanner import scan_content_safe
 from backend.util.workspace import WorkspaceManager
@@ -218,6 +218,12 @@ def _is_text_mime(mime_type: str) -> bool:
     return any(mime_type.startswith(t) for t in _TEXT_MIME_PREFIXES)
 
 
+async def get_manager(user_id: str, session_id: str) -> WorkspaceManager:
+    """Create a session-scoped WorkspaceManager."""
+    workspace = await workspace_db().get_or_create_workspace(user_id)
+    return WorkspaceManager(user_id, workspace.id, session_id)
+
+
 async def _resolve_file(
     manager: WorkspaceManager,
     file_id: str | None,
@@ -321,7 +327,13 @@ class ListWorkspaceFilesTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "List persistent workspace files. For ephemeral session files, use SDK Glob/Read instead. Optionally filter by path prefix."
+        return (
+            "List files in the user's persistent workspace (cloud storage). "
+            "These files survive across sessions. "
+            "For ephemeral session files, use the SDK Read/Glob tools instead. "
+            "Returns file names, paths, sizes, and metadata. "
+            "Optionally filter by path prefix."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -330,17 +342,24 @@ class ListWorkspaceFilesTool(BaseTool):
             "properties": {
                 "path_prefix": {
                     "type": "string",
-                    "description": "Filter by path prefix (e.g. '/documents/').",
+                    "description": (
+                        "Optional path prefix to filter files "
+                        "(e.g., '/documents/' to list only files in documents folder). "
+                        "By default, only files from the current session are listed."
+                    ),
                 },
                 "limit": {
                     "type": "integer",
-                    "description": "Max files to return (default 50, max 100).",
+                    "description": "Maximum number of files to return (default 50, max 100)",
                     "minimum": 1,
                     "maximum": 100,
                 },
                 "include_all_sessions": {
                     "type": "boolean",
-                    "description": "Include files from all sessions (default: false).",
+                    "description": (
+                        "If true, list files from all sessions. "
+                        "Default is false (only current session's files)."
+                    ),
                 },
             },
             "required": [],
@@ -367,7 +386,7 @@ class ListWorkspaceFilesTool(BaseTool):
         include_all_sessions: bool = kwargs.get("include_all_sessions", False)
 
         try:
-            manager = await get_workspace_manager(user_id, session_id)
+            manager = await get_manager(user_id, session_id)
             files = await manager.list_files(
                 path=path_prefix, limit=limit, include_all_sessions=include_all_sessions
             )
@@ -423,10 +442,18 @@ class ReadWorkspaceFileTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Read a file from persistent workspace. Specify file_id or path. "
-            "Small text/image files return inline; large/binary return metadata+URL. "
-            "Use save_to_path to copy to working dir for processing. "
-            "Use offset/length for paginated reads."
+            "Read a file from the user's persistent workspace (cloud storage). "
+            "These files survive across sessions. "
+            "For ephemeral session files, use the SDK Read tool instead. "
+            "Specify either file_id or path to identify the file. "
+            "For small text files, returns content directly. "
+            "For large or binary files, returns metadata and a download URL. "
+            "Use 'save_to_path' to copy the file to the working directory "
+            "(sandbox or ephemeral) for processing with bash_exec or file tools. "
+            "Use 'offset' and 'length' for paginated reads of large files "
+            "(e.g., persisted tool outputs). "
+            "Paths are scoped to the current session by default. "
+            "Use /sessions/<session_id>/... for cross-session access."
         )
 
     @property
@@ -436,30 +463,48 @@ class ReadWorkspaceFileTool(BaseTool):
             "properties": {
                 "file_id": {
                     "type": "string",
-                    "description": "File ID from list_workspace_files.",
+                    "description": "The file's unique ID (from list_workspace_files)",
                 },
                 "path": {
                     "type": "string",
-                    "description": "Virtual file path (e.g. '/documents/report.pdf').",
+                    "description": (
+                        "The virtual file path (e.g., '/documents/report.pdf'). "
+                        "Scoped to current session by default."
+                    ),
                 },
                 "save_to_path": {
                     "type": "string",
-                    "description": "Copy file to this working directory path for processing.",
+                    "description": (
+                        "If provided, save the file to this path in the working "
+                        "directory (cloud sandbox when E2B is active, or "
+                        "ephemeral dir otherwise) so it can be processed with "
+                        "bash_exec or file tools. "
+                        "The file content is still returned in the response."
+                    ),
                 },
                 "force_download_url": {
                     "type": "boolean",
-                    "description": "Always return metadata+URL instead of inline content.",
+                    "description": (
+                        "If true, always return metadata+URL instead of inline content. "
+                        "Default is false (auto-selects based on file size/type)."
+                    ),
                 },
                 "offset": {
                     "type": "integer",
-                    "description": "Character offset for paginated reads (0-based).",
+                    "description": (
+                        "Character offset to start reading from (0-based). "
+                        "Use with 'length' for paginated reads of large files."
+                    ),
                 },
                 "length": {
                     "type": "integer",
-                    "description": "Max characters to return for paginated reads.",
+                    "description": (
+                        "Maximum number of characters to return. "
+                        "Defaults to full file. Use with 'offset' for paginated reads."
+                    ),
                 },
             },
-            "required": [],  # At least one of file_id or path must be provided
+            "required": [],  # At least one must be provided
         }
 
     @property
@@ -491,7 +536,7 @@ class ReadWorkspaceFileTool(BaseTool):
             )
 
         try:
-            manager = await get_workspace_manager(user_id, session_id)
+            manager = await get_manager(user_id, session_id)
             resolved = await _resolve_file(manager, file_id, path, session_id)
             if isinstance(resolved, ErrorResponse):
                 return resolved
@@ -614,9 +659,15 @@ class WriteWorkspaceFileTool(BaseTool):
     @property
     def description(self) -> str:
         return (
-            "Write a file to persistent workspace (survives across sessions). "
-            "Provide exactly one of: content (text), content_base64 (binary), "
-            f"or source_path (copy from working dir). Max {Config().max_file_size_mb}MB."
+            "Write or create a file in the user's persistent workspace (cloud storage). "
+            "These files survive across sessions. "
+            "For ephemeral session files, use the SDK Write tool instead. "
+            "Provide content as plain text via 'content', OR base64-encoded via "
+            "'content_base64', OR copy a file from the ephemeral working directory "
+            "via 'source_path'. Exactly one of these three is required. "
+            f"Maximum file size is {Config().max_file_size_mb}MB. "
+            "Files are saved to the current session's folder by default. "
+            "Use /sessions/<session_id>/... for cross-session access."
         )
 
     @property
@@ -626,31 +677,51 @@ class WriteWorkspaceFileTool(BaseTool):
             "properties": {
                 "filename": {
                     "type": "string",
-                    "description": "Filename (e.g. 'report.pdf').",
+                    "description": "Name for the file (e.g., 'report.pdf')",
                 },
                 "content": {
                     "type": "string",
-                    "description": "Plain text content. Mutually exclusive with content_base64/source_path.",
+                    "description": (
+                        "Plain text content to write. Use this for text files "
+                        "(code, configs, documents, etc.). "
+                        "Mutually exclusive with content_base64 and source_path."
+                    ),
                 },
                 "content_base64": {
                     "type": "string",
-                    "description": "Base64-encoded binary content. Mutually exclusive with content/source_path.",
+                    "description": (
+                        "Base64-encoded file content. Use this for binary files "
+                        "(images, PDFs, etc.). "
+                        "Mutually exclusive with content and source_path."
+                    ),
                 },
                 "source_path": {
                     "type": "string",
-                    "description": "Working directory path to copy to workspace. Mutually exclusive with content/content_base64.",
+                    "description": (
+                        "Path to a file in the ephemeral working directory to "
+                        "copy to workspace (e.g., '/tmp/copilot-.../output.csv'). "
+                        "Use this to persist files created by bash_exec or SDK Write. "
+                        "Mutually exclusive with content and content_base64."
+                    ),
                 },
                 "path": {
                     "type": "string",
-                    "description": "Virtual path (e.g. '/documents/report.pdf'). Defaults to '/{filename}'.",
+                    "description": (
+                        "Optional virtual path where to save the file "
+                        "(e.g., '/documents/report.pdf'). "
+                        "Defaults to '/{filename}'. Scoped to current session."
+                    ),
                 },
                 "mime_type": {
                     "type": "string",
-                    "description": "MIME type. Auto-detected from filename if omitted.",
+                    "description": (
+                        "Optional MIME type of the file. "
+                        "Auto-detected from filename if not provided."
+                    ),
                 },
                 "overwrite": {
                     "type": "boolean",
-                    "description": "Overwrite if file exists (default: false).",
+                    "description": "Whether to overwrite if file exists at path (default: false)",
                 },
             },
             "required": ["filename"],
@@ -701,7 +772,7 @@ class WriteWorkspaceFileTool(BaseTool):
 
         try:
             await scan_content_safe(content, filename=filename)
-            manager = await get_workspace_manager(user_id, session_id)
+            manager = await get_manager(user_id, session_id)
             rec = await manager.write_file(
                 content=content,
                 filename=filename,
@@ -777,7 +848,12 @@ class DeleteWorkspaceFileTool(BaseTool):
 
     @property
     def description(self) -> str:
-        return "Delete a file from persistent workspace. Specify file_id or path."
+        return (
+            "Delete a file from the user's persistent workspace (cloud storage). "
+            "Specify either file_id or path to identify the file. "
+            "Paths are scoped to the current session by default. "
+            "Use /sessions/<session_id>/... for cross-session access."
+        )
 
     @property
     def parameters(self) -> dict[str, Any]:
@@ -786,14 +862,17 @@ class DeleteWorkspaceFileTool(BaseTool):
             "properties": {
                 "file_id": {
                     "type": "string",
-                    "description": "File ID from list_workspace_files.",
+                    "description": "The file's unique ID (from list_workspace_files)",
                 },
                 "path": {
                     "type": "string",
-                    "description": "Virtual file path.",
+                    "description": (
+                        "The virtual file path (e.g., '/documents/report.pdf'). "
+                        "Scoped to current session by default."
+                    ),
                 },
             },
-            "required": [],  # At least one of file_id or path must be provided
+            "required": [],  # At least one must be provided
         }
 
     @property
@@ -820,7 +899,7 @@ class DeleteWorkspaceFileTool(BaseTool):
             )
 
         try:
-            manager = await get_workspace_manager(user_id, session_id)
+            manager = await get_manager(user_id, session_id)
             resolved = await _resolve_file(manager, file_id, path, session_id)
             if isinstance(resolved, ErrorResponse):
                 return resolved

autogpt_platform/backend/backend/util/file.py

@@ -275,12 +275,13 @@ async def store_media_file(
     # Process file
     elif file.startswith("data:"):
         # Data URI
-        parsed_uri = parse_data_uri(file)
-        if parsed_uri is None:
+        match = re.match(r"^data:([^;]+);base64,(.*)$", file, re.DOTALL)
+        if not match:
             raise ValueError(
                 "Invalid data URI format. Expected data:<mime>;base64,<data>"
             )
-        mime_type, b64_content = parsed_uri
+        mime_type = match.group(1).strip().lower()
+        b64_content = match.group(2).strip()
 
         # Generate filename and decode
         extension = _extension_from_mime(mime_type)
@@ -414,70 +415,13 @@ def get_dir_size(path: Path) -> int:
     return total
 
 
-async def resolve_media_content(
-    content: MediaFileType,
-    execution_context: "ExecutionContext",
-    *,
-    return_format: MediaReturnFormat,
-) -> MediaFileType:
-    """Resolve a ``MediaFileType`` value if it is a media reference, pass through otherwise.
-
-    Convenience wrapper around :func:`is_media_file_ref` + :func:`store_media_file`.
-    Plain text content (source code, filenames) is returned unchanged.  Media
-    references (``data:``, ``workspace://``, ``http(s)://``) are resolved via
-    :func:`store_media_file` using *return_format*.
-
-    Use this when a block field is typed as ``MediaFileType`` but may contain
-    either literal text or a media reference.
-    """
-    if not content or not is_media_file_ref(content):
-        return content
-    return await store_media_file(
-        content, execution_context, return_format=return_format
-    )
-
-
-def is_media_file_ref(value: str) -> bool:
-    """Return True if *value* looks like a ``MediaFileType`` reference.
-
-    Detects data URIs, workspace:// references, and HTTP(S) URLs — the
-    formats accepted by :func:`store_media_file`.  Plain text content
-    (e.g. source code, filenames) returns False.
-
-    Known limitation: HTTP(S) URL detection is heuristic.  Any string that
-    starts with ``http://`` or ``https://`` is treated as a media URL, even
-    if it appears as a URL inside source-code comments or documentation.
-    Blocks that produce source code or Markdown as output may therefore
-    trigger false positives.  Callers that need higher precision should
-    inspect the string further (e.g. verify the URL is reachable or has a
-    media-friendly extension).
-
-    Note: this does *not* match local file paths, which are ambiguous
-    (could be filenames or actual paths).  Blocks that need to resolve
-    local paths should check for them separately.
-    """
-    return value.startswith(("data:", "workspace://", "http://", "https://"))
-
-
-def parse_data_uri(value: str) -> tuple[str, str] | None:
-    """Parse a ``data:<mime>;base64,<payload>`` URI.
-
-    Returns ``(mime_type, base64_payload)`` if *value* is a valid data URI,
-    or ``None`` if it is not.
-    """
-    match = re.match(r"^data:([^;]+);base64,(.*)$", value, re.DOTALL)
-    if not match:
-        return None
-    return match.group(1).strip().lower(), match.group(2).strip()
-
-
 def get_mime_type(file: str) -> str:
     """
     Get the MIME type of a file, whether it's a data URI, URL, or local path.
     """
     if file.startswith("data:"):
-        parsed_uri = parse_data_uri(file)
-        return parsed_uri[0] if parsed_uri else "application/octet-stream"
+        match = re.match(r"^data:([^;]+);base64,", file)
+        return match.group(1) if match else "application/octet-stream"
 
     elif file.startswith(("http://", "https://")):
         parsed_url = urlparse(file)

autogpt_platform/backend/backend/util/file_content_parser.py

@@ -1,375 +0,0 @@
-"""Parse file content into structured Python objects based on file format.
-
-Used by the ``@@agptfile:`` expansion system to eagerly parse well-known file
-formats into native Python types *before* schema-driven coercion runs.  This
-lets blocks with ``Any``-typed inputs receive structured data rather than raw
-strings, while blocks expecting strings get the value coerced back via
-``convert()``.
-
-Supported formats:
-
-- **JSON** (``.json``) — arrays and objects are promoted; scalars stay as strings
-- **JSON Lines** (``.jsonl``, ``.ndjson``) — each non-empty line parsed as JSON;
-  when all lines are dicts with the same keys (tabular data), output is
-  ``list[list[Any]]`` with a header row, consistent with CSV/Parquet/Excel;
-  otherwise returns a plain ``list`` of parsed values
-- **CSV** (``.csv``) — ``csv.reader`` → ``list[list[str]]``
-- **TSV** (``.tsv``) — tab-delimited → ``list[list[str]]``
-- **YAML** (``.yaml``, ``.yml``) — parsed via PyYAML; containers only
-- **TOML** (``.toml``) — parsed via stdlib ``tomllib``
-- **Parquet** (``.parquet``) — via pandas/pyarrow → ``list[list[Any]]`` with header row
-- **Excel** (``.xlsx``) — via pandas/openpyxl → ``list[list[Any]]`` with header row
-  (legacy ``.xls`` is **not** supported — only the modern OOXML format)
-
-The **fallback contract** is enforced by :func:`parse_file_content`, not by
-individual parser functions.  If any parser raises, ``parse_file_content``
-catches the exception and returns the original content unchanged (string for
-text formats, bytes for binary formats).  Callers should never see an
-exception from the public API when ``strict=False``.
-"""
-
-import csv
-import io
-import json
-import logging
-import tomllib
-import zipfile
-from collections.abc import Callable
-
-# posixpath.splitext handles forward-slash URI paths correctly on all platforms,
-# unlike os.path.splitext which uses platform-native separators.
-from posixpath import splitext
-from typing import Any
-
-import yaml
-
-logger = logging.getLogger(__name__)
-
-# ---------------------------------------------------------------------------
-# Extension / MIME → format label mapping
-# ---------------------------------------------------------------------------
-
-_EXT_TO_FORMAT: dict[str, str] = {
-    ".json": "json",
-    ".jsonl": "jsonl",
-    ".ndjson": "jsonl",
-    ".csv": "csv",
-    ".tsv": "tsv",
-    ".yaml": "yaml",
-    ".yml": "yaml",
-    ".toml": "toml",
-    ".parquet": "parquet",
-    ".xlsx": "xlsx",
-}
-
-MIME_TO_FORMAT: dict[str, str] = {
-    "application/json": "json",
-    "application/x-ndjson": "jsonl",
-    "application/jsonl": "jsonl",
-    "text/csv": "csv",
-    "text/tab-separated-values": "tsv",
-    "application/x-yaml": "yaml",
-    "application/yaml": "yaml",
-    "text/yaml": "yaml",
-    "application/toml": "toml",
-    "application/vnd.apache.parquet": "parquet",
-    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "xlsx",
-}
-
-# Formats that require raw bytes rather than decoded text.
-BINARY_FORMATS: frozenset[str] = frozenset({"parquet", "xlsx"})
-
-
-# ---------------------------------------------------------------------------
-# Public API  (top-down: main functions first, helpers below)
-# ---------------------------------------------------------------------------
-
-
-def infer_format_from_uri(uri: str) -> str | None:
-    """Return a format label based on URI extension or MIME fragment.
-
-    Returns ``None`` when the format cannot be determined — the caller should
-    fall back to returning the content as a plain string.
-    """
-    # 1. Check MIME fragment  (workspace://abc123#application/json)
-    if "#" in uri:
-        _, fragment = uri.rsplit("#", 1)
-        fmt = MIME_TO_FORMAT.get(fragment.lower())
-        if fmt:
-            return fmt
-
-    # 2. Check file extension from the path portion.
-    #    Strip the fragment first so ".json#mime" doesn't confuse splitext.
-    path = uri.split("#")[0].split("?")[0]
-    _, ext = splitext(path)
-    fmt = _EXT_TO_FORMAT.get(ext.lower())
-    if fmt is not None:
-        return fmt
-
-    # Legacy .xls is not supported — map it so callers can produce a
-    # user-friendly error instead of returning garbled binary.
-    if ext.lower() == ".xls":
-        return "xls"
-
-    return None
-
-
-def parse_file_content(content: str | bytes, fmt: str, *, strict: bool = False) -> Any:
-    """Parse *content* according to *fmt* and return a native Python value.
-
-    When *strict* is ``False`` (default), returns the original *content*
-    unchanged if *fmt* is not recognised or parsing fails for any reason.
-    This mode **never raises**.
-
-    When *strict* is ``True``, parsing errors are propagated to the caller.
-    Unrecognised formats or type mismatches (e.g. text for a binary format)
-    still return *content* unchanged without raising.
-    """
-    if fmt == "xls":
-        return (
-            "[Unsupported format] Legacy .xls files are not supported. "
-            "Please re-save the file as .xlsx (Excel 2007+) and upload again."
-        )
-
-    try:
-        if fmt in BINARY_FORMATS:
-            parser = _BINARY_PARSERS.get(fmt)
-            if parser is None:
-                return content
-            if isinstance(content, str):
-                # Caller gave us text for a binary format — can't parse.
-                return content
-            return parser(content)
-
-        parser = _TEXT_PARSERS.get(fmt)
-        if parser is None:
-            return content
-        if isinstance(content, bytes):
-            content = content.decode("utf-8", errors="replace")
-        return parser(content)
-
-    except PARSE_EXCEPTIONS:
-        if strict:
-            raise
-        logger.debug("Structured parsing failed for format=%s, falling back", fmt)
-        return content
-
-
-# ---------------------------------------------------------------------------
-# Exception loading helpers
-# ---------------------------------------------------------------------------
-
-
-def _load_openpyxl_exception() -> type[Exception]:
-    """Return openpyxl's InvalidFileException, raising ImportError if absent."""
-    from openpyxl.utils.exceptions import InvalidFileException  # noqa: PLC0415
-
-    return InvalidFileException
-
-
-def _load_arrow_exception() -> type[Exception]:
-    """Return pyarrow's ArrowException, raising ImportError if absent."""
-    from pyarrow import ArrowException  # noqa: PLC0415
-
-    return ArrowException
-
-
-def _optional_exc(loader: "Callable[[], type[Exception]]") -> "type[Exception] | None":
-    """Return the exception class from *loader*, or ``None`` if the dep is absent."""
-    try:
-        return loader()
-    except ImportError:
-        return None
-
-
-# Exception types that can be raised during file content parsing.
-# Shared between ``parse_file_content`` (which catches them in non-strict mode)
-# and ``file_ref._expand_bare_ref`` (which re-raises them as FileRefExpansionError).
-#
-# Optional-dependency exception types are loaded via a helper that raises
-# ``ImportError`` at *parse time* rather than silently becoming ``None`` here.
-# This ensures mypy sees clean types and missing deps surface as real errors.
-PARSE_EXCEPTIONS: tuple[type[BaseException], ...] = tuple(
-    exc
-    for exc in (
-        json.JSONDecodeError,
-        csv.Error,
-        yaml.YAMLError,
-        tomllib.TOMLDecodeError,
-        ValueError,
-        UnicodeDecodeError,
-        ImportError,
-        OSError,
-        KeyError,
-        TypeError,
-        zipfile.BadZipFile,
-        _optional_exc(_load_openpyxl_exception),
-        # ArrowException covers ArrowIOError and ArrowCapacityError which
-        # do not inherit from standard exceptions; ArrowInvalid/ArrowTypeError
-        # already map to ValueError/TypeError but this catches the rest.
-        _optional_exc(_load_arrow_exception),
-    )
-    if exc is not None
-)
-
-
-# ---------------------------------------------------------------------------
-# Text-based parsers  (content: str → Any)
-# ---------------------------------------------------------------------------
-
-
-def _parse_container(parser: Callable[[str], Any], content: str) -> list | dict | str:
-    """Parse *content* and return the result only if it is a container (list/dict).
-
-    Scalar values (strings, numbers, booleans, None) are discarded and the
-    original *content* string is returned instead.  This prevents e.g. a JSON
-    file containing just ``"42"`` from silently becoming an int.
-    """
-    parsed = parser(content)
-    if isinstance(parsed, (list, dict)):
-        return parsed
-    return content
-
-
-def _parse_json(content: str) -> list | dict | str:
-    return _parse_container(json.loads, content)
-
-
-def _parse_jsonl(content: str) -> Any:
-    lines = [json.loads(line) for line in content.splitlines() if line.strip()]
-    if not lines:
-        return content
-
-    # When every line is a dict with the same keys, convert to table format
-    # (header row + data rows) — consistent with CSV/TSV/Parquet/Excel output.
-    # Require ≥2 dicts so a single-line JSONL stays as [dict] (not a table).
-    if len(lines) >= 2 and all(isinstance(obj, dict) for obj in lines):
-        keys = list(lines[0].keys())
-        # Cache as tuple to avoid O(n×k) list allocations in the all() call.
-        keys_tuple = tuple(keys)
-        if keys and all(tuple(obj.keys()) == keys_tuple for obj in lines[1:]):
-            return [keys] + [[obj[k] for k in keys] for obj in lines]
-
-    return lines
-
-
-def _parse_csv(content: str) -> Any:
-    return _parse_delimited(content, delimiter=",")
-
-
-def _parse_tsv(content: str) -> Any:
-    return _parse_delimited(content, delimiter="\t")
-
-
-def _parse_delimited(content: str, *, delimiter: str) -> Any:
-    reader = csv.reader(io.StringIO(content), delimiter=delimiter)
-    # csv.reader never yields [] — blank lines yield [""]. Filter out
-    # rows where every cell is empty (i.e. truly blank lines).
-    rows = [row for row in reader if _row_has_content(row)]
-    if not rows:
-        return content
-    # If the declared delimiter produces only single-column rows, try
-    # sniffing the actual delimiter — catches misidentified files (e.g.
-    # a tab-delimited file with a .csv extension).
-    if len(rows[0]) == 1:
-        try:
-            dialect = csv.Sniffer().sniff(content[:8192])
-            if dialect.delimiter != delimiter:
-                reader = csv.reader(io.StringIO(content), dialect)
-                rows = [row for row in reader if _row_has_content(row)]
-        except csv.Error:
-            pass
-    if rows and len(rows[0]) >= 2:
-        return rows
-    return content
-
-
-def _row_has_content(row: list[str]) -> bool:
-    """Return True when *row* contains at least one non-empty cell.
-
-    ``csv.reader`` never yields ``[]`` — truly blank lines yield ``[""]``.
-    This predicate filters those out consistently across the initial read
-    and the sniffer-fallback re-read.
-    """
-    return any(cell for cell in row)
-
-
-def _parse_yaml(content: str) -> list | dict | str:
-    # NOTE: YAML anchor/alias expansion can amplify input beyond the 10MB cap.
-    # safe_load prevents code execution; for production hardening consider
-    # a YAML parser with expansion limits (e.g. ruamel.yaml with max_alias_count).
-    if "\n---" in content or content.startswith("---\n"):
-        # Multi-document YAML: only the first document is parsed; the rest
-        # are silently ignored by yaml.safe_load.  Warn so callers are aware.
-        logger.warning(
-            "Multi-document YAML detected (--- separator); "
-            "only the first document will be parsed."
-        )
-    return _parse_container(yaml.safe_load, content)
-
-
-def _parse_toml(content: str) -> Any:
-    parsed = tomllib.loads(content)
-    # tomllib.loads always returns a dict — return it even if empty.
-    return parsed
-
-
-_TEXT_PARSERS: dict[str, Callable[[str], Any]] = {
-    "json": _parse_json,
-    "jsonl": _parse_jsonl,
-    "csv": _parse_csv,
-    "tsv": _parse_tsv,
-    "yaml": _parse_yaml,
-    "toml": _parse_toml,
-}
-
-# ---------------------------------------------------------------------------
-# Binary-based parsers  (content: bytes → Any)
-# ---------------------------------------------------------------------------
-
-
-def _parse_parquet(content: bytes) -> list[list[Any]]:
-    import pandas as pd
-
-    df = pd.read_parquet(io.BytesIO(content))
-    return _df_to_rows(df)
-
-
-def _parse_xlsx(content: bytes) -> list[list[Any]]:
-    import pandas as pd
-
-    # Explicitly specify openpyxl engine; the default engine varies by pandas
-    # version and does not support legacy .xls (which is excluded by our format map).
-    df = pd.read_excel(io.BytesIO(content), engine="openpyxl")
-    return _df_to_rows(df)
-
-
-def _df_to_rows(df: Any) -> list[list[Any]]:
-    """Convert a DataFrame to ``list[list[Any]]`` with a header row.
-
-    NaN values are replaced with ``None`` so the result is JSON-serializable.
-    Uses explicit cell-level checking because ``df.where(df.notna(), None)``
-    silently converts ``None`` back to ``NaN`` in float64 columns.
-    """
-    header = df.columns.tolist()
-    rows = [
-        [None if _is_nan(cell) else cell for cell in row] for row in df.values.tolist()
-    ]
-    return [header] + rows
-
-
-def _is_nan(cell: Any) -> bool:
-    """Check if a cell value is NaN, handling non-scalar types (lists, dicts).
-
-    ``pd.isna()`` on a list/dict returns a boolean array which raises
-    ``ValueError`` in a boolean context.  Guard with a scalar check first.
-    """
-    import pandas as pd
-
-    return bool(pd.api.types.is_scalar(cell) and pd.isna(cell))
-
-
-_BINARY_PARSERS: dict[str, Callable[[bytes], Any]] = {
-    "parquet": _parse_parquet,
-    "xlsx": _parse_xlsx,
-}

autogpt_platform/backend/backend/util/file_content_parser_test.py

@@ -1,624 +0,0 @@
-"""Tests for file_content_parser — format inference and structured parsing."""
-
-import io
-import json
-
-import pytest
-
-from backend.util.file_content_parser import (
-    BINARY_FORMATS,
-    infer_format_from_uri,
-    parse_file_content,
-)
-
-# ---------------------------------------------------------------------------
-# infer_format_from_uri
-# ---------------------------------------------------------------------------
-
-
-class TestInferFormat:
-    # --- extension-based ---
-
-    def test_json_extension(self):
-        assert infer_format_from_uri("/home/user/data.json") == "json"
-
-    def test_jsonl_extension(self):
-        assert infer_format_from_uri("/tmp/events.jsonl") == "jsonl"
-
-    def test_ndjson_extension(self):
-        assert infer_format_from_uri("/tmp/events.ndjson") == "jsonl"
-
-    def test_csv_extension(self):
-        assert infer_format_from_uri("workspace:///reports/sales.csv") == "csv"
-
-    def test_tsv_extension(self):
-        assert infer_format_from_uri("/home/user/data.tsv") == "tsv"
-
-    def test_yaml_extension(self):
-        assert infer_format_from_uri("/home/user/config.yaml") == "yaml"
-
-    def test_yml_extension(self):
-        assert infer_format_from_uri("/home/user/config.yml") == "yaml"
-
-    def test_toml_extension(self):
-        assert infer_format_from_uri("/home/user/config.toml") == "toml"
-
-    def test_parquet_extension(self):
-        assert infer_format_from_uri("/data/table.parquet") == "parquet"
-
-    def test_xlsx_extension(self):
-        assert infer_format_from_uri("/data/spreadsheet.xlsx") == "xlsx"
-
-    def test_xls_extension_returns_xls_label(self):
-        # Legacy .xls is mapped so callers can produce a helpful error.
-        assert infer_format_from_uri("/data/old_spreadsheet.xls") == "xls"
-
-    def test_case_insensitive(self):
-        assert infer_format_from_uri("/data/FILE.JSON") == "json"
-        assert infer_format_from_uri("/data/FILE.CSV") == "csv"
-
-    def test_unicode_filename(self):
-        assert infer_format_from_uri("/home/user/\u30c7\u30fc\u30bf.json") == "json"
-        assert infer_format_from_uri("/home/user/\u00e9t\u00e9.csv") == "csv"
-
-    def test_unknown_extension(self):
-        assert infer_format_from_uri("/home/user/readme.txt") is None
-
-    def test_no_extension(self):
-        assert infer_format_from_uri("workspace://abc123") is None
-
-    # --- MIME-based ---
-
-    def test_mime_json(self):
-        assert infer_format_from_uri("workspace://abc123#application/json") == "json"
-
-    def test_mime_csv(self):
-        assert infer_format_from_uri("workspace://abc123#text/csv") == "csv"
-
-    def test_mime_tsv(self):
-        assert (
-            infer_format_from_uri("workspace://abc123#text/tab-separated-values")
-            == "tsv"
-        )
-
-    def test_mime_ndjson(self):
-        assert (
-            infer_format_from_uri("workspace://abc123#application/x-ndjson") == "jsonl"
-        )
-
-    def test_mime_yaml(self):
-        assert infer_format_from_uri("workspace://abc123#application/x-yaml") == "yaml"
-
-    def test_mime_xlsx(self):
-        uri = "workspace://abc123#application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
-        assert infer_format_from_uri(uri) == "xlsx"
-
-    def test_mime_parquet(self):
-        assert (
-            infer_format_from_uri("workspace://abc123#application/vnd.apache.parquet")
-            == "parquet"
-        )
-
-    def test_unknown_mime(self):
-        assert infer_format_from_uri("workspace://abc123#text/plain") is None
-
-    def test_unknown_mime_falls_through_to_extension(self):
-        # Unknown MIME (text/plain) should fall through to extension-based detection.
-        assert infer_format_from_uri("workspace:///data.csv#text/plain") == "csv"
-
-    # --- MIME takes precedence over extension ---
-
-    def test_mime_overrides_extension(self):
-        # .txt extension but JSON MIME → json
-        assert infer_format_from_uri("workspace:///file.txt#application/json") == "json"
-
-
-# ---------------------------------------------------------------------------
-# parse_file_content — JSON
-# ---------------------------------------------------------------------------
-
-
-class TestParseJson:
-    def test_array(self):
-        result = parse_file_content("[1, 2, 3]", "json")
-        assert result == [1, 2, 3]
-
-    def test_object(self):
-        result = parse_file_content('{"key": "value"}', "json")
-        assert result == {"key": "value"}
-
-    def test_nested(self):
-        content = json.dumps({"rows": [[1, 2], [3, 4]]})
-        result = parse_file_content(content, "json")
-        assert result == {"rows": [[1, 2], [3, 4]]}
-
-    def test_scalar_string_stays_as_string(self):
-        result = parse_file_content('"hello"', "json")
-        assert result == '"hello"'  # original content, not parsed
-
-    def test_scalar_number_stays_as_string(self):
-        result = parse_file_content("42", "json")
-        assert result == "42"
-
-    def test_scalar_boolean_stays_as_string(self):
-        result = parse_file_content("true", "json")
-        assert result == "true"
-
-    def test_null_stays_as_string(self):
-        result = parse_file_content("null", "json")
-        assert result == "null"
-
-    def test_invalid_json_fallback(self):
-        content = "not json at all"
-        result = parse_file_content(content, "json")
-        assert result == content
-
-    def test_empty_string_fallback(self):
-        result = parse_file_content("", "json")
-        assert result == ""
-
-    def test_bytes_input_decoded(self):
-        result = parse_file_content(b"[1, 2, 3]", "json")
-        assert result == [1, 2, 3]
-
-
-# ---------------------------------------------------------------------------
-# parse_file_content — JSONL
-# ---------------------------------------------------------------------------
-
-
-class TestParseJsonl:
-    def test_tabular_uniform_dicts_to_table_format(self):
-        """JSONL with uniform dict keys → table format (header + rows),
-        consistent with CSV/TSV/Parquet/Excel output."""
-        content = '{"name":"apple","color":"red"}\n{"name":"banana","color":"yellow"}\n{"name":"cherry","color":"red"}'
-        result = parse_file_content(content, "jsonl")
-        assert result == [
-            ["name", "color"],
-            ["apple", "red"],
-            ["banana", "yellow"],
-            ["cherry", "red"],
-        ]
-
-    def test_tabular_single_key_dicts(self):
-        """JSONL with single-key uniform dicts → table format."""
-        content = '{"a": 1}\n{"a": 2}\n{"a": 3}'
-        result = parse_file_content(content, "jsonl")
-        assert result == [["a"], [1], [2], [3]]
-
-    def test_tabular_blank_lines_skipped(self):
-        content = '{"a": 1}\n\n{"a": 2}\n'
-        result = parse_file_content(content, "jsonl")
-        assert result == [["a"], [1], [2]]
-
-    def test_heterogeneous_dicts_stay_as_list(self):
-        """JSONL with different keys across objects → list of dicts (no table)."""
-        content = '{"name":"apple"}\n{"color":"red"}\n{"size":3}'
-        result = parse_file_content(content, "jsonl")
-        assert result == [{"name": "apple"}, {"color": "red"}, {"size": 3}]
-
-    def test_partially_overlapping_keys_stay_as_list(self):
-        """JSONL dicts with partially overlapping keys → list of dicts."""
-        content = '{"name":"apple","color":"red"}\n{"name":"banana","size":"medium"}'
-        result = parse_file_content(content, "jsonl")
-        assert result == [
-            {"name": "apple", "color": "red"},
-            {"name": "banana", "size": "medium"},
-        ]
-
-    def test_mixed_types_stay_as_list(self):
-        """JSONL with non-dict lines → list of parsed values (no table)."""
-        content = '1\n"hello"\n[1,2]\n'
-        result = parse_file_content(content, "jsonl")
-        assert result == [1, "hello", [1, 2]]
-
-    def test_mixed_dicts_and_non_dicts_stay_as_list(self):
-        """JSONL mixing dicts and non-dicts → list of parsed values."""
-        content = '{"a": 1}\n42\n{"b": 2}'
-        result = parse_file_content(content, "jsonl")
-        assert result == [{"a": 1}, 42, {"b": 2}]
-
-    def test_tabular_preserves_key_order(self):
-        """Table header should follow the key order of the first object."""
-        content = '{"z": 1, "a": 2}\n{"z": 3, "a": 4}'
-        result = parse_file_content(content, "jsonl")
-        assert result[0] == ["z", "a"]  # order from first object
-        assert result[1] == [1, 2]
-        assert result[2] == [3, 4]
-
-    def test_single_dict_stays_as_list(self):
-        """Single-line JSONL with one dict → [dict], NOT a table.
-        Tabular detection requires ≥2 dicts to avoid vacuously true all()."""
-        content = '{"a": 1, "b": 2}'
-        result = parse_file_content(content, "jsonl")
-        assert result == [{"a": 1, "b": 2}]
-
-    def test_tabular_with_none_values(self):
-        """Uniform keys but some null values → table with None cells."""
-        content = '{"name":"apple","color":"red"}\n{"name":"banana","color":null}'
-        result = parse_file_content(content, "jsonl")
-        assert result == [
-            ["name", "color"],
-            ["apple", "red"],
-            ["banana", None],
-        ]
-
-    def test_empty_file_fallback(self):
-        result = parse_file_content("", "jsonl")
-        assert result == ""
-
-    def test_all_blank_lines_fallback(self):
-        result = parse_file_content("\n\n\n", "jsonl")
-        assert result == "\n\n\n"
-
-    def test_invalid_line_fallback(self):
-        content = '{"a": 1}\nnot json\n'
-        result = parse_file_content(content, "jsonl")
-        assert result == content  # fallback
-
-
-# ---------------------------------------------------------------------------
-# parse_file_content — CSV
-# ---------------------------------------------------------------------------
-
-
-class TestParseCsv:
-    def test_basic(self):
-        content = "Name,Score\nAlice,90\nBob,85"
-        result = parse_file_content(content, "csv")
-        assert result == [["Name", "Score"], ["Alice", "90"], ["Bob", "85"]]
-
-    def test_quoted_fields(self):
-        content = 'Name,Bio\nAlice,"Loves, commas"\nBob,Simple'
-        result = parse_file_content(content, "csv")
-        assert result[1] == ["Alice", "Loves, commas"]
-
-    def test_single_column_fallback(self):
-        # Only 1 column — not tabular enough.
-        content = "Name\nAlice\nBob"
-        result = parse_file_content(content, "csv")
-        assert result == content
-
-    def test_empty_rows_skipped(self):
-        content = "A,B\n\n1,2\n\n3,4"
-        result = parse_file_content(content, "csv")
-        assert result == [["A", "B"], ["1", "2"], ["3", "4"]]
-
-    def test_empty_file_fallback(self):
-        result = parse_file_content("", "csv")
-        assert result == ""
-
-    def test_utf8_bom(self):
-        """CSV with a UTF-8 BOM should parse correctly (BOM stripped by decode)."""
-        bom = "\ufeff"
-        content = bom + "Name,Score\nAlice,90\nBob,85"
-        result = parse_file_content(content, "csv")
-        # The BOM may be part of the first header cell; ensure rows are still parsed.
-        assert len(result) == 3
-        assert result[1] == ["Alice", "90"]
-        assert result[2] == ["Bob", "85"]
-
-
-# ---------------------------------------------------------------------------
-# parse_file_content — TSV
-# ---------------------------------------------------------------------------
-
-
-class TestParseTsv:
-    def test_basic(self):
-        content = "Name\tScore\nAlice\t90\nBob\t85"
-        result = parse_file_content(content, "tsv")
-        assert result == [["Name", "Score"], ["Alice", "90"], ["Bob", "85"]]
-
-    def test_single_column_fallback(self):
-        content = "Name\nAlice\nBob"
-        result = parse_file_content(content, "tsv")
-        assert result == content
-
-
-# ---------------------------------------------------------------------------
-# parse_file_content — YAML
-# ---------------------------------------------------------------------------
-
-
-class TestParseYaml:
-    def test_list(self):
-        content = "- apple\n- banana\n- cherry"
-        result = parse_file_content(content, "yaml")
-        assert result == ["apple", "banana", "cherry"]
-
-    def test_dict(self):
-        content = "name: Alice\nage: 30"
-        result = parse_file_content(content, "yaml")
-        assert result == {"name": "Alice", "age": 30}
-
-    def test_nested(self):
-        content = "users:\n  - name: Alice\n  - name: Bob"
-        result = parse_file_content(content, "yaml")
-        assert result == {"users": [{"name": "Alice"}, {"name": "Bob"}]}
-
-    def test_scalar_stays_as_string(self):
-        result = parse_file_content("hello world", "yaml")
-        assert result == "hello world"
-
-    def test_invalid_yaml_fallback(self):
-        content = ":\n  :\n    invalid: - -"
-        result = parse_file_content(content, "yaml")
-        # Malformed YAML should fall back to the original string, not raise.
-        assert result == content
-
-
-# ---------------------------------------------------------------------------
-# parse_file_content — TOML
-# ---------------------------------------------------------------------------
-
-
-class TestParseToml:
-    def test_basic(self):
-        content = '[server]\nhost = "localhost"\nport = 8080'
-        result = parse_file_content(content, "toml")
-        assert result == {"server": {"host": "localhost", "port": 8080}}
-
-    def test_flat(self):
-        content = 'name = "test"\ncount = 42'
-        result = parse_file_content(content, "toml")
-        assert result == {"name": "test", "count": 42}
-
-    def test_empty_string_returns_empty_dict(self):
-        result = parse_file_content("", "toml")
-        assert result == {}
-
-    def test_invalid_toml_fallback(self):
-        result = parse_file_content("not = [valid toml", "toml")
-        assert result == "not = [valid toml"
-
-
-# ---------------------------------------------------------------------------
-# parse_file_content — Parquet (binary)
-# ---------------------------------------------------------------------------
-
-
-try:
-    import pyarrow as _pa  # noqa: F401  # pyright: ignore[reportMissingImports]
-
-    _has_pyarrow = True
-except ImportError:
-    _has_pyarrow = False
-
-
-@pytest.mark.skipif(not _has_pyarrow, reason="pyarrow not installed")
-class TestParseParquet:
-    @pytest.fixture
-    def parquet_bytes(self) -> bytes:
-        import pandas as pd
-
-        df = pd.DataFrame({"Name": ["Alice", "Bob"], "Score": [90, 85]})
-        buf = io.BytesIO()
-        df.to_parquet(buf, index=False)
-        return buf.getvalue()
-
-    def test_basic(self, parquet_bytes: bytes):
-        result = parse_file_content(parquet_bytes, "parquet")
-        assert result == [["Name", "Score"], ["Alice", 90], ["Bob", 85]]
-
-    def test_string_input_fallback(self):
-        # Parquet is binary — string input can't be parsed.
-        result = parse_file_content("not parquet", "parquet")
-        assert result == "not parquet"
-
-    def test_invalid_bytes_fallback(self):
-        result = parse_file_content(b"not parquet bytes", "parquet")
-        assert result == b"not parquet bytes"
-
-    def test_empty_bytes_fallback(self):
-        """Empty binary input should return the empty bytes, not crash."""
-        result = parse_file_content(b"", "parquet")
-        assert result == b""
-
-    def test_nan_replaced_with_none(self):
-        """NaN values in Parquet must become None for JSON serializability."""
-        import math
-
-        import pandas as pd
-
-        df = pd.DataFrame({"A": [1.0, float("nan"), 3.0], "B": ["x", None, "z"]})
-        buf = io.BytesIO()
-        df.to_parquet(buf, index=False)
-        result = parse_file_content(buf.getvalue(), "parquet")
-        # Row with NaN in float col → None
-        assert result[2][0] is None  # float NaN → None
-        assert result[2][1] is None  # str None → None
-        # Ensure no NaN leaks
-        for row in result[1:]:
-            for cell in row:
-                if isinstance(cell, float):
-                    assert not math.isnan(cell), f"NaN leaked: {row}"
-
-
-# ---------------------------------------------------------------------------
-# parse_file_content — Excel (binary)
-# ---------------------------------------------------------------------------
-
-
-class TestParseExcel:
-    @pytest.fixture
-    def xlsx_bytes(self) -> bytes:
-        import pandas as pd
-
-        df = pd.DataFrame({"Name": ["Alice", "Bob"], "Score": [90, 85]})
-        buf = io.BytesIO()
-        df.to_excel(buf, index=False)  # type: ignore[arg-type]  # BytesIO is a valid target
-        return buf.getvalue()
-
-    def test_basic(self, xlsx_bytes: bytes):
-        result = parse_file_content(xlsx_bytes, "xlsx")
-        assert result == [["Name", "Score"], ["Alice", 90], ["Bob", 85]]
-
-    def test_string_input_fallback(self):
-        result = parse_file_content("not xlsx", "xlsx")
-        assert result == "not xlsx"
-
-    def test_invalid_bytes_fallback(self):
-        result = parse_file_content(b"not xlsx bytes", "xlsx")
-        assert result == b"not xlsx bytes"
-
-    def test_empty_bytes_fallback(self):
-        """Empty binary input should return the empty bytes, not crash."""
-        result = parse_file_content(b"", "xlsx")
-        assert result == b""
-
-    def test_nan_replaced_with_none(self):
-        """NaN values in float columns must become None for JSON serializability."""
-        import math
-
-        import pandas as pd
-
-        df = pd.DataFrame({"A": [1.0, float("nan"), 3.0], "B": ["x", "y", None]})
-        buf = io.BytesIO()
-        df.to_excel(buf, index=False)  # type: ignore[arg-type]
-        result = parse_file_content(buf.getvalue(), "xlsx")
-        # Row with NaN in float col → None, not float('nan')
-        assert result[2][0] is None  # float NaN → None
-        assert result[3][1] is None  # str None → None
-        # Ensure no NaN leaks
-        for row in result[1:]:  # skip header
-            for cell in row:
-                if isinstance(cell, float):
-                    assert not math.isnan(cell), f"NaN leaked: {row}"
-
-
-# ---------------------------------------------------------------------------
-# parse_file_content — unknown format / fallback
-# ---------------------------------------------------------------------------
-
-
-class TestFallback:
-    def test_unknown_format_returns_content(self):
-        result = parse_file_content("hello world", "xml")
-        assert result == "hello world"
-
-    def test_none_format_returns_content(self):
-        # Shouldn't normally be called with unrecognised format, but must not crash.
-        result = parse_file_content("hello", "unknown_format")
-        assert result == "hello"
-
-
-# ---------------------------------------------------------------------------
-# BINARY_FORMATS
-# ---------------------------------------------------------------------------
-
-
-class TestBinaryFormats:
-    def test_parquet_is_binary(self):
-        assert "parquet" in BINARY_FORMATS
-
-    def test_xlsx_is_binary(self):
-        assert "xlsx" in BINARY_FORMATS
-
-    def test_text_formats_not_binary(self):
-        for fmt in ("json", "jsonl", "csv", "tsv", "yaml", "toml"):
-            assert fmt not in BINARY_FORMATS
-
-
-# ---------------------------------------------------------------------------
-# MIME mapping
-# ---------------------------------------------------------------------------
-
-
-class TestMimeMapping:
-    def test_application_yaml(self):
-        assert infer_format_from_uri("workspace://abc123#application/yaml") == "yaml"
-
-
-# ---------------------------------------------------------------------------
-# CSV sniffer fallback
-# ---------------------------------------------------------------------------
-
-
-class TestCsvSnifferFallback:
-    def test_tab_delimited_with_csv_format(self):
-        """Tab-delimited content parsed as csv should use sniffer fallback."""
-        content = "Name\tScore\nAlice\t90\nBob\t85"
-        result = parse_file_content(content, "csv")
-        assert result == [["Name", "Score"], ["Alice", "90"], ["Bob", "85"]]
-
-    def test_sniffer_failure_returns_content(self):
-        """When sniffer fails, single-column falls back to raw content."""
-        content = "Name\nAlice\nBob"
-        result = parse_file_content(content, "csv")
-        assert result == content
-
-
-# ---------------------------------------------------------------------------
-# OpenpyxlInvalidFile fallback
-# ---------------------------------------------------------------------------
-
-
-class TestOpenpyxlFallback:
-    def test_invalid_xlsx_non_strict(self):
-        """Invalid xlsx bytes should fall back gracefully in non-strict mode."""
-        result = parse_file_content(b"not xlsx bytes", "xlsx")
-        assert result == b"not xlsx bytes"
-
-
-# ---------------------------------------------------------------------------
-# Header-only CSV
-# ---------------------------------------------------------------------------
-
-
-class TestHeaderOnlyCsv:
-    def test_header_only_csv_returns_header_row(self):
-        """CSV with only a header row (no data rows) should return [[header]]."""
-        content = "Name,Score"
-        result = parse_file_content(content, "csv")
-        assert result == [["Name", "Score"]]
-
-    def test_header_only_csv_with_trailing_newline(self):
-        content = "Name,Score\n"
-        result = parse_file_content(content, "csv")
-        assert result == [["Name", "Score"]]
-
-
-# ---------------------------------------------------------------------------
-# Binary format + line range (line range ignored for binary formats)
-# ---------------------------------------------------------------------------
-
-
-@pytest.mark.skipif(not _has_pyarrow, reason="pyarrow not installed")
-class TestBinaryFormatLineRange:
-    def test_parquet_ignores_line_range(self):
-        """Binary formats should parse the full file regardless of line range.
-
-        Line ranges are meaningless for binary formats (parquet/xlsx) — the
-        caller (file_ref._expand_bare_ref) passes raw bytes and the parser
-        should return the complete structured data.
-        """
-        import pandas as pd
-
-        df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})
-        buf = io.BytesIO()
-        df.to_parquet(buf, index=False)
-        # parse_file_content itself doesn't take a line range — this tests
-        # that the full content is parsed even though the bytes could have
-        # been truncated upstream (it's not, by design).
-        result = parse_file_content(buf.getvalue(), "parquet")
-        assert result == [["A", "B"], [1, 4], [2, 5], [3, 6]]
-
-
-# ---------------------------------------------------------------------------
-# Legacy .xls UX
-# ---------------------------------------------------------------------------
-
-
-class TestXlsFallback:
-    def test_xls_returns_helpful_error_string(self):
-        """Uploading a .xls file should produce a helpful error, not garbled binary."""
-        result = parse_file_content(b"\xd0\xcf\x11\xe0garbled", "xls")
-        assert isinstance(result, str)
-        assert ".xlsx" in result
-        assert "not supported" in result.lower()
-
-    def test_xls_with_string_content(self):
-        result = parse_file_content("some text", "xls")
-        assert isinstance(result, str)
-        assert ".xlsx" in result

autogpt_platform/backend/backend/util/file_test.py

@@ -8,12 +8,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
 import pytest
 
 from backend.data.execution import ExecutionContext
-from backend.util.file import (
-    is_media_file_ref,
-    parse_data_uri,
-    resolve_media_content,
-    store_media_file,
-)
+from backend.util.file import store_media_file
 from backend.util.type import MediaFileType
 
 
@@ -349,162 +344,3 @@ class TestFileCloudIntegration:
                     execution_context=make_test_context(graph_exec_id=graph_exec_id),
                     return_format="for_local_processing",
                 )
-
-
-# ---------------------------------------------------------------------------
-# is_media_file_ref
-# ---------------------------------------------------------------------------
-
-
-class TestIsMediaFileRef:
-    def test_data_uri(self):
-        assert is_media_file_ref("data:image/png;base64,iVBORw0KGg==") is True
-
-    def test_workspace_uri(self):
-        assert is_media_file_ref("workspace://abc123") is True
-
-    def test_workspace_uri_with_mime(self):
-        assert is_media_file_ref("workspace://abc123#image/png") is True
-
-    def test_http_url(self):
-        assert is_media_file_ref("http://example.com/image.png") is True
-
-    def test_https_url(self):
-        assert is_media_file_ref("https://example.com/image.png") is True
-
-    def test_plain_text(self):
-        assert is_media_file_ref("print('hello')") is False
-
-    def test_local_path(self):
-        assert is_media_file_ref("/tmp/file.txt") is False
-
-    def test_empty_string(self):
-        assert is_media_file_ref("") is False
-
-    def test_filename(self):
-        assert is_media_file_ref("image.png") is False
-
-
-# ---------------------------------------------------------------------------
-# parse_data_uri
-# ---------------------------------------------------------------------------
-
-
-class TestParseDataUri:
-    def test_valid_png(self):
-        result = parse_data_uri("data:image/png;base64,iVBORw0KGg==")
-        assert result is not None
-        mime, payload = result
-        assert mime == "image/png"
-        assert payload == "iVBORw0KGg=="
-
-    def test_valid_text(self):
-        result = parse_data_uri("data:text/plain;base64,SGVsbG8=")
-        assert result is not None
-        assert result[0] == "text/plain"
-        assert result[1] == "SGVsbG8="
-
-    def test_mime_case_normalized(self):
-        result = parse_data_uri("data:IMAGE/PNG;base64,abc")
-        assert result is not None
-        assert result[0] == "image/png"
-
-    def test_not_data_uri(self):
-        assert parse_data_uri("workspace://abc123") is None
-
-    def test_plain_text(self):
-        assert parse_data_uri("hello world") is None
-
-    def test_missing_base64(self):
-        assert parse_data_uri("data:image/png;utf-8,abc") is None
-
-    def test_empty_payload(self):
-        result = parse_data_uri("data:image/png;base64,")
-        assert result is not None
-        assert result[1] == ""
-
-
-# ---------------------------------------------------------------------------
-# resolve_media_content
-# ---------------------------------------------------------------------------
-
-
-class TestResolveMediaContent:
-    @pytest.mark.asyncio
-    async def test_plain_text_passthrough(self):
-        """Plain text content (not a media ref) passes through unchanged."""
-        ctx = make_test_context()
-        result = await resolve_media_content(
-            MediaFileType("print('hello')"),
-            ctx,
-            return_format="for_external_api",
-        )
-        assert result == "print('hello')"
-
-    @pytest.mark.asyncio
-    async def test_empty_string_passthrough(self):
-        """Empty string passes through unchanged."""
-        ctx = make_test_context()
-        result = await resolve_media_content(
-            MediaFileType(""),
-            ctx,
-            return_format="for_external_api",
-        )
-        assert result == ""
-
-    @pytest.mark.asyncio
-    async def test_media_ref_delegates_to_store(self):
-        """Media references are resolved via store_media_file."""
-        ctx = make_test_context()
-        with patch(
-            "backend.util.file.store_media_file",
-            new=AsyncMock(return_value=MediaFileType("data:image/png;base64,abc")),
-        ) as mock_store:
-            result = await resolve_media_content(
-                MediaFileType("workspace://img123"),
-                ctx,
-                return_format="for_external_api",
-            )
-        assert result == "data:image/png;base64,abc"
-        mock_store.assert_called_once_with(
-            MediaFileType("workspace://img123"),
-            ctx,
-            return_format="for_external_api",
-        )
-
-    @pytest.mark.asyncio
-    async def test_data_uri_delegates_to_store(self):
-        """Data URIs are also resolved via store_media_file."""
-        ctx = make_test_context()
-        data_uri = "data:image/png;base64,iVBORw0KGg=="
-        with patch(
-            "backend.util.file.store_media_file",
-            new=AsyncMock(return_value=MediaFileType(data_uri)),
-        ) as mock_store:
-            result = await resolve_media_content(
-                MediaFileType(data_uri),
-                ctx,
-                return_format="for_external_api",
-            )
-        assert result == data_uri
-        mock_store.assert_called_once()
-
-    @pytest.mark.asyncio
-    async def test_https_url_delegates_to_store(self):
-        """HTTPS URLs are resolved via store_media_file."""
-        ctx = make_test_context()
-        with patch(
-            "backend.util.file.store_media_file",
-            new=AsyncMock(return_value=MediaFileType("data:image/png;base64,abc")),
-        ) as mock_store:
-            result = await resolve_media_content(
-                MediaFileType("https://example.com/image.png"),
-                ctx,
-                return_format="for_local_processing",
-            )
-        assert result == "data:image/png;base64,abc"
-        mock_store.assert_called_once_with(
-            MediaFileType("https://example.com/image.png"),
-            ctx,
-            return_format="for_local_processing",
-        )

autogpt_platform/backend/poetry.lock

@@ -1360,18 +1360,6 @@ files = [
 dnspython = ">=2.0.0"
 idna = ">=2.0.0"
 
-[[package]]
-name = "et-xmlfile"
-version = "2.0.0"
-description = "An implementation of lxml.xmlfile for the standard library"
-optional = false
-python-versions = ">=3.8"
-groups = ["main"]
-files = [
-    {file = "et_xmlfile-2.0.0-py3-none-any.whl", hash = "sha256:7a91720bc756843502c3b7504c77b8fe44217c85c537d85037f0f536151b2caa"},
-    {file = "et_xmlfile-2.0.0.tar.gz", hash = "sha256:dab3f4764309081ce75662649be815c4c9081e88f0837825f90fd28317d4da54"},
-]
-
 [[package]]
 name = "exa-py"
 version = "1.16.1"
@@ -4240,21 +4228,6 @@ datalib = ["numpy (>=1)", "pandas (>=1.2.3)", "pandas-stubs (>=1.1.0.11)"]
 realtime = ["websockets (>=13,<16)"]
 voice-helpers = ["numpy (>=2.0.2)", "sounddevice (>=0.5.1)"]
 
-[[package]]
-name = "openpyxl"
-version = "3.1.5"
-description = "A Python library to read/write Excel 2010 xlsx/xlsm files"
-optional = false
-python-versions = ">=3.8"
-groups = ["main"]
-files = [
-    {file = "openpyxl-3.1.5-py2.py3-none-any.whl", hash = "sha256:5282c12b107bffeef825f4617dc029afaf41d0ea60823bbb665ef3079dc79de2"},
-    {file = "openpyxl-3.1.5.tar.gz", hash = "sha256:cf0e3cf56142039133628b5acffe8ef0c12bc902d2aadd3e0fe5878dc08d1050"},
-]
-
-[package.dependencies]
-et-xmlfile = "*"
-
 [[package]]
 name = "opentelemetry-api"
 version = "1.39.1"
@@ -5457,66 +5430,6 @@ files = [
     {file = "psycopg2_binary-2.9.11-cp39-cp39-win_amd64.whl", hash = "sha256:875039274f8a2361e5207857899706da840768e2a775bf8c65e82f60b197df02"},
 ]
 
-[[package]]
-name = "pyarrow"
-version = "23.0.1"
-description = "Python library for Apache Arrow"
-optional = false
-python-versions = ">=3.10"
-groups = ["main"]
-files = [
-    {file = "pyarrow-23.0.1-cp310-cp310-macosx_12_0_arm64.whl", hash = "sha256:3fab8f82571844eb3c460f90a75583801d14ca0cc32b1acc8c361650e006fd56"},
-    {file = "pyarrow-23.0.1-cp310-cp310-macosx_12_0_x86_64.whl", hash = "sha256:3f91c038b95f71ddfc865f11d5876c42f343b4495535bd262c7b321b0b94507c"},
-    {file = "pyarrow-23.0.1-cp310-cp310-manylinux_2_28_aarch64.whl", hash = "sha256:d0744403adabef53c985a7f8a082b502a368510c40d184df349a0a8754533258"},
-    {file = "pyarrow-23.0.1-cp310-cp310-manylinux_2_28_x86_64.whl", hash = "sha256:c33b5bf406284fd0bba436ed6f6c3ebe8e311722b441d89397c54f871c6863a2"},
-    {file = "pyarrow-23.0.1-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:ddf743e82f69dcd6dbbcb63628895d7161e04e56794ef80550ac6f3315eeb1d5"},
-    {file = "pyarrow-23.0.1-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:e052a211c5ac9848ae15d5ec875ed0943c0221e2fcfe69eee80b604b4e703222"},
-    {file = "pyarrow-23.0.1-cp310-cp310-win_amd64.whl", hash = "sha256:5abde149bb3ce524782d838eb67ac095cd3fd6090eba051130589793f1a7f76d"},
-    {file = "pyarrow-23.0.1-cp311-cp311-macosx_12_0_arm64.whl", hash = "sha256:6f0147ee9e0386f519c952cc670eb4a8b05caa594eeffe01af0e25f699e4e9bb"},
-    {file = "pyarrow-23.0.1-cp311-cp311-macosx_12_0_x86_64.whl", hash = "sha256:0ae6e17c828455b6265d590100c295193f93cc5675eb0af59e49dbd00d2de350"},
-    {file = "pyarrow-23.0.1-cp311-cp311-manylinux_2_28_aarch64.whl", hash = "sha256:fed7020203e9ef273360b9e45be52a2a47d3103caf156a30ace5247ffb51bdbd"},
-    {file = "pyarrow-23.0.1-cp311-cp311-manylinux_2_28_x86_64.whl", hash = "sha256:26d50dee49d741ac0e82185033488d28d35be4d763ae6f321f97d1140eb7a0e9"},
-    {file = "pyarrow-23.0.1-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:3c30143b17161310f151f4a2bcfe41b5ff744238c1039338779424e38579d701"},
-    {file = "pyarrow-23.0.1-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:db2190fa79c80a23fdd29fef4b8992893f024ae7c17d2f5f4db7171fa30c2c78"},
-    {file = "pyarrow-23.0.1-cp311-cp311-win_amd64.whl", hash = "sha256:f00f993a8179e0e1c9713bcc0baf6d6c01326a406a9c23495ec1ba9c9ebf2919"},
-    {file = "pyarrow-23.0.1-cp312-cp312-macosx_12_0_arm64.whl", hash = "sha256:f4b0dbfa124c0bb161f8b5ebb40f1a680b70279aa0c9901d44a2b5a20806039f"},
-    {file = "pyarrow-23.0.1-cp312-cp312-macosx_12_0_x86_64.whl", hash = "sha256:7707d2b6673f7de054e2e83d59f9e805939038eebe1763fe811ee8fa5c0cd1a7"},
-    {file = "pyarrow-23.0.1-cp312-cp312-manylinux_2_28_aarch64.whl", hash = "sha256:86ff03fb9f1a320266e0de855dee4b17da6794c595d207f89bba40d16b5c78b9"},
-    {file = "pyarrow-23.0.1-cp312-cp312-manylinux_2_28_x86_64.whl", hash = "sha256:813d99f31275919c383aab17f0f455a04f5a429c261cc411b1e9a8f5e4aaaa05"},
-    {file = "pyarrow-23.0.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:bf5842f960cddd2ef757d486041d57c96483efc295a8c4a0e20e704cbbf39c67"},
-    {file = "pyarrow-23.0.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:564baf97c858ecc03ec01a41062e8f4698abc3e6e2acd79c01c2e97880a19730"},
-    {file = "pyarrow-23.0.1-cp312-cp312-win_amd64.whl", hash = "sha256:07deae7783782ac7250989a7b2ecde9b3c343a643f82e8a4df03d93b633006f0"},
-    {file = "pyarrow-23.0.1-cp313-cp313-macosx_12_0_arm64.whl", hash = "sha256:6b8fda694640b00e8af3c824f99f789e836720aa8c9379fb435d4c4953a756b8"},
-    {file = "pyarrow-23.0.1-cp313-cp313-macosx_12_0_x86_64.whl", hash = "sha256:8ff51b1addc469b9444b7c6f3548e19dc931b172ab234e995a60aea9f6e6025f"},
-    {file = "pyarrow-23.0.1-cp313-cp313-manylinux_2_28_aarch64.whl", hash = "sha256:71c5be5cbf1e1cb6169d2a0980850bccb558ddc9b747b6206435313c47c37677"},
-    {file = "pyarrow-23.0.1-cp313-cp313-manylinux_2_28_x86_64.whl", hash = "sha256:9b6f4f17b43bc39d56fec96e53fe89d94bac3eb134137964371b45352d40d0c2"},
-    {file = "pyarrow-23.0.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:9fc13fc6c403d1337acab46a2c4346ca6c9dec5780c3c697cf8abfd5e19b6b37"},
-    {file = "pyarrow-23.0.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:5c16ed4f53247fa3ffb12a14d236de4213a4415d127fe9cebed33d51671113e2"},
-    {file = "pyarrow-23.0.1-cp313-cp313-win_amd64.whl", hash = "sha256:cecfb12ef629cf6be0b1887f9f86463b0dd3dc3195ae6224e74006be4736035a"},
-    {file = "pyarrow-23.0.1-cp313-cp313t-macosx_12_0_arm64.whl", hash = "sha256:29f7f7419a0e30264ea261fdc0e5fe63ce5a6095003db2945d7cd78df391a7e1"},
-    {file = "pyarrow-23.0.1-cp313-cp313t-macosx_12_0_x86_64.whl", hash = "sha256:33d648dc25b51fd8055c19e4261e813dfc4d2427f068bcecc8b53d01b81b0500"},
-    {file = "pyarrow-23.0.1-cp313-cp313t-manylinux_2_28_aarch64.whl", hash = "sha256:cd395abf8f91c673dd3589cadc8cc1ee4e8674fa61b2e923c8dd215d9c7d1f41"},
-    {file = "pyarrow-23.0.1-cp313-cp313t-manylinux_2_28_x86_64.whl", hash = "sha256:00be9576d970c31defb5c32eb72ef585bf600ef6d0a82d5eccaae96639cf9d07"},
-    {file = "pyarrow-23.0.1-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:c2139549494445609f35a5cda4eb94e2c9e4d704ce60a095b342f82460c73a83"},
-    {file = "pyarrow-23.0.1-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:7044b442f184d84e2351e5084600f0d7343d6117aabcbc1ac78eb1ae11eb4125"},
-    {file = "pyarrow-23.0.1-cp313-cp313t-win_amd64.whl", hash = "sha256:a35581e856a2fafa12f3f54fce4331862b1cfb0bef5758347a858a4aa9d6bae8"},
-    {file = "pyarrow-23.0.1-cp314-cp314-macosx_12_0_arm64.whl", hash = "sha256:5df1161da23636a70838099d4aaa65142777185cc0cdba4037a18cee7d8db9ca"},
-    {file = "pyarrow-23.0.1-cp314-cp314-macosx_12_0_x86_64.whl", hash = "sha256:fa8e51cb04b9f8c9c5ace6bab63af9a1f88d35c0d6cbf53e8c17c098552285e1"},
-    {file = "pyarrow-23.0.1-cp314-cp314-manylinux_2_28_aarch64.whl", hash = "sha256:0b95a3994f015be13c63148fef8832e8a23938128c185ee951c98908a696e0eb"},
-    {file = "pyarrow-23.0.1-cp314-cp314-manylinux_2_28_x86_64.whl", hash = "sha256:4982d71350b1a6e5cfe1af742c53dfb759b11ce14141870d05d9e540d13bc5d1"},
-    {file = "pyarrow-23.0.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:c250248f1fe266db627921c89b47b7c06fee0489ad95b04d50353537d74d6886"},
-    {file = "pyarrow-23.0.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:5f4763b83c11c16e5f4c15601ba6dfa849e20723b46aa2617cb4bffe8768479f"},
-    {file = "pyarrow-23.0.1-cp314-cp314-win_amd64.whl", hash = "sha256:3a4c85ef66c134161987c17b147d6bffdca4566f9a4c1d81a0a01cdf08414ea5"},
-    {file = "pyarrow-23.0.1-cp314-cp314t-macosx_12_0_arm64.whl", hash = "sha256:17cd28e906c18af486a499422740298c52d7c6795344ea5002a7720b4eadf16d"},
-    {file = "pyarrow-23.0.1-cp314-cp314t-macosx_12_0_x86_64.whl", hash = "sha256:76e823d0e86b4fb5e1cf4a58d293036e678b5a4b03539be933d3b31f9406859f"},
-    {file = "pyarrow-23.0.1-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:a62e1899e3078bf65943078b3ad2a6ddcacf2373bc06379aac61b1e548a75814"},
-    {file = "pyarrow-23.0.1-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:df088e8f640c9fae3b1f495b3c64755c4e719091caf250f3a74d095ddf3c836d"},
-    {file = "pyarrow-23.0.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:46718a220d64677c93bc243af1d44b55998255427588e400677d7192671845c7"},
-    {file = "pyarrow-23.0.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:a09f3876e87f48bc2f13583ab551f0379e5dfb83210391e68ace404181a20690"},
-    {file = "pyarrow-23.0.1-cp314-cp314t-win_amd64.whl", hash = "sha256:527e8d899f14bd15b740cd5a54ad56b7f98044955373a17179d5956ddb93d9ce"},
-    {file = "pyarrow-23.0.1.tar.gz", hash = "sha256:b8c5873e33440b2bc2f4a79d2b47017a89c5a24116c055625e6f2ee50523f019"},
-]
-
 [[package]]
 name = "pyasn1"
 version = "0.6.2"
@@ -8969,4 +8882,4 @@ cffi = ["cffi (>=1.17,<2.0) ; platform_python_implementation != \"PyPy\" and pyt
 [metadata]
 lock-version = "2.1"
 python-versions = ">=3.10,<3.14"
-content-hash = "86dab25684dd46e635a33bd33281a926e5626a874ecc048c34389fecf34a87d8"
+content-hash = "4e4365721cd3b68c58c237353b74adae1c64233fd4446904c335f23eb866fdca"

autogpt_platform/backend/pyproject.toml

@@ -92,8 +92,6 @@ gravitas-md2gdocs = "^0.1.0"
 posthog = "^7.6.0"
 fpdf2 = "^2.8.6"
 langsmith = "^0.7.7"
-openpyxl = "^3.1.5"
-pyarrow = "^23.0.0"
 
 [tool.poetry.group.dev.dependencies]
 aiohappyeyeballs = "^2.6.1"

autogpt_platform/frontend/src/tests/agent-activity.spec.ts

@@ -18,11 +18,8 @@ test.beforeEach(async ({ page }) => {
   await page.goto("/build");
   await buildPage.closeTutorial();
 
-  const [dictionaryBlock] = await buildPage.getFilteredBlocksFromAPI(
-    (block) => block.name === "AddToDictionaryBlock",
-  );
-
-  await buildPage.addBlock(dictionaryBlock);
+  await buildPage.addBlockByClick("Add to Dictionary");
+  await buildPage.waitForNodeOnCanvas(1);
 
   await buildPage.saveAgent("Test Agent", "Test Description");
   await test

autogpt_platform/frontend/src/tests/build.spec.ts

@@ -1,363 +1,134 @@
-// TODO: These tests were written for the old (legacy) builder.
-// They need to be updated to work with the new flow editor.
-
-// Note: all the comments with //(number)! are for the docs
-//ignore them when reading the code, but if you change something,
-//make sure to update the docs! Your autoformmater will break this page,
-// so don't run it on this file.
-// --8<-- [start:BuildPageExample]
-
-import test from "@playwright/test";
+import test, { expect } from "@playwright/test";
 import { BuildPage } from "./pages/build.page";
 import { LoginPage } from "./pages/login.page";
 import { hasUrl } from "./utils/assertion";
 import { getTestUser } from "./utils/auth";
 
-// Reason Ignore: admonishment is in the wrong place visually with correct prettier rules
-// prettier-ignore
-test.describe.skip("Build", () => { //(1)!
-  let buildPage: BuildPage; //(2)!
+test.describe("Builder", () => {
+  let buildPage: BuildPage;
 
-  // Reason Ignore: admonishment is in the wrong place visually with correct prettier rules
-  // prettier-ignore
-  test.beforeEach(async ({ page }) => { //(3)! ts-ignore
-    test.setTimeout(25000);
+  test.beforeEach(async ({ page }) => {
+    test.setTimeout(60000);
     const loginPage = new LoginPage(page);
     const testUser = await getTestUser();
 
     buildPage = new BuildPage(page);
 
-    // Start each test with login using worker auth
-    await page.goto("/login"); //(4)!
+    await page.goto("/login");
     await loginPage.login(testUser.email, testUser.password);
-    await hasUrl(page, "/marketplace"); //(5)!
-    await buildPage.navbar.clickBuildLink();
-    await hasUrl(page, "/build");
+    await hasUrl(page, "/marketplace");
+
+    await page.goto("/build");
+    await page.waitForLoadState("domcontentloaded");
     await buildPage.closeTutorial();
   });
 
-  // Helper function to add blocks starting with a specific letter, split into parts for parallelization
-  async function addBlocksStartingWithSplit(letter: string, part: number, totalParts: number): Promise<void> {
-    const blockIdsToSkip = await buildPage.getBlocksToSkip();
-    const blockTypesToSkip = ["Input", "Output", "Agent", "AI"];
-    const targetLetter = letter.toLowerCase();
-    
-    const allBlocks = await buildPage.getFilteredBlocksFromAPI(block => 
-      block.name[0].toLowerCase() === targetLetter &&
-      !blockIdsToSkip.includes(block.id) && 
-      !blockTypesToSkip.includes(block.type)
-    );
+  // --- Core tests ---
 
-    const blocksToAdd = allBlocks.filter((_, index) => 
-      index % totalParts === (part - 1)
-    );
-
-    console.log(`Adding ${blocksToAdd.length} blocks starting with "${letter}" (part ${part}/${totalParts})`);
-    
-    for (const block of blocksToAdd) {
-      await buildPage.addBlock(block);
-    }
-  }
-
-  // Reason Ignore: admonishment is in the wrong place visually with correct prettier rules
-  // prettier-ignore
-  test("user can add a block", async ({ page: _page }) => { //(6)!
-    await buildPage.openBlocksPanel(); //(10)!
-    const blocks = await buildPage.getFilteredBlocksFromAPI(block => block.name[0].toLowerCase() === "a");
-    const block = blocks.at(-1);
-    if (!block) throw new Error("No block found");
-
-    await buildPage.addBlock(block); //(11)!
-    await buildPage.closeBlocksPanel(); //(12)!
-    await buildPage.hasBlock(block); //(13)!
-  });
-  // --8<-- [end:BuildPageExample]
-
-  test("user can add blocks starting with a (part 1)", async () => {
-    await addBlocksStartingWithSplit("a", 1, 2);
+  test("build page loads successfully", async () => {
+    await expect(buildPage.isLoaded()).resolves.toBeTruthy();
+    await expect(
+      buildPage.getPlaywrightPage().getByTestId("blocks-control-blocks-button"),
+    ).toBeVisible();
+    await expect(
+      buildPage.getPlaywrightPage().getByTestId("save-control-save-button"),
+    ).toBeVisible();
   });
 
-  test("user can add blocks starting with a (part 2)", async () => {
-    await addBlocksStartingWithSplit("a", 2, 2);
+  test("user can add a block via block menu", async () => {
+    const initialCount = await buildPage.getNodeCount();
+    await buildPage.addBlockByClick("Store Value");
+    await buildPage.waitForNodeOnCanvas(initialCount + 1);
+    expect(await buildPage.getNodeCount()).toBe(initialCount + 1);
   });
 
-  test("user can add blocks starting with b", async () => {
-    await addBlocksStartingWithSplit("b", 1, 1);
+  test("user can add multiple blocks", async () => {
+    await buildPage.addBlockByClick("Store Value");
+    await buildPage.waitForNodeOnCanvas(1);
+
+    await buildPage.addBlockByClick("Store Value");
+    await buildPage.waitForNodeOnCanvas(2);
+
+    expect(await buildPage.getNodeCount()).toBe(2);
   });
 
-  test("user can add blocks starting with c", async () => {
-    await addBlocksStartingWithSplit("c", 1, 1);
+  test("user can remove a block", async () => {
+    await buildPage.addBlockByClick("Store Value");
+    await buildPage.waitForNodeOnCanvas(1);
+
+    // Deselect, then re-select the node and delete
+    await buildPage.clickCanvas();
+    await buildPage.selectNode(0);
+    await buildPage.deleteSelectedNodes();
+
+    await expect(buildPage.getNodeLocator()).toHaveCount(0, { timeout: 5000 });
   });
 
-  test("user can add blocks starting with d", async () => {
-    await addBlocksStartingWithSplit("d", 1, 1);
+  test("user can save an agent", async ({ page }) => {
+    await buildPage.addBlockByClick("Store Value");
+    await buildPage.waitForNodeOnCanvas(1);
+
+    await buildPage.saveAgent("E2E Test Agent", "Created by e2e test");
+    await buildPage.waitForSaveComplete();
+
+    expect(page.url()).toContain("flowID=");
   });
 
-  test("user can add blocks starting with e", async () => {
-    test.setTimeout(60000); // Increase timeout for many Exa blocks
-    await addBlocksStartingWithSplit("e", 1, 2);
-  });
+  test("user can save and run button becomes enabled", async () => {
+    await buildPage.addBlockByClick("Store Value");
+    await buildPage.waitForNodeOnCanvas(1);
 
-  test("user can add blocks starting with e pt 2", async () => {
-    test.setTimeout(60000); // Increase timeout for many Exa blocks
-    await addBlocksStartingWithSplit("e", 2, 2);
-  });
-
-  test("user can add blocks starting with f", async () => {
-    await addBlocksStartingWithSplit("f", 1, 1);
-  });
-
-  test("user can add blocks starting with g (part 1)", async () => {
-    await addBlocksStartingWithSplit("g", 1, 3);
-  });
-
-  test("user can add blocks starting with g (part 2)", async () => {
-    await addBlocksStartingWithSplit("g", 2, 3);
-  });
-
-  test("user can add blocks starting with g (part 3)", async () => {
-    await addBlocksStartingWithSplit("g", 3, 3);
-  });
-
-  test("user can add blocks starting with h", async () => {
-    await addBlocksStartingWithSplit("h", 1, 1);
-  });
-
-  test("user can add blocks starting with i", async () => {
-    await addBlocksStartingWithSplit("i", 1, 1);
-  });
-
-  test("user can add blocks starting with j", async () => {
-    await addBlocksStartingWithSplit("j", 1, 1);
-  });
-
-  test("user can add blocks starting with k", async () => {
-    await addBlocksStartingWithSplit("k", 1, 1);
-  });
-
-  test("user can add blocks starting with l", async () => {
-    await addBlocksStartingWithSplit("l", 1, 1);
-  });
-
-  test("user can add blocks starting with m", async () => {
-    await addBlocksStartingWithSplit("m", 1, 1);
-  });
-
-  test("user can add blocks starting with n", async () => {
-    await addBlocksStartingWithSplit("n", 1, 1);
-  });
-
-  test("user can add blocks starting with o", async () => {
-    await addBlocksStartingWithSplit("o", 1, 1);
-  });
-
-  test("user can add blocks starting with p", async () => {
-    await addBlocksStartingWithSplit("p", 1, 1);
-  });
-
-  test("user can add blocks starting with q", async () => {
-    await addBlocksStartingWithSplit("q", 1, 1);
-  });
-
-  test("user can add blocks starting with r", async () => {
-    await addBlocksStartingWithSplit("r", 1, 1);
-  });
-
-  test("user can add blocks starting with s (part 1)", async () => {
-    await addBlocksStartingWithSplit("s", 1, 3);
-  });
-
-  test("user can add blocks starting with s (part 2)", async () => {
-    await addBlocksStartingWithSplit("s", 2, 3);
-  });
-
-  test("user can add blocks starting with s (part 3)", async () => {
-    await addBlocksStartingWithSplit("s", 3, 3);
-  });
-
-  test("user can add blocks starting with t", async () => {
-    await addBlocksStartingWithSplit("t", 1, 1);
-  });
-
-  test("user can add blocks starting with u", async () => {
-    await addBlocksStartingWithSplit("u", 1, 1);
-  });
-
-  test("user can add blocks starting with v", async () => {
-    await addBlocksStartingWithSplit("v", 1, 1);
-  });
-
-  test("user can add blocks starting with w", async () => {
-    await addBlocksStartingWithSplit("w", 1, 1);
-  });
-
-  test("user can add blocks starting with x", async () => {
-    await addBlocksStartingWithSplit("x", 1, 1);
-  });
-
-  test("user can add blocks starting with y", async () => {
-    await addBlocksStartingWithSplit("y", 1, 1);
-  });
-
-  test("user can add blocks starting with z", async () => {
-    await addBlocksStartingWithSplit("z", 1, 1);
-  });
-
-  test("build navigation is accessible from navbar", async ({ page }) => {
-    // Navigate somewhere else first
-    await page.goto("/marketplace"); //(4)!
-
-    // Check that navigation to the Builder is available on the page
-    await buildPage.navbar.clickBuildLink();
-
-    await hasUrl(page, "/build");
-    await test.expect(buildPage.isLoaded()).resolves.toBeTruthy();
-  });
-
-  test("user can add two blocks and connect them", async ({ page }) => {
-    await buildPage.openBlocksPanel();
-
-    // Define the blocks to add
-    const block1 = {
-      id: "1ff065e9-88e8-4358-9d82-8dc91f622ba9",
-      name: "Store Value 1",
-      description: "Store Value Block 1",
-      type: "Standard",
-    };
-    const block2 = {
-      id: "1ff065e9-88e8-4358-9d82-8dc91f622ba9",
-      name: "Store Value 2",
-      description: "Store Value Block 2",
-      type: "Standard",
-    };
-
-    // Add the blocks
-    await buildPage.addBlock(block1);
-    await buildPage.addBlock(block2);
-    await buildPage.closeBlocksPanel();
-
-    // Connect the blocks
-    await buildPage.connectBlockOutputToBlockInputViaDataId(
-      "1-1-output-source",
-      "1-2-input-target",
-    );
-
-    // Fill in the input for the first block
-    await buildPage.fillBlockInputByPlaceholder(
-      block1.id,
-      "Enter input",
-      "Test Value",
-      "1",
-    );
-
-    // Save the agent and wait for the URL to update
-    await buildPage.saveAgent(
-      "Connected Blocks Test",
-      "Testing block connections",
-    );
-    await test.expect(page).toHaveURL(({ searchParams }) => !!searchParams.get("flowID"));
-
-    // Wait for the save button to be enabled again
+    await buildPage.saveAgent("Runnable Agent", "Test run button");
+    await buildPage.waitForSaveComplete();
     await buildPage.waitForSaveButton();
 
-    // Ensure the run button is enabled
-    await test.expect(buildPage.isRunButtonEnabled()).resolves.toBeTruthy();
+    await expect(buildPage.isRunButtonEnabled()).resolves.toBeTruthy();
   });
 
-  test.skip("user can build an agent with inputs and output blocks", async ({ page }, testInfo) => {
-    test.setTimeout(testInfo.timeout * 10);
+  // --- Copy / Paste test ---
 
-    // prep
-    await buildPage.openBlocksPanel();
+  test("user can copy and paste a node", async ({ context }) => {
+    await context.grantPermissions(["clipboard-read", "clipboard-write"]);
 
-    // Get input block from Input category
-    const inputBlocks = await buildPage.getBlocksForCategory("Input");
-    const inputBlock = inputBlocks.find((b) => b.name === "Agent Input");
-    if (!inputBlock) throw new Error("Input block not found");
-    await buildPage.addBlock(inputBlock);
+    await buildPage.addBlockByClick("Store Value");
+    await buildPage.waitForNodeOnCanvas(1);
 
-    // Get output block from Output category  
-    const outputBlocks = await buildPage.getBlocksForCategory("Output");
-    const outputBlock = outputBlocks.find((b) => b.name === "Agent Output");
-    if (!outputBlock) throw new Error("Output block not found");
-    await buildPage.addBlock(outputBlock);
+    await buildPage.selectNode(0);
+    await buildPage.copyViaKeyboard();
+    await buildPage.pasteViaKeyboard();
 
-    // Get calculator block from Logic category
-    const logicBlocks = await buildPage.getBlocksForCategory("Logic");
-    const calculatorBlock = logicBlocks.find((b) => b.name === "Calculator");
-    if (!calculatorBlock) throw new Error("Calculator block not found");
-    await buildPage.addBlock(calculatorBlock);
+    await buildPage.waitForNodeOnCanvas(2);
+    expect(await buildPage.getNodeCount()).toBe(2);
+  });
 
-    await buildPage.closeBlocksPanel();
+  // --- Run agent test ---
 
-    // Wait for blocks to be fully loaded
-    await page.waitForTimeout(1000);
+  test("user can run an agent from the builder", async () => {
+    await buildPage.addBlockByClick("Store Value");
+    await buildPage.waitForNodeOnCanvas(1);
 
-    // Wait for blocks to be ready for connections
-    await page.waitForTimeout(1000);
+    // Save the agent (required before running)
+    await buildPage.saveAgent("Run Test Agent", "Testing run from builder");
+    await buildPage.waitForSaveComplete();
+    await buildPage.waitForSaveButton();
 
-    await buildPage.connectBlockOutputToBlockInputViaName(
-      inputBlock.id,
-      "Result",
-      calculatorBlock.id,
-      "A",
-    );
-    await buildPage.connectBlockOutputToBlockInputViaName(
-      inputBlock.id,
-      "Result",
-      calculatorBlock.id,
-      "B",
-    );
-    await buildPage.connectBlockOutputToBlockInputViaName(
-      calculatorBlock.id,
-      "Result",
-      outputBlock.id,
-      "Value",
-    );
+    // Click run button
+    await buildPage.clickRunButton();
 
-    // Wait for connections to stabilize
-    await page.waitForTimeout(1000);
+    // Either the run dialog appears or the agent starts running directly
+    const runDialogOrRunning = await Promise.race([
+      buildPage
+        .getPlaywrightPage()
+        .locator('[data-id="run-input-dialog-content"]')
+        .waitFor({ state: "visible", timeout: 10000 })
+        .then(() => "dialog"),
+      buildPage
+        .getPlaywrightPage()
+        .locator('[data-id="stop-graph-button"]')
+        .waitFor({ state: "visible", timeout: 10000 })
+        .then(() => "running"),
+    ]).catch(() => "timeout");
 
-    await buildPage.fillBlockInputByPlaceholder(
-      inputBlock.id,
-      "Enter Name",
-      "Value",
-    );
-    await buildPage.fillBlockInputByPlaceholder(
-      outputBlock.id,
-      "Enter Name",
-      "Doubled",
-    );
-
-    // Wait before changing dropdown
-    await page.waitForTimeout(500);
-
-    await buildPage.selectBlockInputValue(
-      calculatorBlock.id,
-      "Operation",
-      "Add",
-    );
-
-    // Wait before saving
-    await page.waitForTimeout(1000);
-
-    await buildPage.saveAgent(
-      "Input and Output Blocks Test",
-      "Testing input and output blocks",
-    );
-    await test.expect(page).toHaveURL(({ searchParams }) => !!searchParams.get("flowID"));
-
-    // Wait for save to complete
-    await page.waitForTimeout(1000);
-
-    // await buildPage.runAgent();
-    // await buildPage.fillRunDialog({
-    //   Value: "10",
-    // });
-    // await buildPage.clickRunDialogRunButton();
-    // await buildPage.waitForCompletionBadge();
-    // await test
-    //   .expect(buildPage.isCompletionBadgeVisible())
-    //   .resolves.toBeTruthy();
+    expect(["dialog", "running"]).toContain(runDialogOrRunning);
   });
 });

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

@@ -1,44 +1,47 @@
-import { Locator, Page } from "@playwright/test";
-import { Block as APIBlock } from "../../lib/autogpt-server-api/types";
-import { beautifyString } from "../../lib/utils";
+import { expect, Locator, Page } from "@playwright/test";
 import { BasePage } from "./base.page";
 
-export interface Block {
-  id: string;
-  name: string;
-  description: string;
-  type: string;
-}
-
 export class BuildPage extends BasePage {
-  private cachedBlocks: Record<string, Block> = {};
-
   constructor(page: Page) {
     super(page);
   }
 
-  private getDisplayName(blockName: string): string {
-    return beautifyString(blockName).replace(/ Block$/, "");
+  // --- Navigation ---
+
+  async goto(): Promise<void> {
+    await this.page.goto("/build");
+    await this.page.waitForLoadState("domcontentloaded");
+  }
+
+  async isLoaded(): Promise<boolean> {
+    try {
+      await this.page.waitForLoadState("domcontentloaded", { timeout: 10_000 });
+      await this.page
+        .locator(".react-flow")
+        .waitFor({ state: "visible", timeout: 10_000 });
+      return true;
+    } catch {
+      return false;
+    }
   }
 
   async closeTutorial(): Promise<void> {
-    console.log(`closing tutorial`);
     try {
       await this.page
         .getByRole("button", { name: "Skip Tutorial", exact: true })
         .click({ timeout: 3000 });
-    } catch (_error) {
-      console.info("Tutorial not shown or already dismissed");
+    } catch {
+      // Tutorial not shown or already dismissed
     }
   }
 
+  // --- Block Menu ---
+
   async openBlocksPanel(): Promise<void> {
     const popoverContent = this.page.locator(
       '[data-id="blocks-control-popover-content"]',
     );
-    const isPanelOpen = await popoverContent.isVisible();
-
-    if (!isPanelOpen) {
+    if (!(await popoverContent.isVisible())) {
       await this.page.getByTestId("blocks-control-blocks-button").click();
       await popoverContent.waitFor({ state: "visible", timeout: 5000 });
     }
@@ -50,501 +53,258 @@ export class BuildPage extends BasePage {
     );
     if (await popoverContent.isVisible()) {
       await this.page.getByTestId("blocks-control-blocks-button").click();
+      await popoverContent.waitFor({ state: "hidden", timeout: 5000 });
     }
   }
 
+  async searchBlock(searchTerm: string): Promise<void> {
+    const searchInput = this.page.locator(
+      '[data-id="blocks-control-search-bar"] input[type="text"]',
+    );
+    await searchInput.clear();
+    await searchInput.fill(searchTerm);
+    await this.page.waitForTimeout(300);
+  }
+
+  private getBlockCardByName(name: string): Locator {
+    const escapedName = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const exactName = new RegExp(`^\\s*${escapedName}\\s*$`, "i");
+    return this.page
+      .locator('[data-id^="block-card-"]')
+      .filter({ has: this.page.locator("span", { hasText: exactName }) })
+      .first();
+  }
+
+  async addBlockByClick(searchTerm: string): Promise<void> {
+    await this.openBlocksPanel();
+    await this.searchBlock(searchTerm);
+
+    // Wait for any search results to appear
+    const anyCard = this.page.locator('[data-id^="block-card-"]').first();
+    await anyCard.waitFor({ state: "visible", timeout: 10000 });
+
+    // Click the card matching the search term name
+    const blockCard = this.getBlockCardByName(searchTerm);
+    await blockCard.waitFor({ state: "visible", timeout: 5000 });
+    await blockCard.click();
+
+    // Close the panel so it doesn't overlay the canvas
+    await this.closeBlocksPanel();
+  }
+
+  async dragBlockToCanvas(searchTerm: string): Promise<void> {
+    await this.openBlocksPanel();
+    await this.searchBlock(searchTerm);
+
+    const anyCard = this.page.locator('[data-id^="block-card-"]').first();
+    await anyCard.waitFor({ state: "visible", timeout: 10000 });
+
+    const blockCard = this.getBlockCardByName(searchTerm);
+    await blockCard.waitFor({ state: "visible", timeout: 5000 });
+
+    const canvas = this.page.locator(".react-flow__pane").first();
+    await blockCard.dragTo(canvas);
+  }
+
+  // --- Nodes on Canvas ---
+
+  getNodeLocator(index?: number): Locator {
+    const locator = this.page.locator('[data-id^="custom-node-"]');
+    return index !== undefined ? locator.nth(index) : locator;
+  }
+
+  async getNodeCount(): Promise<number> {
+    return await this.getNodeLocator().count();
+  }
+
+  async waitForNodeOnCanvas(expectedCount?: number): Promise<void> {
+    if (expectedCount !== undefined) {
+      await expect(this.getNodeLocator()).toHaveCount(expectedCount, {
+        timeout: 10000,
+      });
+    } else {
+      await this.getNodeLocator()
+        .first()
+        .waitFor({ state: "visible", timeout: 10000 });
+    }
+  }
+
+  async selectNode(index: number = 0): Promise<void> {
+    const node = this.getNodeLocator(index);
+    await node.click();
+  }
+
+  async selectAllNodes(): Promise<void> {
+    await this.page.locator(".react-flow__pane").first().click();
+    const isMac = process.platform === "darwin";
+    await this.page.keyboard.press(isMac ? "Meta+a" : "Control+a");
+  }
+
+  async deleteSelectedNodes(): Promise<void> {
+    await this.page.keyboard.press("Backspace");
+  }
+
+  // --- Connections (Edges) ---
+
+  async connectNodes(
+    sourceNodeIndex: number,
+    targetNodeIndex: number,
+  ): Promise<void> {
+    // Get the node wrapper elements to scope handle search
+    const sourceNode = this.getNodeLocator(sourceNodeIndex);
+    const targetNode = this.getNodeLocator(targetNodeIndex);
+
+    // ReactFlow renders Handle components as .react-flow__handle elements
+    // Output handles have class .react-flow__handle-right (Position.Right)
+    // Input handles have class .react-flow__handle-left (Position.Left)
+    const sourceHandle = sourceNode
+      .locator(".react-flow__handle-right")
+      .first();
+    const targetHandle = targetNode.locator(".react-flow__handle-left").first();
+
+    // Get precise center coordinates using evaluate to avoid CSS transform issues
+    const getHandleCenter = async (locator: Locator) => {
+      const el = await locator.elementHandle();
+      if (!el) throw new Error("Handle element not found");
+      const rect = await el.evaluate((node) => {
+        const r = node.getBoundingClientRect();
+        return { x: r.x + r.width / 2, y: r.y + r.height / 2 };
+      });
+      return rect;
+    };
+
+    const source = await getHandleCenter(sourceHandle);
+    const target = await getHandleCenter(targetHandle);
+
+    // ReactFlow requires a proper drag sequence with intermediate moves
+    await this.page.mouse.move(source.x, source.y);
+    await this.page.mouse.down();
+    // Move in steps to trigger ReactFlow's connection detection
+    const steps = 20;
+    for (let i = 1; i <= steps; i++) {
+      const ratio = i / steps;
+      await this.page.mouse.move(
+        source.x + (target.x - source.x) * ratio,
+        source.y + (target.y - source.y) * ratio,
+      );
+    }
+    await this.page.mouse.up();
+  }
+
+  async getEdgeCount(): Promise<number> {
+    return await this.page.locator(".react-flow__edge").count();
+  }
+
+  // --- Save ---
+
   async saveAgent(
     name: string = "Test Agent",
     description: string = "",
   ): Promise<void> {
-    console.log(`Saving agent '${name}' with description '${description}'`);
     await this.page.getByTestId("save-control-save-button").click();
-    await this.page.getByTestId("save-control-name-input").fill(name);
-    await this.page
-      .getByTestId("save-control-description-input")
-      .fill(description);
+
+    const nameInput = this.page.getByTestId("save-control-name-input");
+    await nameInput.waitFor({ state: "visible", timeout: 5000 });
+    await nameInput.fill(name);
+
+    if (description) {
+      await this.page
+        .getByTestId("save-control-description-input")
+        .fill(description);
+    }
+
     await this.page.getByTestId("save-control-save-agent-button").click();
   }
 
-  async getBlocksFromAPI(): Promise<Block[]> {
-    if (Object.keys(this.cachedBlocks).length > 0) {
-      return Object.values(this.cachedBlocks);
-    }
+  async waitForSaveComplete(): Promise<void> {
+    await expect(this.page).toHaveURL(/flowID=/, { timeout: 15000 });
+  }
 
-    console.log(`Getting blocks from API request`);
-
-    // Make direct API request using the page's request context
-    const response = await this.page.request.get(
-      "http://localhost:3000/api/proxy/api/blocks",
+  async waitForSaveButton(): Promise<void> {
+    await this.page.waitForSelector(
+      '[data-testid="save-control-save-button"]:not([disabled])',
+      { timeout: 10000 },
     );
-    const apiBlocks: APIBlock[] = await response.json();
-
-    console.log(`Found ${apiBlocks.length} blocks from API`);
-
-    // Convert API blocks to test Block format
-    const blocks = apiBlocks.map((block) => ({
-      id: block.id,
-      name: block.name,
-      description: block.description,
-      type: block.uiType,
-    }));
-
-    this.cachedBlocks = blocks.reduce(
-      (acc, block) => {
-        acc[block.id] = block;
-        return acc;
-      },
-      {} as Record<string, Block>,
-    );
-    return blocks;
   }
 
-  async getFilteredBlocksFromAPI(
-    filterFn: (block: Block) => boolean,
-  ): Promise<Block[]> {
-    console.log(`Getting filtered blocks from API`);
-    const blocks = await this.getBlocksFromAPI();
-    return blocks.filter(filterFn);
-  }
-
-  async addBlock(block: Block): Promise<void> {
-    console.log(`Adding block ${block.name} (${block.id}) to agent`);
-
-    await this.openBlocksPanel();
-
-    const searchInput = this.page.locator(
-      '[data-id="blocks-control-search-bar"] input[type="text"]',
-    );
-
-    const displayName = this.getDisplayName(block.name);
-    await searchInput.clear();
-    await searchInput.fill(displayName);
-
-    const blockCardId = block.id.replace(/[^a-zA-Z0-9]/g, "");
-    const blockCard = this.page.locator(
-      `[data-id="block-card-${blockCardId}"]`,
-    );
-
-    await blockCard.waitFor({ state: "visible", timeout: 10000 });
-    await blockCard.click();
-  }
-
-  async hasBlock(_block: Block) {
-    // In the new flow editor, verify a node exists on the canvas
-    const node = this.page.locator('[data-id^="custom-node-"]').first();
-    await node.isVisible();
-  }
-
-  async getBlockInputs(blockId: string): Promise<string[]> {
-    console.log(`Getting block ${blockId} inputs`);
-    try {
-      const node = this.page.locator(`[data-blockid="${blockId}"]`).first();
-      const inputsData = await node.getAttribute("data-inputs");
-      return inputsData ? JSON.parse(inputsData) : [];
-    } catch (error) {
-      console.error("Error getting block inputs:", error);
-      return [];
-    }
-  }
-
-  async selectBlockCategory(category: string): Promise<void> {
-    console.log(`Selecting block category: ${category}`);
-    await this.page.getByText(category, { exact: true }).click();
-    // Wait for the blocks to load after category selection
-    await this.page.waitForTimeout(3000);
-  }
-
-  async getBlocksForCategory(category: string): Promise<Block[]> {
-    console.log(`Getting blocks for category: ${category}`);
-
-    // Clear any existing search to ensure we see all blocks in the category
-    const searchInput = this.page.locator(
-      '[data-id="blocks-control-search-bar"] input[type="text"]',
-    );
-    await searchInput.clear();
-
-    // Wait for search to clear
-    await this.page.waitForTimeout(300);
-
-    // Select the category first
-    await this.selectBlockCategory(category);
-
-    try {
-      const blockFinder = this.page.locator('[data-id^="block-card-"]');
-      await blockFinder.first().waitFor();
-      const blocks = await blockFinder.all();
-
-      console.log(`found ${blocks.length} blocks in category ${category}`);
-
-      const results = await Promise.all(
-        blocks.map(async (block) => {
-          try {
-            const fullId = (await block.getAttribute("data-id")) || "";
-            const id = fullId.replace("block-card-", "");
-            const nameElement = block.locator('[data-testid^="block-name-"]');
-            const descriptionElement = block.locator(
-              '[data-testid^="block-description-"]',
-            );
-
-            const name = (await nameElement.textContent()) || "";
-            const description = (await descriptionElement.textContent()) || "";
-            const type = (await nameElement.getAttribute("data-type")) || "";
-
-            return {
-              id,
-              name: name.trim(),
-              type: type.trim(),
-              description: description.trim(),
-            };
-          } catch (elementError) {
-            console.error("Error processing block:", elementError);
-            return null;
-          }
-        }),
-      );
-
-      // Filter out any null results from errors
-      return results.filter((block): block is Block => block !== null);
-    } catch (error) {
-      console.error(`Error getting blocks for category ${category}:`, error);
-      return [];
-    }
-  }
-
-  async _buildBlockSelector(blockId: string, dataId?: string): Promise<string> {
-    const selector = dataId
-      ? `[data-id="${dataId}"] [data-blockid="${blockId}"]`
-      : `[data-blockid="${blockId}"]`;
-    return selector;
-  }
-
-  private async moveBlockToViewportPosition(
-    blockSelector: string,
-    options: { xRatio?: number; yRatio?: number } = {},
-  ): Promise<void> {
-    const { xRatio = 0.5, yRatio = 0.5 } = options;
-    const blockLocator = this.page.locator(blockSelector).first();
-
-    await blockLocator.waitFor({ state: "visible" });
-
-    const boundingBox = await blockLocator.boundingBox();
-    const viewport = this.page.viewportSize();
-
-    if (!boundingBox || !viewport) {
-      return;
-    }
-
-    const currentX = boundingBox.x + boundingBox.width / 2;
-    const currentY = boundingBox.y + boundingBox.height / 2;
-
-    const targetX = viewport.width * xRatio;
-    const targetY = viewport.height * yRatio;
-
-    const distance = Math.hypot(targetX - currentX, targetY - currentY);
-
-    if (distance < 5) {
-      return;
-    }
-
-    await this.page.mouse.move(currentX, currentY);
-    await this.page.mouse.down();
-    await this.page.mouse.move(targetX, targetY, { steps: 15 });
-    await this.page.mouse.up();
-    await this.page.waitForTimeout(200);
-  }
-
-  async getBlockById(blockId: string, dataId?: string): Promise<Locator> {
-    console.log(`getting block ${blockId} with dataId ${dataId}`);
-    return this.page.locator(await this._buildBlockSelector(blockId, dataId));
-  }
-
-  // dataId is optional, if provided, it will start the search with that container, otherwise it will start with the blockId
-  // this is useful if you have multiple blocks with the same id, but different dataIds which you should have when adding a block to the graph.
-  // Do note that once you run an agent, the dataId will change, so you will need to update the tests to use the new dataId or not use the same block in tests that run an agent
-  async fillBlockInputByPlaceholder(
-    blockId: string,
-    placeholder: string,
-    value: string,
-    dataId?: string,
-  ): Promise<void> {
-    console.log(
-      `filling block input ${placeholder} with value ${value} of block ${blockId}`,
-    );
-    const block = await this.getBlockById(blockId, dataId);
-    const input = block.getByPlaceholder(placeholder);
-    await input.fill(value);
-  }
-
-  async selectBlockInputValue(
-    blockId: string,
-    inputName: string,
-    value: string,
-    dataId?: string,
-  ): Promise<void> {
-    console.log(
-      `selecting value ${value} for input ${inputName} of block ${blockId}`,
-    );
-    // First get the button that opens the dropdown
-    const baseSelector = await this._buildBlockSelector(blockId, dataId);
-
-    // Find the combobox button within the input handle container
-    const comboboxSelector = `${baseSelector} [data-id="input-handle-${inputName.toLowerCase()}"] button[role="combobox"]`;
-
-    try {
-      // Click the combobox to open it
-      await this.page.click(comboboxSelector);
-
-      // Wait a moment for the dropdown to open
-      await this.page.waitForTimeout(100);
-
-      // Select the option from the dropdown
-      // The actual selector for the option might need adjustment based on the dropdown structure
-      await this.page.getByRole("option", { name: value }).click();
-    } catch (error) {
-      console.error(
-        `Error selecting value "${value}" for input "${inputName}":`,
-        error,
-      );
-      throw error;
-    }
-  }
-
-  async fillBlockInputByLabel(
-    blockId: string,
-    label: string,
-    value: string,
-  ): Promise<void> {
-    console.log(`filling block input ${label} with value ${value}`);
-    const block = await this.getBlockById(blockId);
-    const input = block.getByLabel(label);
-    await input.fill(value);
-  }
-
-  async connectBlockOutputToBlockInputViaDataId(
-    blockOutputId: string,
-    blockInputId: string,
-  ): Promise<void> {
-    console.log(
-      `connecting block output ${blockOutputId} to block input ${blockInputId}`,
-    );
-    try {
-      // Locate the output element
-      const outputElement = this.page.locator(`[data-id="${blockOutputId}"]`);
-      // Locate the input element
-      const inputElement = this.page.locator(`[data-id="${blockInputId}"]`);
-
-      await outputElement.dragTo(inputElement);
-    } catch (error) {
-      console.error("Error connecting block output to input:", error);
-    }
-  }
-
-  async connectBlockOutputToBlockInputViaName(
-    startBlockId: string,
-    startBlockOutputName: string,
-    endBlockId: string,
-    endBlockInputName: string,
-    startDataId?: string,
-    endDataId?: string,
-  ): Promise<void> {
-    console.log(
-      `connecting block output ${startBlockOutputName} of block ${startBlockId} to block input ${endBlockInputName} of block ${endBlockId}`,
-    );
-
-    const startBlockBase = await this._buildBlockSelector(
-      startBlockId,
-      startDataId,
-    );
-
-    const endBlockBase = await this._buildBlockSelector(endBlockId, endDataId);
-
-    await this.moveBlockToViewportPosition(startBlockBase, { xRatio: 0.35 });
-    await this.moveBlockToViewportPosition(endBlockBase, { xRatio: 0.65 });
-
-    const startBlockOutputSelector = `${startBlockBase} [data-testid="output-handle-${startBlockOutputName.toLowerCase()}"]`;
-    const endBlockInputSelector = `${endBlockBase} [data-testid="input-handle-${endBlockInputName.toLowerCase()}"]`;
-
-    console.log("Start block selector:", startBlockOutputSelector);
-    console.log("End block selector:", endBlockInputSelector);
-
-    const startElement = this.page.locator(startBlockOutputSelector);
-    const endElement = this.page.locator(endBlockInputSelector);
-
-    await startElement.scrollIntoViewIfNeeded();
-    await this.page.waitForTimeout(200);
-
-    await endElement.scrollIntoViewIfNeeded();
-    await this.page.waitForTimeout(200);
-
-    await startElement.dragTo(endElement);
-  }
-
-  async isLoaded(): Promise<boolean> {
-    console.log(`checking if build page is loaded`);
-    try {
-      await this.page.waitForLoadState("domcontentloaded", { timeout: 10_000 });
-      return true;
-    } catch {
-      return false;
-    }
-  }
+  // --- Run ---
 
   async isRunButtonEnabled(): Promise<boolean> {
-    console.log(`checking if run button is enabled`);
     const runButton = this.page.locator('[data-id="run-graph-button"]');
     return await runButton.isEnabled();
   }
 
-  async runAgent(): Promise<void> {
-    console.log(`clicking run button`);
+  async clickRunButton(): Promise<void> {
     const runButton = this.page.locator('[data-id="run-graph-button"]');
     await runButton.click();
-    await this.page.waitForTimeout(1000);
-    await runButton.click();
   }
 
-  async fillRunDialog(inputs: Record<string, string>): Promise<void> {
-    console.log(`filling run dialog`);
-    for (const [key, value] of Object.entries(inputs)) {
-      await this.page.getByTestId(`agent-input-${key}`).fill(value);
+  // --- Undo / Redo ---
+
+  async isUndoEnabled(): Promise<boolean> {
+    const btn = this.page.locator('[data-id="undo-button"]');
+    return !(await btn.isDisabled());
+  }
+
+  async isRedoEnabled(): Promise<boolean> {
+    const btn = this.page.locator('[data-id="redo-button"]');
+    return !(await btn.isDisabled());
+  }
+
+  async clickUndo(): Promise<void> {
+    await this.page.locator('[data-id="undo-button"]').click();
+  }
+
+  async clickRedo(): Promise<void> {
+    await this.page.locator('[data-id="redo-button"]').click();
+  }
+
+  // --- Copy / Paste ---
+
+  async copyViaKeyboard(): Promise<void> {
+    const isMac = process.platform === "darwin";
+    await this.page.keyboard.press(isMac ? "Meta+c" : "Control+c");
+  }
+
+  async pasteViaKeyboard(): Promise<void> {
+    const isMac = process.platform === "darwin";
+    await this.page.keyboard.press(isMac ? "Meta+v" : "Control+v");
+  }
+
+  // --- Helpers ---
+
+  async fillBlockInputByPlaceholder(
+    placeholder: string,
+    value: string,
+    nodeIndex: number = 0,
+  ): Promise<void> {
+    const node = this.getNodeLocator(nodeIndex);
+    const input = node.getByPlaceholder(placeholder);
+    await input.fill(value);
+  }
+
+  async clickCanvas(): Promise<void> {
+    const pane = this.page.locator(".react-flow__pane").first();
+    const box = await pane.boundingBox();
+    if (box) {
+      // Click in the center of the canvas to avoid sidebar/toolbar overlaps
+      await pane.click({
+        position: { x: box.width / 2, y: box.height / 2 },
+      });
+    } else {
+      await pane.click();
     }
   }
-  async clickRunDialogRunButton(): Promise<void> {
-    console.log(`clicking run button`);
-    await this.page.getByTestId("agent-run-button").click();
+
+  getPlaywrightPage(): Page {
+    return this.page;
   }
 
-  async waitForCompletionBadge(): Promise<void> {
-    console.log(`waiting for completion badge`);
-    await this.page.waitForSelector(
-      '[data-id^="badge-"][data-id$="-COMPLETED"]',
-    );
-  }
-
-  async waitForSaveButton(): Promise<void> {
-    console.log(`waiting for save button`);
-    await this.page.waitForSelector(
-      '[data-testid="save-control-save-button"]:not([disabled])',
-    );
-  }
-
-  async isCompletionBadgeVisible(): Promise<boolean> {
-    console.log(`checking for completion badge`);
-    const completionBadge = this.page
-      .locator('[data-id^="badge-"][data-id$="-COMPLETED"]')
-      .first();
-    return await completionBadge.isVisible();
-  }
-
-  async waitForVersionField(): Promise<void> {
-    console.log(`waiting for version field`);
-
-    // wait for the url to have the flowID
-    await this.page.waitForSelector(
-      '[data-testid="save-control-version-output"]',
-    );
-  }
-
-  async getDictionaryBlockDetails(): Promise<Block> {
-    return {
-      id: "dummy-id-1",
-      name: "Add to Dictionary",
-      description: "Add to Dictionary",
-      type: "Standard",
-    };
-  }
-
-  async getCalculatorBlockDetails(): Promise<Block> {
-    return {
-      id: "dummy-id-2",
-      name: "Calculator",
-      description: "Calculator",
-      type: "Standard",
-    };
-  }
-
-  async waitForSaveDialogClose(): Promise<void> {
-    console.log(`waiting for save dialog to close`);
-
-    await this.page.waitForSelector(
-      '[data-id="save-control-popover-content"]',
-      { state: "hidden" },
-    );
-  }
-
-  async getGithubTriggerBlockDetails(): Promise<Block[]> {
-    return [
-      {
-        id: "6c60ec01-8128-419e-988f-96a063ee2fea",
-        name: "Github Trigger",
-        description:
-          "This block triggers on pull request events and outputs the event type and payload.",
-        type: "Standard",
-      },
-      {
-        id: "551e0a35-100b-49b7-89b8-3031322239b6",
-        name: "Github Star Trigger",
-        description:
-          "This block triggers on star events and outputs the event type and payload.",
-        type: "Standard",
-      },
-      {
-        id: "2052dd1b-74e1-46ac-9c87-c7a0e057b60b",
-        name: "Github Release Trigger",
-        description:
-          "This block triggers on release events and outputs the event type and payload.",
-        type: "Standard",
-      },
-      {
-        id: "b2605464-e486-4bf4-aad3-d8a213c8a48a",
-        name: "Github Issue Trigger",
-        description:
-          "This block triggers on issue events and outputs the event type and payload.",
-        type: "Standard",
-      },
-      {
-        id: "87f847b3-d81a-424e-8e89-acadb5c9d52b",
-        name: "Github Discussion Trigger",
-        description:
-          "This block triggers on discussion events and outputs the event type and payload.",
-        type: "Standard",
-      },
-    ];
-  }
-
-  async nextTutorialStep(): Promise<void> {
-    console.log(`clicking next tutorial step`);
-    await this.page.getByRole("button", { name: "Next" }).click();
-  }
-
-  async getBlocksToSkip(): Promise<string[]> {
-    return [
-      (await this.getGithubTriggerBlockDetails()).map((b) => b.id),
-      // MCP Tool block requires an interactive dialog (server URL + OAuth) before
-      // it can be placed, so it can't be tested via the standard "add block" flow.
-      "a0a4b1c2-d3e4-4f56-a7b8-c9d0e1f2a3b4",
-    ].flat();
-  }
-
-  async createDummyAgent() {
+  async createDummyAgent(): Promise<void> {
     await this.closeTutorial();
-    await this.openBlocksPanel();
-
-    const searchInput = this.page.locator(
-      '[data-id="blocks-control-search-bar"] input[type="text"]',
-    );
-
-    await searchInput.clear();
-    await searchInput.fill("Add to Dictionary");
-
-    const blockCard = this.page.locator('[data-id^="block-card-"]').first();
-    try {
-      await blockCard.waitFor({ state: "visible", timeout: 10000 });
-      await blockCard.click();
-    } catch (error) {
-      console.log("Could not find Add to Dictionary block:", error);
-    }
-
+    await this.addBlockByClick("Add to Dictionary");
+    await this.waitForNodeOnCanvas(1);
     await this.saveAgent("Test Agent", "Test Description");
+    await this.waitForSaveComplete();
   }
 }