yeet migrations that we don't need anymore (left over from conflict resolution on marketplace DB layer cleanup)

`responseType.ts` was accidentally committed inside
`src/app/api/__generated__/models/` despite that directory being listed
in `.gitignore` (added in PR #12238).

### Changes 🏗️

- Removes
`autogpt_platform/frontend/src/app/api/__generated__/models/responseType.ts`
from git tracking — the file is already covered by the `.gitignore` rule
`src/app/api/__generated__/` and should never have been committed.

### Checklist 📋

#### For code changes:
- [x] I have clearly listed my changes in the PR description
- [x] I have made a test plan
- [x] I have tested my changes according to the test plan:
- [x] No functional changes — only removes a stale tracked file that is
already gitignored

.claude/skills/backend-check/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: backend-check
+description: Run the full backend formatting, linting, and test suite. Ensures code quality before commits and PRs. TRIGGER when backend Python code has been modified and needs validation.
+user-invocable: true
+metadata:
+  author: autogpt-team
+  version: "1.0.0"
+---
+
+# Backend Check
+
+## Steps
+
+1. **Format**: `poetry run format` — runs formatting AND linting. NEVER run ruff/black/isort individually
+2. **Fix** any remaining errors manually, re-run until clean
+3. **Test**: `poetry run test` (runs DB setup + pytest). For specific files: `poetry run pytest -s -vvv <test_files>`
+4. **Snapshots** (if needed): `poetry run pytest path/to/test.py --snapshot-update` — review with `git diff`

.claude/skills/code-style/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: code-style
+description: Python code style preferences for the AutoGPT backend. Apply when writing or reviewing Python code. TRIGGER when writing new Python code, reviewing PRs, or refactoring backend code.
+user-invocable: false
+metadata:
+  author: autogpt-team
+  version: "1.0.0"
+---
+
+# Code Style
+
+## Imports
+
+- **Top-level only** — no local/inner imports. Move all imports to the top of the file.
+
+## Typing
+
+- **No duck typing** — avoid `hasattr`, `getattr`, `isinstance` for type dispatch. Use proper typed interfaces, unions, or protocols.
+- **Pydantic models** over dataclass, namedtuple, or raw dict for structured data.
+- **No linter suppressors** — avoid `# type: ignore`, `# noqa`, `# pyright: ignore` etc. 99% of the time the right fix is fixing the type/code, not silencing the tool.
+
+## Code Structure
+
+- **List comprehensions** over manual loop-and-append.
+- **Early return** — guard clauses first, avoid deep nesting.
+- **Flatten inline** — prefer short, concise expressions. Reduce `if/else` chains with direct returns or ternaries when readable.
+- **Modular functions** — break complex logic into small, focused functions rather than long blocks with nested conditionals.
+
+## Review Checklist
+
+Before finishing, always ask:
+- Can any function be split into smaller pieces?
+- Is there unnecessary nesting that an early return would eliminate?
+- Can any loop be a comprehension?
+- Is there a simpler way to express this logic?

.claude/skills/frontend-check/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: frontend-check
+description: Run the full frontend formatting, linting, and type checking suite. Ensures code quality before commits and PRs. TRIGGER when frontend TypeScript/React code has been modified and needs validation.
+user-invocable: true
+metadata:
+  author: autogpt-team
+  version: "1.0.0"
+---
+
+# Frontend Check
+
+## Steps (in order)
+
+1. **Format**: `pnpm format` — NEVER run individual formatters
+2. **Lint**: `pnpm lint` — fix errors, re-run until clean
+3. **Types**: `pnpm types` — if it keeps failing after multiple attempts, stop and ask the user

.claude/skills/new-block/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: new-block
+description: Create a new backend block following the Block SDK Guide. Guides through provider configuration, schema definition, authentication, and testing. TRIGGER when user asks to create a new block, add a new integration, or build a new node for the graph editor.
+user-invocable: true
+metadata:
+  author: autogpt-team
+  version: "1.0.0"
+---
+
+# New Block Creation
+
+Read `docs/platform/block-sdk-guide.md` first for the full guide.
+
+## Steps
+
+1. **Provider config** (if external service): create `_config.py` with `ProviderBuilder`
+2. **Block file** in `backend/blocks/` (from `autogpt_platform/backend/`):
+   - Generate a UUID once with `uuid.uuid4()`, then **hard-code that string** as `id` (IDs must be stable across imports)
+   - `Input(BlockSchema)` and `Output(BlockSchema)` classes
+   - `async def run` that `yield`s output fields
+3. **Files**: use `store_media_file()` with `"for_block_output"` for outputs
+4. **Test**: `poetry run pytest 'backend/blocks/test/test_block.py::test_available_blocks[MyBlock]' -xvs`
+5. **Format**: `poetry run format`
+
+## Rules
+
+- Analyze interfaces: do inputs/outputs connect well with other blocks in a graph?
+- Use top-level imports, avoid duck typing
+- Always use `for_block_output` for block outputs

.claude/skills/openapi-regen/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: openapi-regen
+description: Regenerate the OpenAPI spec and frontend API client. Starts the backend REST server, fetches the spec, and regenerates the typed frontend hooks. TRIGGER when API routes change, new endpoints are added, or frontend API types are stale.
+user-invocable: true
+metadata:
+  author: autogpt-team
+  version: "1.0.0"
+---
+
+# OpenAPI Spec Regeneration
+
+## Steps
+
+1. **Run end-to-end** in a single shell block (so `REST_PID` persists):
+   ```bash
+   cd autogpt_platform/backend && poetry run rest &
+   REST_PID=$!
+   WAIT=0; until curl -sf http://localhost:8006/health > /dev/null 2>&1; do sleep 1; WAIT=$((WAIT+1)); [ $WAIT -ge 60 ] && echo "Timed out" && kill $REST_PID && exit 1; done
+   cd ../frontend && pnpm generate:api:force
+   kill $REST_PID
+   pnpm types && pnpm lint && pnpm format
+   ```
+
+## Rules
+
+- Always use `pnpm generate:api:force` (not `pnpm generate:api`)
+- Don't manually edit files in `src/app/api/__generated__/`
+- Generated hooks follow: `use{Method}{Version}{OperationName}`

.claude/skills/pr-create/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: pr-create
+description: Create a pull request for the current branch. TRIGGER when user asks to create a PR, open a pull request, push changes for review, or submit work for merging.
+user-invocable: true
+metadata:
+  author: autogpt-team
+  version: "1.0.0"
+---
+
+# Create Pull Request
+
+## Steps
+
+1. **Check for existing PR**: `gh pr view --json url -q .url 2>/dev/null` — if a PR already exists, output its URL and stop
+2. **Understand changes**: `git status`, `git diff dev...HEAD`, `git log dev..HEAD --oneline`
+3. **Read PR template**: `.github/PULL_REQUEST_TEMPLATE.md`
+4. **Draft PR title**: Use conventional commits format (see CLAUDE.md for types and scopes)
+5. **Fill out PR template** as the body — be thorough in the Changes section
+6. **Format first** (if relevant changes exist):
+   - Backend: `cd autogpt_platform/backend && poetry run format`
+   - Frontend: `cd autogpt_platform/frontend && pnpm format`
+   - Fix any lint errors, then commit formatting changes before pushing
+7. **Push**: `git push -u origin HEAD`
+8. **Create PR**: `gh pr create --base dev`
+9. **Output** the PR URL
+
+## Rules
+
+- Always target `dev` branch
+- Do NOT run tests — CI will handle that
+- Use the PR template from `.github/PULL_REQUEST_TEMPLATE.md`

.claude/skills/pr-review/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: pr-review
+description: Address all open PR review comments systematically. Fetches comments, addresses each one, reacts +1/-1, and replies when clarification is needed. Keeps iterating until all comments are addressed and CI is green. TRIGGER when user shares a PR URL, asks to address review comments, fix PR feedback, or respond to reviewer comments.
+user-invocable: true
+metadata:
+  author: autogpt-team
+  version: "1.0.0"
+---
+
+# PR Review Comment Workflow
+
+## Steps
+
+1. **Find PR**: `gh pr list --head $(git branch --show-current) --repo Significant-Gravitas/AutoGPT`
+2. **Fetch comments** (all three sources):
+   - `gh api repos/Significant-Gravitas/AutoGPT/pulls/{N}/reviews` (top-level reviews)
+   - `gh api repos/Significant-Gravitas/AutoGPT/pulls/{N}/comments` (inline review comments)
+   - `gh api repos/Significant-Gravitas/AutoGPT/issues/{N}/comments` (PR conversation comments)
+3. **Skip** comments already reacted to by PR author
+4. **For each unreacted comment**:
+   - Read referenced code, make the fix (or reply if you disagree/need info)
+   - **Inline review comments** (`pulls/{N}/comments`):
+     - React: `gh api repos/.../pulls/comments/{ID}/reactions -f content="+1"` (or `-1`)
+     - Reply: `gh api repos/.../pulls/{N}/comments/{ID}/replies -f body="..."`
+   - **PR conversation comments** (`issues/{N}/comments`):
+     - React: `gh api repos/.../issues/comments/{ID}/reactions -f content="+1"` (or `-1`)
+     - No threaded replies — post a new issue comment if needed
+   - **Top-level reviews**: no reaction API — address in code, reply via issue comment if needed
+5. **Include autogpt-reviewer bot fixes** too
+6. **Format**: `cd autogpt_platform/backend && poetry run format`, `cd autogpt_platform/frontend && pnpm format`
+7. **Commit & push**
+8. **Re-fetch comments** immediately — address any new unreacted ones before waiting on CI
+9. **Stay productive while CI runs** — don't idle. In priority order:
+   - Run any pending local tests (`poetry run pytest`, e2e, etc.) and fix failures
+   - Address any remaining comments
+   - Only poll `gh pr checks {N}` as the last resort when there's truly nothing left to do
+10. **If CI fails** — fix, go back to step 6
+11. **Re-fetch comments again** after CI is green — address anything that appeared while CI was running
+12. **Done** only when: all comments reacted AND CI is green.
+
+## CRITICAL: Do Not Stop
+
+**Loop is: address → format → commit → push → re-check comments → run local tests → wait CI → re-check comments → repeat.**
+
+Never idle. If CI is running and you have nothing to address, run local tests. Waiting on CI is the last resort.
+
+## Rules
+
+- One todo per comment
+- For inline review comments: reply on existing threads. For PR conversation comments: post a new issue comment (API doesn't support threaded replies)
+- React to every comment: +1 addressed, -1 disagreed (with explanation)

.claude/skills/worktree-setup/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: worktree-setup
+description: Set up a new git worktree for parallel development. Creates the worktree, copies .env files, installs dependencies, generates Prisma client, and optionally starts the app (with port conflict resolution) or runs tests. TRIGGER when user asks to set up a worktree, work on a branch in isolation, or needs a separate environment for a branch or PR.
+user-invocable: true
+metadata:
+  author: autogpt-team
+  version: "1.0.0"
+---
+
+# Worktree Setup
+
+## Preferred: Use Branchlet
+
+The repo has a `.branchlet.json` config — it handles env file copying, dependency installation, and Prisma generation automatically.
+
+```bash
+npm install -g branchlet                                      # install once
+branchlet create -n <name> -s <source-branch> -b <new-branch>
+branchlet list --json   # list all worktrees
+```
+
+## Manual Fallback
+
+If branchlet isn't available:
+
+1. `git worktree add ../<RepoName><N> <branch-name>`
+2. Copy `.env` files: `backend/.env`, `frontend/.env`, `autogpt_platform/.env`, `db/docker/.env`
+3. Install deps:
+   - `cd autogpt_platform/backend && poetry install && poetry run prisma generate`
+   - `cd autogpt_platform/frontend && pnpm install`
+
+## Running the App
+
+Free ports first — backend uses: 8001, 8002, 8003, 8005, 8006, 8007, 8008.
+
+```bash
+for port in 8001 8002 8003 8005 8006 8007 8008; do
+  lsof -ti :$port | xargs kill -9 2>/dev/null || true
+done
+cd <worktree>/autogpt_platform/backend && poetry run app
+```
+
+## CoPilot Testing Gotcha
+
+SDK mode spawns a Claude subprocess — **won't work inside Claude Code**. Set `CHAT_USE_CLAUDE_AGENT_SDK=false` in `backend/.env` to use baseline mode.

.pre-commit-config.yaml

@@ -27,6 +27,103 @@ repos:
         exclude: pnpm-lock\.yaml$
         stages: [pre-push]
 
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.7.2
+    hooks:
+      - id: ruff
+        name: Lint (Ruff) - AutoGPT Platform - Backend
+        alias: ruff-lint-platform-backend
+        files: ^autogpt_platform/backend/
+        args: [--fix]
+
+      - id: ruff
+        name: Lint (Ruff) - AutoGPT Platform - Libs
+        alias: ruff-lint-platform-libs
+        files: ^autogpt_platform/autogpt_libs/
+        args: [--fix]
+
+      - id: ruff-format
+        name: Format (Ruff) - AutoGPT Platform - Libs
+        alias: ruff-lint-platform-libs
+        files: ^autogpt_platform/autogpt_libs/
+
+  - repo: local
+    # isort needs the context of which packages are installed to function, so we
+    # can't use a vendored isort pre-commit hook (which runs in its own isolated venv).
+    hooks:
+      - id: isort
+        name: Lint (isort) - AutoGPT Platform - Backend
+        alias: isort-platform-backend
+        entry: poetry -P autogpt_platform/backend run isort -p backend
+        files: ^autogpt_platform/backend/
+        types: [file, python]
+        language: system
+
+      - id: isort
+        name: Lint (isort) - Classic - AutoGPT
+        alias: isort-classic-autogpt
+        entry: poetry -P classic/original_autogpt run isort -p autogpt
+        files: ^classic/original_autogpt/
+        types: [file, python]
+        language: system
+
+      - id: isort
+        name: Lint (isort) - Classic - Forge
+        alias: isort-classic-forge
+        entry: poetry -P classic/forge run isort -p forge
+        files: ^classic/forge/
+        types: [file, python]
+        language: system
+
+      - id: isort
+        name: Lint (isort) - Classic - Benchmark
+        alias: isort-classic-benchmark
+        entry: poetry -P classic/benchmark run isort -p agbenchmark
+        files: ^classic/benchmark/
+        types: [file, python]
+        language: system
+
+  - repo: https://github.com/psf/black
+    rev: 24.10.0
+    # Black has sensible defaults, doesn't need package context, and ignores
+    # everything in .gitignore, so it works fine without any config or arguments.
+    hooks:
+      - id: black
+        name: Format (Black)
+
+  - repo: https://github.com/PyCQA/flake8
+    rev: 7.0.0
+    # To have flake8 load the config of the individual subprojects, we have to call
+    # them separately.
+    hooks:
+      - id: flake8
+        name: Lint (Flake8) - Classic - AutoGPT
+        alias: flake8-classic-autogpt
+        files: ^classic/original_autogpt/(autogpt|scripts|tests)/
+        args: [--config=classic/original_autogpt/.flake8]
+
+      - id: flake8
+        name: Lint (Flake8) - Classic - Forge
+        alias: flake8-classic-forge
+        files: ^classic/forge/(forge|tests)/
+        args: [--config=classic/forge/.flake8]
+
+      - id: flake8
+        name: Lint (Flake8) - Classic - Benchmark
+        alias: flake8-classic-benchmark
+        files: ^classic/benchmark/(agbenchmark|tests)/((?!reports).)*[/.]
+        args: [--config=classic/benchmark/.flake8]
+
+  - repo: local
+    hooks:
+      - id: prettier
+        name: Format (Prettier) - AutoGPT Platform - Frontend
+        alias: format-platform-frontend
+        entry: bash -c 'cd autogpt_platform/frontend && npx prettier --write $(echo "$@" | sed "s|autogpt_platform/frontend/||g")' --
+        files: ^autogpt_platform/frontend/
+        types: [file]
+        language: system
+
   - repo: local
     # For proper type checking, all dependencies need to be up-to-date.
     # It's also a good idea to check that poetry.lock is consistent with pyproject.toml.
@@ -164,7 +261,7 @@ repos:
         entry: >
           bash -c '
           cd autogpt_platform/backend
-          && poetry run export-api-schema --output ../frontend/src/app/api/openapi.json
+          && poetry run export-api-schema --api internal --output ../frontend/src/app/api/openapi.json
           && cd ../frontend
           && pnpm prettier --write ./src/app/api/openapi.json
           '
@@ -190,103 +287,6 @@ repos:
         pass_filenames: false
         stages: [pre-commit, post-checkout]
 
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.7.2
-    hooks:
-      - id: ruff
-        name: Lint (Ruff) - AutoGPT Platform - Backend
-        alias: ruff-lint-platform-backend
-        files: ^autogpt_platform/backend/
-        args: [--fix]
-
-      - id: ruff
-        name: Lint (Ruff) - AutoGPT Platform - Libs
-        alias: ruff-lint-platform-libs
-        files: ^autogpt_platform/autogpt_libs/
-        args: [--fix]
-
-      - id: ruff-format
-        name: Format (Ruff) - AutoGPT Platform - Libs
-        alias: ruff-lint-platform-libs
-        files: ^autogpt_platform/autogpt_libs/
-
-  - repo: local
-    # isort needs the context of which packages are installed to function, so we
-    # can't use a vendored isort pre-commit hook (which runs in its own isolated venv).
-    hooks:
-      - id: isort
-        name: Lint (isort) - AutoGPT Platform - Backend
-        alias: isort-platform-backend
-        entry: poetry -P autogpt_platform/backend run isort -p backend
-        files: ^autogpt_platform/backend/
-        types: [file, python]
-        language: system
-
-      - id: isort
-        name: Lint (isort) - Classic - AutoGPT
-        alias: isort-classic-autogpt
-        entry: poetry -P classic/original_autogpt run isort -p autogpt
-        files: ^classic/original_autogpt/
-        types: [file, python]
-        language: system
-
-      - id: isort
-        name: Lint (isort) - Classic - Forge
-        alias: isort-classic-forge
-        entry: poetry -P classic/forge run isort -p forge
-        files: ^classic/forge/
-        types: [file, python]
-        language: system
-
-      - id: isort
-        name: Lint (isort) - Classic - Benchmark
-        alias: isort-classic-benchmark
-        entry: poetry -P classic/benchmark run isort -p agbenchmark
-        files: ^classic/benchmark/
-        types: [file, python]
-        language: system
-
-  - repo: https://github.com/psf/black
-    rev: 24.10.0
-    # Black has sensible defaults, doesn't need package context, and ignores
-    # everything in .gitignore, so it works fine without any config or arguments.
-    hooks:
-      - id: black
-        name: Format (Black)
-
-  - repo: https://github.com/PyCQA/flake8
-    rev: 7.0.0
-    # To have flake8 load the config of the individual subprojects, we have to call
-    # them separately.
-    hooks:
-      - id: flake8
-        name: Lint (Flake8) - Classic - AutoGPT
-        alias: flake8-classic-autogpt
-        files: ^classic/original_autogpt/(autogpt|scripts|tests)/
-        args: [--config=classic/original_autogpt/.flake8]
-
-      - id: flake8
-        name: Lint (Flake8) - Classic - Forge
-        alias: flake8-classic-forge
-        files: ^classic/forge/(forge|tests)/
-        args: [--config=classic/forge/.flake8]
-
-      - id: flake8
-        name: Lint (Flake8) - Classic - Benchmark
-        alias: flake8-classic-benchmark
-        files: ^classic/benchmark/(agbenchmark|tests)/((?!reports).)*[/.]
-        args: [--config=classic/benchmark/.flake8]
-
-  - repo: local
-    hooks:
-      - id: prettier
-        name: Format (Prettier) - AutoGPT Platform - Frontend
-        alias: format-platform-frontend
-        entry: bash -c 'cd autogpt_platform/frontend && npx prettier --write $(echo "$@" | sed "s|autogpt_platform/frontend/||g")' --
-        files: ^autogpt_platform/frontend/
-        types: [file]
-        language: system
-
   - repo: local
     # To have watertight type checking, we check *all* the files in an affected
     # project. To trigger on poetry.lock we also reset the file `types` filter.

autogpt_platform/autogpt_libs/autogpt_libs/auth/__init__.py

@@ -5,7 +5,7 @@ from .dependencies import (
     requires_admin_user,
     requires_user,
 )
-from .helpers import add_auth_responses_to_openapi
+from .jwt_utils import add_auth_responses_to_openapi
 from .models import User
 
 __all__ = [

autogpt_platform/autogpt_libs/autogpt_libs/auth/helpers.py

@@ -1,9 +1,9 @@
 from fastapi import FastAPI
 
-from .jwt_utils import bearer_jwt_auth
 
-
-def add_auth_responses_to_openapi(app: FastAPI) -> None:
+def add_auth_responses_to_openapi(
+    app: FastAPI, supported_auth_schemes: list[str]
+) -> None:
     """
     Patch a FastAPI instance's `openapi()` method to add 401 responses
     to all authenticated endpoints.
@@ -29,7 +29,7 @@ def add_auth_responses_to_openapi(app: FastAPI) -> None:
                     for auth_option in details.get("security", [])
                     for schema in auth_option.keys()
                 ]
-                if bearer_jwt_auth.scheme_name not in security_schemas:
+                if not any(s in security_schemas for s in supported_auth_schemes):
                     continue
 
                 if "responses" not in details:

autogpt_platform/autogpt_libs/autogpt_libs/auth/helpers_test.py

@@ -8,8 +8,7 @@ from unittest import mock
 from fastapi import FastAPI
 from fastapi.openapi.utils import get_openapi
 
-from autogpt_libs.auth.helpers import add_auth_responses_to_openapi
-from autogpt_libs.auth.jwt_utils import bearer_jwt_auth
+from autogpt_libs.auth.jwt_utils import add_auth_responses_to_openapi, bearer_jwt_auth
 
 
 def test_add_auth_responses_to_openapi_basic():

autogpt_platform/autogpt_libs/autogpt_libs/auth/jwt_utils.py

@@ -2,7 +2,7 @@ import logging
 from typing import Any
 
 import jwt
-from fastapi import HTTPException, Security
+from fastapi import FastAPI, HTTPException, Security
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 
 from .config import get_settings
@@ -78,3 +78,12 @@ def verify_user(jwt_payload: dict | None, admin_only: bool) -> User:
         raise HTTPException(status_code=403, detail="Admin access required")
 
     return User.from_payload(jwt_payload)
+
+
+def add_auth_responses_to_openapi(app: FastAPI) -> None:
+    """
+    Add 401 responses to all endpoints that use the bearer JWT authentication scheme.
+    """
+    from .helpers import add_auth_responses_to_openapi
+
+    add_auth_responses_to_openapi(app, [bearer_jwt_auth.scheme_name])

autogpt_platform/backend/backend/api/external/fastapi_app.py

@@ -1,21 +1,57 @@
-from fastapi import FastAPI
+"""
+External API Application
+
+This module defines the main FastAPI application for the external API,
+which mounts the v1 and v2 sub-applications.
+"""
+
+from fastapi import FastAPI
+from fastapi.responses import RedirectResponse
 
-from backend.api.middleware.security import SecurityHeadersMiddleware
 from backend.monitoring.instrumentation import instrument_fastapi
 
-from .v1.routes import v1_router
+from .v1.app import v1_app
+from .v2.app import v2_app
+
+DESCRIPTION = """
+The external API provides programmatic access to the AutoGPT Platform for building
+integrations, automations, and custom applications.
+
+### API Versions
+
+| Version             | End of Life | Path                   | Documentation |
+|---------------------|-------------|------------------------|---------------|
+| **v2**              |             | `/external-api/v2/...` | [v2 docs](v2/docs) |
+| **v1** (deprecated) | 2025-05-01  | `/external-api/v1/...` | [v1 docs](v1/docs) |
+
+**Recommendation**: New integrations should use v2.
+
+For authentication details and usage examples, see the
+[API Integration Guide](https://docs.agpt.co/platform/integrating/api-guide/).
+"""
 
 external_api = FastAPI(
-    title="AutoGPT External API",
-    description="External API for AutoGPT integrations",
+    title="AutoGPT Platform API",
+    summary="External API for AutoGPT Platform integrations",
+    description=DESCRIPTION,
+    version="2.0.0",
     docs_url="/docs",
-    version="1.0",
+    redoc_url="/redoc",
 )
 
-external_api.add_middleware(SecurityHeadersMiddleware)
-external_api.include_router(v1_router, prefix="/v1")
 
-# Add Prometheus instrumentation
+@external_api.get("/", include_in_schema=False)
+async def root_redirect() -> RedirectResponse:
+    """Redirect root to API documentation."""
+    return RedirectResponse(url="/docs")
+
+
+# Mount versioned sub-applications
+# Each sub-app has its own /docs page at /v1/docs and /v2/docs
+external_api.mount("/v1", v1_app)
+external_api.mount("/v2", v2_app)
+
+# Add Prometheus instrumentation to the main app
 instrument_fastapi(
     external_api,
     service_name="external-api",

autogpt_platform/backend/backend/api/external/middleware.py

@@ -1,4 +1,4 @@
-from fastapi import HTTPException, Security, status
+from fastapi import FastAPI, HTTPException, Security, status
 from fastapi.security import APIKeyHeader, HTTPAuthorizationCredentials, HTTPBearer
 from prisma.enums import APIKeyPermission
 
@@ -96,7 +96,9 @@ def require_permission(*permissions: APIKeyPermission):
     """
 
     async def check_permissions(
-        auth: APIAuthorizationInfo = Security(require_auth),
+        auth: APIAuthorizationInfo = Security(
+            require_auth, scopes=[p.value for p in permissions]
+        ),
     ) -> APIAuthorizationInfo:
         missing = [p for p in permissions if p not in auth.scopes]
         if missing:
@@ -108,3 +110,15 @@ def require_permission(*permissions: APIKeyPermission):
         return auth
 
     return check_permissions
+
+
+def add_auth_responses_to_openapi(app: FastAPI) -> None:
+    """
+    Add 401 responses to all endpoints secured with `require_auth`,
+    `require_api_key`, or `require_access_token` middleware.
+    """
+    from autogpt_libs.auth.helpers import add_auth_responses_to_openapi
+
+    add_auth_responses_to_openapi(
+        app, [api_key_header.scheme_name, bearer_auth.scheme_name]
+    )

autogpt_platform/backend/backend/api/external/v1/app.py

@@ -0,0 +1,50 @@
+"""
+V1 External API Application
+
+This module defines the FastAPI application for the v1 external API.
+"""
+
+from fastapi import FastAPI
+
+from backend.api.external.middleware import add_auth_responses_to_openapi
+from backend.api.middleware.security import SecurityHeadersMiddleware
+from backend.api.utils.exceptions import add_exception_handlers
+from backend.api.utils.openapi import sort_openapi
+
+from .routes import v1_router
+
+DESCRIPTION = """
+The v1 API provides access to core AutoGPT functionality for external integrations.
+
+For authentication details and usage examples, see the
+[API Integration Guide](https://docs.agpt.co/platform/integrating/api-guide/).
+"""
+
+v1_app = FastAPI(
+    title="AutoGPT Platform API",
+    summary="External API for AutoGPT Platform integrations (v1)",
+    description=DESCRIPTION,
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
+    openapi_url="/openapi.json",
+    openapi_tags=[
+        {"name": "user", "description": "User information"},
+        {"name": "blocks", "description": "Block operations"},
+        {"name": "graphs", "description": "Graph execution"},
+        {"name": "store", "description": "Marketplace agents and creators"},
+        {"name": "integrations", "description": "OAuth credential management"},
+        {"name": "tools", "description": "AI assistant tools"},
+    ],
+)
+
+v1_app.add_middleware(SecurityHeadersMiddleware)
+v1_app.include_router(v1_router)
+
+# Mounted sub-apps do NOT inherit exception handlers from the parent app.
+add_exception_handlers(v1_app)
+
+# Add 401 responses to authenticated endpoints in OpenAPI spec
+add_auth_responses_to_openapi(v1_app)
+# Sort OpenAPI schema to eliminate diff on refactors
+sort_openapi(v1_app)

autogpt_platform/backend/backend/api/external/v1/routes.py

@@ -1,7 +1,7 @@
 import logging
 import urllib.parse
 from collections import defaultdict
-from typing import Annotated, Any, Literal, Optional, Sequence
+from typing import Annotated, Any, Optional, Sequence
 
 from fastapi import APIRouter, Body, HTTPException, Security
 from prisma.enums import AgentExecutionStatus, APIKeyPermission
@@ -9,9 +9,10 @@ from pydantic import BaseModel, Field
 from typing_extensions import TypedDict
 
 import backend.api.features.store.cache as store_cache
+import backend.api.features.store.db as store_db
 import backend.api.features.store.model as store_model
 import backend.blocks
-from backend.api.external.middleware import require_permission
+from backend.api.external.middleware import require_auth, require_permission
 from backend.data import execution as execution_db
 from backend.data import graph as graph_db
 from backend.data import user as user_db
@@ -230,13 +231,13 @@ async def get_graph_execution_results(
 @v1_router.get(
     path="/store/agents",
     tags=["store"],
-    dependencies=[Security(require_permission(APIKeyPermission.READ_STORE))],
+    dependencies=[Security(require_auth)],  # data is public; auth required as anti-DDoS
     response_model=store_model.StoreAgentsResponse,
 )
 async def get_store_agents(
     featured: bool = False,
     creator: str | None = None,
-    sorted_by: Literal["rating", "runs", "name", "updated_at"] | None = None,
+    sorted_by: store_db.StoreAgentsSortOptions | None = None,
     search_query: str | None = None,
     category: str | None = None,
     page: int = 1,
@@ -278,7 +279,7 @@ async def get_store_agents(
 @v1_router.get(
     path="/store/agents/{username}/{agent_name}",
     tags=["store"],
-    dependencies=[Security(require_permission(APIKeyPermission.READ_STORE))],
+    dependencies=[Security(require_auth)],  # data is public; auth required as anti-DDoS
     response_model=store_model.StoreAgentDetails,
 )
 async def get_store_agent(
@@ -306,13 +307,13 @@ async def get_store_agent(
 @v1_router.get(
     path="/store/creators",
     tags=["store"],
-    dependencies=[Security(require_permission(APIKeyPermission.READ_STORE))],
+    dependencies=[Security(require_auth)],  # data is public; auth required as anti-DDoS
     response_model=store_model.CreatorsResponse,
 )
 async def get_store_creators(
     featured: bool = False,
     search_query: str | None = None,
-    sorted_by: Literal["agent_rating", "agent_runs", "num_agents"] | None = None,
+    sorted_by: store_db.StoreCreatorsSortOptions | None = None,
     page: int = 1,
     page_size: int = 20,
 ) -> store_model.CreatorsResponse:
@@ -348,7 +349,7 @@ async def get_store_creators(
 @v1_router.get(
     path="/store/creators/{username}",
     tags=["store"],
-    dependencies=[Security(require_permission(APIKeyPermission.READ_STORE))],
+    dependencies=[Security(require_auth)],  # data is public; auth required as anti-DDoS
     response_model=store_model.CreatorDetails,
 )
 async def get_store_creator(

autogpt_platform/backend/backend/api/external/v2/__init__.py

@@ -0,0 +1,9 @@
+"""
+V2 External API
+
+This module provides the v2 external API for programmatic access to the AutoGPT Platform.
+"""
+
+from .routes import v2_router
+
+__all__ = ["v2_router"]

autogpt_platform/backend/backend/api/external/v2/app.py

@@ -0,0 +1,112 @@
+"""
+V2 External API Application
+
+This module defines the FastAPI application for the v2 external API.
+"""
+
+from fastapi import FastAPI
+
+from backend.api.external.middleware import add_auth_responses_to_openapi
+from backend.api.middleware.security import SecurityHeadersMiddleware
+from backend.api.utils.exceptions import add_exception_handlers
+from backend.api.utils.openapi import sort_openapi
+
+from .mcp_server import create_mcp_app
+from .routes import v2_router
+
+DESCRIPTION = """
+The v2 API provides comprehensive access to the AutoGPT Platform for building
+integrations, automations, and custom applications.
+
+### Key Improvements over v1
+
+- **Consistent naming**: Uses `graph_id`/`graph_version` consistently
+- **Better pagination**: All list endpoints support pagination
+- **Comprehensive coverage**: Access to library, runs, schedules, credits, and more
+- **Human-in-the-loop**: Review and approve agent decisions via the API
+
+For authentication details and usage examples, see the
+[API Integration Guide](https://docs.agpt.co/platform/integrating/api-guide/).
+
+### Pagination
+
+List endpoints return paginated responses. Use `page` and `page_size` query
+parameters to navigate results. Maximum page size is 100 items.
+""".strip()
+
+v2_app = FastAPI(
+    title="AutoGPT Platform External API",
+    summary="External API for AutoGPT Platform integrations (v2)",
+    description=DESCRIPTION,
+    version="2.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
+    openapi_url="/openapi.json",
+    openapi_tags=[
+        {
+            "name": "graphs",
+            "description": "Create, update, and manage agent graphs",
+        },
+        {
+            "name": "schedules",
+            "description": "Manage scheduled graph executions",
+        },
+        {
+            "name": "blocks",
+            "description": "Discover available building blocks",
+        },
+        {
+            "name": "search",
+            "description": "Cross-domain hybrid search across agents, blocks, and docs",
+        },
+        {
+            "name": "marketplace",
+            "description": "Browse agents and creators, manage submissions",
+        },
+        {
+            "name": "library",
+            "description": (
+                "Manage your agent library (agents and presets), "
+                "execute agents, organize with folders"
+            ),
+        },
+        {
+            "name": "presets",
+            "description": "Agent execution presets with webhook triggers",
+        },
+        {
+            "name": "runs",
+            "description": (
+                "Monitor, stop, delete, and share agent runs; "
+                "manage human-in-the-loop reviews"
+            ),
+        },
+        {
+            "name": "credits",
+            "description": "Check balance and view transaction history",
+        },
+        {
+            "name": "integrations",
+            "description": "List, create, and delete integration credentials",
+        },
+        {
+            "name": "files",
+            "description": "Upload, list, download, and delete workspace files",
+        },
+    ],
+)
+
+v2_app.add_middleware(SecurityHeadersMiddleware)
+v2_app.include_router(v2_router)
+
+# Mounted sub-apps do NOT inherit exception handlers from the parent app,
+# so we must register them here for the v2 API specifically.
+add_exception_handlers(v2_app)
+
+# Mount MCP server (Copilot tools via Streamable HTTP)
+v2_app.mount("/mcp", create_mcp_app())
+
+# Add 401 responses to authenticated endpoints in OpenAPI spec
+add_auth_responses_to_openapi(v2_app)
+# Sort OpenAPI schema to eliminate diff on refactors
+sort_openapi(v2_app)

autogpt_platform/backend/backend/api/external/v2/app_test.py

@@ -0,0 +1,276 @@
+"""
+Tests for v2 API error handling behavior.
+
+The v2 app registers its own exception handlers (since mounted sub-apps don't
+inherit handlers from the parent app). These tests verify that exceptions from
+the DB/service layer are correctly mapped to HTTP status codes.
+
+We construct a lightweight test app rather than importing the full v2_app,
+because the latter eagerly loads the MCP server, block registry, and other
+heavy dependencies that are irrelevant for error handling tests.
+"""
+
+import json
+from datetime import datetime, timezone
+from unittest.mock import AsyncMock
+
+import fastapi
+import fastapi.testclient
+import pytest
+import pytest_mock
+from prisma.enums import APIKeyPermission
+from pytest_snapshot.plugin import Snapshot
+
+from backend.api.external.middleware import require_auth
+from backend.api.utils.exceptions import add_exception_handlers
+from backend.data.auth.base import APIAuthorizationInfo
+from backend.util.exceptions import DatabaseError, NotFoundError
+
+from .library.agents import agents_router
+from .marketplace import marketplace_router
+
+TEST_USER_ID = "test-user-id"
+
+_mock_auth = APIAuthorizationInfo(
+    user_id=TEST_USER_ID,
+    scopes=list(APIKeyPermission),
+    type="api_key",
+    created_at=datetime.now(tz=timezone.utc),
+)
+
+# ---------------------------------------------------------------------------
+# Build a lightweight test app with the shared exception handlers
+# but only the routers we need for testing.
+# ---------------------------------------------------------------------------
+
+app = fastapi.FastAPI()
+app.include_router(agents_router, prefix="/library")
+app.include_router(marketplace_router, prefix="/marketplace")
+add_exception_handlers(app)
+
+
+@pytest.fixture(autouse=True)
+def _override_auth():
+    """Bypass API key / OAuth auth for all tests in this module."""
+
+    async def fake_auth() -> APIAuthorizationInfo:
+        return _mock_auth
+
+    app.dependency_overrides[require_auth] = fake_auth
+    yield
+    app.dependency_overrides.clear()
+
+
+client = fastapi.testclient.TestClient(app, raise_server_exceptions=False)
+
+
+# ============================================================================
+# NotFoundError → 404
+# ============================================================================
+
+
+def test_not_found_error_returns_404(
+    mocker: pytest_mock.MockFixture,
+    snapshot: Snapshot,
+) -> None:
+    """NotFoundError raised by the DB layer should become a 404 response."""
+    mocker.patch(
+        "backend.api.features.library.db.get_library_agent",
+        new_callable=AsyncMock,
+        side_effect=NotFoundError("Agent #nonexistent not found"),
+    )
+
+    response = client.get("/library/agents/nonexistent")
+
+    assert response.status_code == 404
+    body = response.json()
+    assert body["detail"] == "Agent #nonexistent not found"
+    assert "message" in body
+    assert body["hint"] == "Adjust the request and retry."
+
+    snapshot.snapshot_dir = "snapshots"
+    snapshot.assert_match(
+        json.dumps(body, indent=2, sort_keys=True),
+        "v2_not_found_error_404",
+    )
+
+
+def test_not_found_error_on_delete_returns_404(
+    mocker: pytest_mock.MockFixture,
+) -> None:
+    """NotFoundError on DELETE should return 404, not 204 or 500."""
+    mocker.patch(
+        "backend.api.features.library.db.delete_library_agent",
+        new_callable=AsyncMock,
+        side_effect=NotFoundError("Agent #gone not found"),
+    )
+
+    response = client.delete("/library/agents/gone")
+
+    assert response.status_code == 404
+    assert response.json()["detail"] == "Agent #gone not found"
+    assert "message" in response.json()
+
+
+def test_not_found_error_on_marketplace_returns_404(
+    mocker: pytest_mock.MockFixture,
+) -> None:
+    """NotFoundError from store DB layer should become a 404."""
+    mocker.patch(
+        "backend.api.features.store.db.get_store_agent_by_version_id",
+        new_callable=AsyncMock,
+        side_effect=NotFoundError("Store listing not found"),
+    )
+
+    response = client.get("/marketplace/agents/by-version/nonexistent")
+
+    assert response.status_code == 404
+    assert response.json()["detail"] == "Store listing not found"
+    assert "message" in response.json()
+
+
+# ============================================================================
+# ValueError → 400
+# ============================================================================
+
+
+def test_value_error_returns_400(
+    mocker: pytest_mock.MockFixture,
+    snapshot: Snapshot,
+) -> None:
+    """ValueError raised by the service layer should become a 400 response."""
+    mocker.patch(
+        "backend.api.features.library.db.update_library_agent",
+        new_callable=AsyncMock,
+        side_effect=ValueError("Invalid graph version: -1"),
+    )
+
+    response = client.patch(
+        "/library/agents/some-id",
+        json={"graph_version": -1},
+    )
+
+    assert response.status_code == 400
+    body = response.json()
+    assert body["detail"] == "Invalid graph version: -1"
+    assert "message" in body
+    assert body["hint"] == "Adjust the request and retry."
+
+    snapshot.snapshot_dir = "snapshots"
+    snapshot.assert_match(
+        json.dumps(body, indent=2, sort_keys=True),
+        "v2_value_error_400",
+    )
+
+
+# ============================================================================
+# NotFoundError is a ValueError subclass — verify specificity wins
+# ============================================================================
+
+
+def test_not_found_error_takes_precedence_over_value_error(
+    mocker: pytest_mock.MockFixture,
+) -> None:
+    """
+    NotFoundError(ValueError) should match the NotFoundError handler (404),
+    not the ValueError handler (400).
+    """
+    mocker.patch(
+        "backend.api.features.library.db.get_library_agent",
+        new_callable=AsyncMock,
+        side_effect=NotFoundError("Specific not found"),
+    )
+
+    response = client.get("/library/agents/test-id")
+
+    # Must be 404, not 400
+    assert response.status_code == 404
+
+
+# ============================================================================
+# Unhandled Exception → 500
+# ============================================================================
+
+
+def test_unhandled_exception_returns_500(
+    mocker: pytest_mock.MockFixture,
+    snapshot: Snapshot,
+) -> None:
+    """
+    Unexpected exceptions should return a generic 500 without leaking
+    internal details.
+    """
+    mocker.patch(
+        "backend.api.features.library.db.get_library_agent",
+        new_callable=AsyncMock,
+        side_effect=DatabaseError("connection refused"),
+    )
+
+    response = client.get("/library/agents/some-id")
+
+    assert response.status_code == 500
+    body = response.json()
+    assert "message" in body
+    assert "detail" in body
+    assert body["hint"] == "Check server logs and dependent services."
+
+    snapshot.snapshot_dir = "snapshots"
+    snapshot.assert_match(
+        json.dumps(body, indent=2, sort_keys=True),
+        "v2_unhandled_exception_500",
+    )
+
+
+def test_runtime_error_returns_500(
+    mocker: pytest_mock.MockFixture,
+) -> None:
+    """RuntimeError (not ValueError) should hit the catch-all 500 handler."""
+    mocker.patch(
+        "backend.api.features.library.db.delete_library_agent",
+        new_callable=AsyncMock,
+        side_effect=RuntimeError("something broke"),
+    )
+
+    response = client.delete("/library/agents/some-id")
+
+    assert response.status_code == 500
+    assert "detail" in response.json()
+    assert response.json()["hint"] == "Check server logs and dependent services."
+
+
+# ============================================================================
+# Response format consistency
+# ============================================================================
+
+
+def test_all_error_responses_have_consistent_format(
+    mocker: pytest_mock.MockFixture,
+) -> None:
+    """All error responses should use {"message": ..., "detail": ..., "hint": ...} format."""
+    cases = [
+        (NotFoundError("not found"), 404),
+        (ValueError("bad value"), 400),
+        (RuntimeError("boom"), 500),
+    ]
+
+    for exc, expected_status in cases:
+        mocker.patch(
+            "backend.api.features.library.db.get_library_agent",
+            new_callable=AsyncMock,
+            side_effect=exc,
+        )
+
+        response = client.get("/library/agents/test-id")
+
+        assert response.status_code == expected_status, (
+            f"Expected {expected_status} for {type(exc).__name__}, "
+            f"got {response.status_code}"
+        )
+        body = response.json()
+        assert (
+            "message" in body
+        ), f"Missing 'message' key for {type(exc).__name__}: {body}"
+        assert (
+            "detail" in body
+        ), f"Missing 'detail' key for {type(exc).__name__}: {body}"
+        assert "hint" in body, f"Missing 'hint' key for {type(exc).__name__}: {body}"

autogpt_platform/backend/backend/api/external/v2/blocks.py

@@ -0,0 +1,68 @@
+"""
+V2 External API - Blocks Endpoints
+
+Provides read-only access to available building blocks.
+"""
+
+import logging
+
+from fastapi import APIRouter, Security
+from fastapi.concurrency import run_in_threadpool
+from prisma.enums import APIKeyPermission
+
+from backend.api.external.middleware import require_permission
+from backend.blocks import get_blocks
+from backend.data.auth.base import APIAuthorizationInfo
+from backend.util.cache import cached
+
+from .models import BlockInfo
+
+logger = logging.getLogger(__name__)
+
+blocks_router = APIRouter(tags=["blocks"])
+
+
+# ============================================================================
+# Internal Functions
+# ============================================================================
+
+
+def _compute_blocks_sync() -> list[BlockInfo]:
+    """
+    Synchronous function to compute blocks data.
+    This does the heavy lifting: instantiate 226+ blocks, compute costs, serialize.
+    """
+    return [
+        BlockInfo.from_internal(block)
+        for block_class in get_blocks().values()
+        if not (block := block_class()).disabled
+    ]
+
+
+@cached(ttl_seconds=3600)
+async def _get_cached_blocks() -> list[BlockInfo]:
+    """
+    Async cached function with thundering herd protection.
+    On cache miss: runs heavy work in thread pool
+    On cache hit: returns cached list immediately
+    """
+    return await run_in_threadpool(_compute_blocks_sync)
+
+
+# ============================================================================
+# Endpoints
+# ============================================================================
+
+
+@blocks_router.get(
+    path="",
+    summary="List available blocks",
+    operation_id="listAvailableBlocks",
+)
+async def list_available_blocks(
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_BLOCK)
+    ),
+) -> list[BlockInfo]:
+    """List all available blocks with their input/output schemas and cost information."""
+    return await _get_cached_blocks()

autogpt_platform/backend/backend/api/external/v2/common.py

@@ -0,0 +1,7 @@
+"""
+Common utilities for V2 External API
+"""
+
+# Constants for pagination
+MAX_PAGE_SIZE = 100
+DEFAULT_PAGE_SIZE = 20

autogpt_platform/backend/backend/api/external/v2/credits.py

@@ -0,0 +1,90 @@
+"""
+V2 External API - Credits Endpoints
+
+Provides access to credit balance and transaction history.
+"""
+
+import logging
+from typing import Optional
+
+from fastapi import APIRouter, Query, Security
+from prisma.enums import APIKeyPermission
+
+from backend.api.external.middleware import require_permission
+from backend.data.auth.base import APIAuthorizationInfo
+from backend.data.credit import get_user_credit_model
+
+from .common import DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE
+from .models import CreditBalance, CreditTransaction, CreditTransactionsResponse
+
+logger = logging.getLogger(__name__)
+
+credits_router = APIRouter(tags=["credits"])
+
+
+# ============================================================================
+# Endpoints
+# ============================================================================
+
+
+@credits_router.get(
+    path="",
+    summary="Get credit balance",
+    operation_id="getCreditBalance",
+)
+async def get_balance(
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_CREDITS)
+    ),
+) -> CreditBalance:
+    """Get the current credit balance for the authenticated user."""
+    user_credit_model = await get_user_credit_model(auth.user_id)
+    balance = await user_credit_model.get_credits(auth.user_id)
+
+    return CreditBalance(balance=balance)
+
+
+@credits_router.get(
+    path="/transactions",
+    summary="Get credit transaction history",
+    operation_id="listCreditTransactions",
+)
+async def get_transactions(
+    page: int = Query(default=1, ge=1, description="Page number (1-indexed)"),
+    page_size: int = Query(
+        default=DEFAULT_PAGE_SIZE,
+        ge=1,
+        le=MAX_PAGE_SIZE,
+        description=f"Items per page (max {MAX_PAGE_SIZE})",
+    ),
+    transaction_type: Optional[str] = Query(
+        default=None,
+        description="Filter by transaction type (TOP_UP, USAGE, GRANT, REFUND)",
+    ),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_CREDITS)
+    ),
+) -> CreditTransactionsResponse:
+    """Get credit transaction history for the authenticated user."""
+    user_credit_model = await get_user_credit_model(auth.user_id)
+
+    history = await user_credit_model.get_transaction_history(
+        user_id=auth.user_id,
+        transaction_count_limit=page_size,
+        transaction_type=transaction_type,
+    )
+
+    transactions = [CreditTransaction.from_internal(t) for t in history.transactions]
+
+    # Note: The current credit module doesn't support true pagination,
+    # so we're returning what we have
+    total_count = len(transactions)
+    total_pages = 1  # Without true pagination support
+
+    return CreditTransactionsResponse(
+        transactions=transactions,
+        page=page,
+        page_size=page_size,
+        total_count=total_count,
+        total_pages=total_pages,
+    )

autogpt_platform/backend/backend/api/external/v2/files.py

@@ -0,0 +1,341 @@
+"""
+V2 External API - Files Endpoints
+
+Provides file upload, download, listing, metadata, and deletion functionality.
+"""
+
+import base64
+import logging
+import re
+from urllib.parse import quote
+
+from fastapi import APIRouter, File, HTTPException, Query, Security, UploadFile
+from fastapi.responses import RedirectResponse, Response
+from prisma.enums import APIKeyPermission
+from starlette import status
+
+from backend.api.external.middleware import require_permission
+from backend.data.auth.base import APIAuthorizationInfo
+from backend.data.workspace import (
+    count_workspace_files,
+    get_workspace,
+    get_workspace_file,
+    list_workspace_files,
+    soft_delete_workspace_file,
+)
+from backend.util.cloud_storage import get_cloud_storage_handler
+from backend.util.settings import Settings
+from backend.util.virus_scanner import scan_content_safe
+from backend.util.workspace_storage import get_workspace_storage
+
+from .common import DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE
+from .models import (
+    UploadWorkspaceFileResponse,
+    WorkspaceFileInfo,
+    WorkspaceFileListResponse,
+)
+from .rate_limit import file_upload_limiter
+
+logger = logging.getLogger(__name__)
+settings = Settings()
+
+file_workspace_router = APIRouter(tags=["files"])
+
+
+# ============================================================================
+# Endpoints
+# ============================================================================
+
+
+@file_workspace_router.get(
+    path="",
+    summary="List workspace files",
+    operation_id="listWorkspaceFiles",
+)
+async def list_files(
+    page: int = Query(default=1, ge=1, description="Page number (1-indexed)"),
+    page_size: int = Query(
+        default=DEFAULT_PAGE_SIZE,
+        ge=1,
+        le=MAX_PAGE_SIZE,
+        description=f"Items per page (max {MAX_PAGE_SIZE})",
+    ),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_FILES)
+    ),
+) -> WorkspaceFileListResponse:
+    """List files in the user's workspace."""
+    workspace = await get_workspace(auth.user_id)
+    if workspace is None:
+        return WorkspaceFileListResponse(
+            files=[], page=page, page_size=page_size, total_count=0, total_pages=0
+        )
+
+    total_count = await count_workspace_files(workspace.id)
+    total_pages = (total_count + page_size - 1) // page_size if total_count > 0 else 0
+    offset = (page - 1) * page_size
+
+    files = await list_workspace_files(
+        workspace_id=workspace.id,
+        limit=page_size,
+        offset=offset,
+    )
+
+    return WorkspaceFileListResponse(
+        files=[
+            WorkspaceFileInfo(
+                id=f.id,
+                name=f.name,
+                path=f.path,
+                mime_type=f.mime_type,
+                size_bytes=f.size_bytes,
+                created_at=f.created_at,
+                updated_at=f.updated_at,
+            )
+            for f in files
+        ],
+        page=page,
+        page_size=page_size,
+        total_count=total_count,
+        total_pages=total_pages,
+    )
+
+
+@file_workspace_router.get(
+    path="/{file_id}",
+    summary="Get workspace file metadata",
+    operation_id="getWorkspaceFileInfo",
+)
+async def get_file(
+    file_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_FILES)
+    ),
+) -> WorkspaceFileInfo:
+    """Get metadata for a specific file in the user's workspace."""
+    workspace = await get_workspace(auth.user_id)
+    if workspace is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Workspace not found",
+        )
+
+    file = await get_workspace_file(file_id, workspace.id)
+    if file is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"File #{file_id} not found",
+        )
+
+    return WorkspaceFileInfo(
+        id=file.id,
+        name=file.name,
+        path=file.path,
+        mime_type=file.mime_type,
+        size_bytes=file.size_bytes,
+        created_at=file.created_at,
+        updated_at=file.updated_at,
+    )
+
+
+@file_workspace_router.delete(
+    path="/{file_id}",
+    summary="Delete file from workspace",
+    operation_id="deleteWorkspaceFile",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def delete_file(
+    file_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_FILES)
+    ),
+) -> None:
+    """Soft-delete a file from the user's workspace."""
+    workspace = await get_workspace(auth.user_id)
+    if workspace is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Workspace not found",
+        )
+
+    result = await soft_delete_workspace_file(file_id, workspace.id)
+    if result is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"File #{file_id} not found",
+        )
+
+
+def _create_file_size_error(size_bytes: int, max_size_mb: int) -> HTTPException:
+    """Create standardized file size error response."""
+    return HTTPException(
+        status_code=status.HTTP_400_BAD_REQUEST,
+        detail=(
+            f"File size ({size_bytes} bytes) exceeds "
+            f"the maximum allowed size of {max_size_mb}MB"
+        ),
+    )
+
+
+@file_workspace_router.post(
+    path="/upload",
+    summary="Upload file to workspace",
+    operation_id="uploadWorkspaceFile",
+)
+async def upload_file(
+    file: UploadFile = File(...),
+    expiration_hours: int = Query(
+        default=24, ge=1, le=48, description="Hours until file expires (1-48)"
+    ),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_FILES)
+    ),
+) -> UploadWorkspaceFileResponse:
+    """
+    Upload a file to cloud storage for use with agents.
+
+    Returns a `file_uri` that can be passed to agent graph/node file inputs.
+    Uploaded files are virus-scanned before storage.
+    """
+    file_upload_limiter.check(auth.user_id)
+
+    # Check file size limit
+    max_size_mb = settings.config.upload_file_size_limit_mb
+    max_size_bytes = max_size_mb * 1024 * 1024
+
+    # Try to get file size from headers first
+    if hasattr(file, "size") and file.size is not None and file.size > max_size_bytes:
+        raise _create_file_size_error(file.size, max_size_mb)
+
+    # Read file content
+    content = await file.read()
+    content_size = len(content)
+
+    # Double-check file size after reading
+    if content_size > max_size_bytes:
+        raise _create_file_size_error(content_size, max_size_mb)
+
+    # Extract file info
+    file_name = file.filename or "uploaded_file"
+    content_type = file.content_type or "application/octet-stream"
+
+    # Virus scan the content
+    await scan_content_safe(content, filename=file_name)
+
+    # Check if cloud storage is configured
+    cloud_storage = await get_cloud_storage_handler()
+    if not cloud_storage.config.gcs_bucket_name:
+        # Fallback to base64 data URI when GCS is not configured
+        base64_content = base64.b64encode(content).decode("utf-8")
+        data_uri = f"data:{content_type};base64,{base64_content}"
+
+        return UploadWorkspaceFileResponse(
+            file_uri=data_uri,
+            file_name=file_name,
+            size=content_size,
+            content_type=content_type,
+            expires_in_hours=expiration_hours,
+        )
+
+    # Store in cloud storage
+    storage_path = await cloud_storage.store_file(
+        content=content,
+        filename=file_name,
+        expiration_hours=expiration_hours,
+        user_id=auth.user_id,
+    )
+
+    return UploadWorkspaceFileResponse(
+        file_uri=storage_path,
+        file_name=file_name,
+        size=content_size,
+        content_type=content_type,
+        expires_in_hours=expiration_hours,
+    )
+
+
+# ============================================================================
+# Endpoints - Download
+# ============================================================================
+
+
+def _sanitize_filename_for_header(filename: str) -> str:
+    """Sanitize filename for Content-Disposition header."""
+    sanitized = re.sub(r"[\r\n\x00]", "", filename)
+    sanitized = sanitized.replace('"', '\\"')
+    try:
+        sanitized.encode("ascii")
+        return f'attachment; filename="{sanitized}"'
+    except UnicodeEncodeError:
+        encoded = quote(sanitized, safe="")
+        return f"attachment; filename*=UTF-8''{encoded}"
+
+
+@file_workspace_router.get(
+    path="/{file_id}/download",
+    summary="Download file from workspace",
+    operation_id="getWorkspaceFileDownload",
+)
+async def download_file(
+    file_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_FILES)
+    ),
+) -> Response:
+    """Download a file from the user's workspace."""
+    workspace = await get_workspace(auth.user_id)
+    if workspace is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Workspace not found",
+        )
+
+    file = await get_workspace_file(file_id, workspace.id)
+    if file is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"File #{file_id} not found",
+        )
+
+    storage = await get_workspace_storage()
+
+    # For local storage, stream directly
+    if file.storage_path.startswith("local://"):
+        content = await storage.retrieve(file.storage_path)
+        return Response(
+            content=content,
+            media_type=file.mime_type,
+            headers={
+                "Content-Disposition": _sanitize_filename_for_header(file.name),
+                "Content-Length": str(len(content)),
+            },
+        )
+
+    # For cloud storage, try signed URL redirect, fall back to streaming
+    try:
+        url = await storage.get_download_url(file.storage_path, expires_in=300)
+        if url.startswith("/api/"):
+            content = await storage.retrieve(file.storage_path)
+            return Response(
+                content=content,
+                media_type=file.mime_type,
+                headers={
+                    "Content-Disposition": _sanitize_filename_for_header(file.name),
+                    "Content-Length": str(len(content)),
+                },
+            )
+        return RedirectResponse(url=url, status_code=302)
+    except Exception:
+        logger.error(
+            f"Failed to get download URL for file {file.id}, falling back to stream",
+            exc_info=True,
+        )
+        content = await storage.retrieve(file.storage_path)
+        return Response(
+            content=content,
+            media_type=file.mime_type,
+            headers={
+                "Content-Disposition": _sanitize_filename_for_header(file.name),
+                "Content-Length": str(len(content)),
+            },
+        )

autogpt_platform/backend/backend/api/external/v2/graphs.py

@@ -0,0 +1,458 @@
+"""
+V2 External API - Graphs Endpoints
+
+Provides endpoints for managing agent graphs (CRUD operations).
+"""
+
+import logging
+from typing import Optional
+from uuid import uuid4
+
+from fastapi import APIRouter, HTTPException, Query, Security
+from prisma.enums import APIKeyPermission
+from starlette import status
+
+from backend.api.external.middleware import require_permission
+from backend.api.features.library import db as library_db
+from backend.data import graph as graph_db
+from backend.data.auth.base import APIAuthorizationInfo
+from backend.integrations.webhooks.graph_lifecycle_hooks import (
+    on_graph_activate,
+    on_graph_deactivate,
+)
+
+from .common import DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE
+from .integrations.helpers import get_credential_requirements
+from .models import (
+    BlockInfo,
+    CredentialRequirementsResponse,
+    Graph,
+    GraphCreateRequest,
+    GraphListResponse,
+    GraphMeta,
+    GraphSetActiveVersionRequest,
+    GraphSettings,
+    LibraryAgent,
+    MarketplaceAgentDetails,
+)
+
+logger = logging.getLogger(__name__)
+
+graphs_router = APIRouter(tags=["graphs"])
+
+
+@graphs_router.get(
+    path="",
+    summary="List graphs",
+    operation_id="listGraphs",
+)
+async def list_graphs(
+    page: int = Query(default=1, ge=1, description="Page number (1-indexed)"),
+    page_size: int = Query(
+        default=DEFAULT_PAGE_SIZE,
+        ge=1,
+        le=MAX_PAGE_SIZE,
+        description=f"Items per page (max {MAX_PAGE_SIZE})",
+    ),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_GRAPH)
+    ),
+) -> GraphListResponse:
+    """List all graphs owned by the authenticated user."""
+    graphs, pagination_info = await graph_db.list_graphs_paginated(
+        user_id=auth.user_id,
+        page=page,
+        page_size=page_size,
+        filter_by="active",
+    )
+    return GraphListResponse(
+        graphs=[GraphMeta.from_internal(g) for g in graphs],
+        page=pagination_info.current_page,
+        page_size=pagination_info.page_size,
+        total_count=pagination_info.total_items,
+        total_pages=pagination_info.total_pages,
+    )
+
+
+@graphs_router.get(
+    path="/{graph_id}",
+    summary="Get graph details",
+    operation_id="getGraphDetails",
+)
+async def get_graph(
+    graph_id: str,
+    version: Optional[int] = Query(
+        default=None,
+        description="Specific version to retrieve (default: active version)",
+    ),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_GRAPH)
+    ),
+) -> Graph:
+    """
+    Get detailed information about a specific graph.
+
+    Returns the active version by default. Pass `version` to retrieve
+    a specific version instead.
+    """
+    graph = await graph_db.get_graph(
+        graph_id,
+        version,
+        user_id=auth.user_id,
+        include_subgraphs=True,
+    )
+    if not graph:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Graph #{graph_id} not found.",
+        )
+    return Graph.from_internal(graph)
+
+
+@graphs_router.post(
+    path="",
+    summary="Create graph",
+    operation_id="createGraph",
+)
+async def create_graph(
+    create_graph: GraphCreateRequest,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_GRAPH)
+    ),
+) -> Graph:
+    """Create a new agent graph."""
+    from backend.api.features.library import db as library_db
+
+    internal_graph = create_graph.to_internal(id=str(uuid4()), version=1)
+
+    graph = graph_db.make_graph_model(internal_graph, auth.user_id)
+    graph.reassign_ids(user_id=auth.user_id, reassign_graph_id=True)
+    graph.validate_graph(for_run=False)
+
+    await graph_db.create_graph(graph, user_id=auth.user_id)
+    await library_db.create_library_agent(graph, user_id=auth.user_id)
+    activated_graph = await on_graph_activate(graph, user_id=auth.user_id)
+
+    return Graph.from_internal(activated_graph)
+
+
+@graphs_router.put(
+    path="/{graph_id}",
+    summary="Update graph by creating a new version",
+    operation_id="updateGraphCreateVersion",
+)
+async def update_graph(
+    graph_id: str,
+    update_graph: GraphCreateRequest,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_GRAPH)
+    ),
+) -> Graph:
+    """
+    Update a graph by creating a new version.
+
+    This does not modify existing versions; it creates a new version
+    with the provided graph definition.
+    """
+    from backend.api.features.library import db as library_db
+
+    existing_versions = await graph_db.get_graph_all_versions(
+        graph_id, user_id=auth.user_id
+    )
+    if not existing_versions:
+        raise HTTPException(
+            status.HTTP_404_NOT_FOUND, detail=f"Graph #{graph_id} not found"
+        )
+
+    latest_version_number = max(g.version for g in existing_versions)
+
+    internal_graph = update_graph.to_internal(
+        id=graph_id, version=latest_version_number + 1
+    )
+
+    current_active_version = next((v for v in existing_versions if v.is_active), None)
+    graph = graph_db.make_graph_model(internal_graph, auth.user_id)
+    graph.reassign_ids(user_id=auth.user_id, reassign_graph_id=False)
+    graph.validate_graph(for_run=False)
+
+    new_graph_version = await graph_db.create_graph(graph, user_id=auth.user_id)
+
+    if new_graph_version.is_active:
+        await library_db.update_agent_version_in_library(
+            auth.user_id, new_graph_version.id, new_graph_version.version
+        )
+        new_graph_version = await on_graph_activate(
+            new_graph_version, user_id=auth.user_id
+        )
+        await graph_db.set_graph_active_version(
+            graph_id=graph_id, version=new_graph_version.version, user_id=auth.user_id
+        )
+        if current_active_version:
+            await on_graph_deactivate(current_active_version, user_id=auth.user_id)
+
+    new_graph_version_with_subgraphs = await graph_db.get_graph(
+        graph_id,
+        new_graph_version.version,
+        user_id=auth.user_id,
+        include_subgraphs=True,
+    )
+    assert new_graph_version_with_subgraphs
+    return Graph.from_internal(new_graph_version_with_subgraphs)
+
+
+# NOTE: we don't expose graph deletion in the UI, so this is commented for now
+# @graphs_router.delete(
+#     path="/{graph_id}",
+#     summary="Delete graph permanently",
+#     status_code=status.HTTP_204_NO_CONTENT,
+# )
+# async def delete_graph(
+#     graph_id: str,
+#     auth: APIAuthorizationInfo = Security(
+#         require_permission(APIKeyPermission.WRITE_GRAPH)
+#     ),
+# ) -> None:
+#     """
+#     Permanently delete a graph and all its versions.
+
+#     This action cannot be undone. All associated executions will remain
+#     but will reference a deleted graph.
+#     """
+#     if active_version := await graph_db.get_graph(
+#         graph_id=graph_id, version=None, user_id=auth.user_id
+#     ):
+#         await on_graph_deactivate(active_version, user_id=auth.user_id)
+
+#     # FIXME: maybe only expose delete for library agents?
+#     deleted_count = await graph_db.delete_graph(graph_id, user_id=auth.user_id)
+#     if deleted_count == 0:
+#         raise HTTPException(
+#             status_code=status.HTTP_404_NOT_FOUND, detail=f"Graph {graph_id} not found"
+#         )
+
+
+@graphs_router.get(
+    path="/{graph_id}/versions",
+    summary="List graph versions",
+    operation_id="listGraphVersions",
+)
+async def list_graph_versions(
+    graph_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_GRAPH)
+    ),
+) -> list[Graph]:
+    """Get all versions of a specific graph."""
+    graphs = await graph_db.get_graph_all_versions(graph_id, user_id=auth.user_id)
+    if not graphs:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Graph #{graph_id} not found.",
+        )
+    return [Graph.from_internal(g) for g in graphs]
+
+
+@graphs_router.put(
+    path="/{graph_id}/versions/active",
+    summary="Set active graph version",
+    operation_id="updateGraphSetActiveVersion",
+)
+async def set_active_version(
+    graph_id: str,
+    request_body: GraphSetActiveVersionRequest,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_GRAPH)
+    ),
+) -> None:
+    """
+    Set which version of a graph is the active version.
+
+    The active version is the one used when executing the graph
+    and what is shown to users in the UI.
+    """
+    from backend.api.features.library import db as library_db
+
+    new_active_version = request_body.active_graph_version
+    new_active_graph = await graph_db.get_graph(
+        graph_id, new_active_version, user_id=auth.user_id
+    )
+    if not new_active_graph:
+        raise HTTPException(
+            status.HTTP_404_NOT_FOUND,
+            f"Graph #{graph_id} v{new_active_version} not found",
+        )
+
+    current_active_graph = await graph_db.get_graph(
+        graph_id=graph_id,
+        version=None,
+        user_id=auth.user_id,
+    )
+
+    await on_graph_activate(new_active_graph, user_id=auth.user_id)
+    await graph_db.set_graph_active_version(
+        graph_id=graph_id,
+        version=new_active_version,
+        user_id=auth.user_id,
+    )
+
+    await library_db.update_agent_version_in_library(
+        auth.user_id, new_active_graph.id, new_active_graph.version
+    )
+
+    if current_active_graph and current_active_graph.version != new_active_version:
+        await on_graph_deactivate(current_active_graph, user_id=auth.user_id)
+
+
+@graphs_router.patch(
+    path="/{graph_id}/settings",
+    summary="Update graph settings",
+    operation_id="updateGraphSettings",
+)
+async def update_graph_settings(
+    graph_id: str,
+    settings: GraphSettings,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_GRAPH)
+    ),
+) -> GraphSettings:
+    """Update settings for a graph."""
+    from backend.api.features.library import db as library_db
+
+    library_agent = await library_db.get_library_agent_by_graph_id(
+        graph_id=graph_id, user_id=auth.user_id
+    )
+    if not library_agent:
+        raise HTTPException(
+            status.HTTP_404_NOT_FOUND, f"Graph #{graph_id} not found in user's library"
+        )
+
+    updated_agent = await library_db.update_library_agent(
+        user_id=auth.user_id,
+        library_agent_id=library_agent.id,
+        settings=settings.to_internal(),
+    )
+
+    return GraphSettings(
+        human_in_the_loop_safe_mode=updated_agent.settings.human_in_the_loop_safe_mode
+    )
+
+
+@graphs_router.get(
+    path="/{graph_id}/library-agent",
+    summary="Get library agent for graph",
+    operation_id="getLibraryAgentForGraph",
+)
+async def get_library_agent_by_graph(
+    graph_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_LIBRARY)
+    ),
+) -> LibraryAgent:
+    """Get the library agent associated with a specific graph."""
+    agent = await library_db.get_library_agent_by_graph_id(
+        graph_id=graph_id,
+        user_id=auth.user_id,
+    )
+    if not agent:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"No library agent found for graph #{graph_id}",
+        )
+    return LibraryAgent.from_internal(agent)
+
+
+@graphs_router.get(
+    path="/{graph_id}/blocks",
+    summary="List blocks used in a graph",
+    operation_id="listBlocksInGraph",
+)
+async def list_graph_blocks(
+    graph_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_GRAPH)
+    ),
+) -> list[BlockInfo]:
+    """List the unique blocks used by a graph."""
+    from backend.blocks import get_block
+
+    graph = await graph_db.get_graph(
+        graph_id,
+        version=None,
+        user_id=auth.user_id,
+        include_subgraphs=True,
+    )
+    if not graph:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Graph #{graph_id} not found.",
+        )
+
+    seen_block_ids: set[str] = set()
+    blocks: list[BlockInfo] = []
+
+    for node in graph.nodes:
+        if node.block_id in seen_block_ids:
+            continue
+        seen_block_ids.add(node.block_id)
+
+        block = get_block(node.block_id)
+        if block and not block.disabled:
+            blocks.append(BlockInfo.from_internal(block))
+
+    return blocks
+
+
+@graphs_router.get(
+    path="/{graph_id}/credentials",
+    summary="Get graph credentials",
+    operation_id="getCredentialRequirementsForGraph",
+)
+async def list_graph_credential_requirements(
+    graph_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_INTEGRATIONS)
+    ),
+) -> CredentialRequirementsResponse:
+    """List credential requirements for a graph and matching user credentials."""
+    graph = await graph_db.get_graph(
+        graph_id=graph_id,
+        version=None,
+        user_id=auth.user_id,
+        include_subgraphs=True,
+    )
+    if not graph:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail=f"Graph #{graph_id} not found"
+        )
+
+    requirements = await get_credential_requirements(
+        graph.credentials_input_schema, auth.user_id
+    )
+    return CredentialRequirementsResponse(requirements=requirements)
+
+
+@graphs_router.get(
+    path="/{graph_id}/marketplace-listing",
+    summary="Get marketplace listing for graph",
+    operation_id="getMarketplaceListingForGraph",
+)
+async def get_marketplace_listing_for_graph(
+    graph_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_STORE)
+    ),
+) -> MarketplaceAgentDetails:
+    """Get the marketplace listing for a given graph, if one exists."""
+    import prisma.models
+
+    from backend.api.features.store.model import StoreAgentDetails
+
+    agent = await prisma.models.StoreAgent.prisma().find_first(
+        where={"graph_id": graph_id}
+    )
+    if not agent:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"No marketplace listing found for graph {graph_id}",
+        )
+    return MarketplaceAgentDetails.from_internal(StoreAgentDetails.from_db(agent))

autogpt_platform/backend/backend/api/external/v2/integrations/__init__.py

@@ -0,0 +1,13 @@
+"""
+V2 External API - Integrations Package
+
+Aggregates all integration-related sub-routers.
+"""
+
+from fastapi import APIRouter
+
+from .credentials import credentials_router
+
+integrations_router = APIRouter(tags=["integrations"])
+
+integrations_router.include_router(credentials_router)

autogpt_platform/backend/backend/api/external/v2/integrations/credentials.py

@@ -0,0 +1,131 @@
+"""
+V2 External API - Credential CRUD Endpoints
+
+Provides endpoints for managing integration credentials.
+"""
+
+import logging
+from typing import Annotated, Optional
+from uuid import uuid4
+
+from fastapi import APIRouter, Body, HTTPException, Query, Security
+from prisma.enums import APIKeyPermission
+from pydantic import SecretStr
+from starlette import status
+
+from backend.api.external.middleware import require_permission
+from backend.data.auth.base import APIAuthorizationInfo
+from backend.data.model import (
+    APIKeyCredentials,
+    HostScopedCredentials,
+    UserPasswordCredentials,
+)
+
+from ..models import CredentialCreateRequest, CredentialInfo, CredentialListResponse
+from .helpers import creds_manager
+
+logger = logging.getLogger(__name__)
+
+credentials_router = APIRouter()
+
+
+@credentials_router.get(
+    path="/credentials",
+    summary="List integration credentials",
+    operation_id="listIntegrationCredentials",
+)
+async def list_credentials(
+    provider: Optional[str] = Query(
+        default=None,
+        description="Filter by provider name (e.g., 'github', 'google')",
+    ),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_INTEGRATIONS)
+    ),
+) -> CredentialListResponse:
+    """List integration credentials for the authenticated user."""
+    credentials = await creds_manager.store.get_all_creds(auth.user_id)
+
+    if provider:
+        credentials = [c for c in credentials if c.provider.lower() == provider.lower()]
+
+    return CredentialListResponse(
+        credentials=[CredentialInfo.from_internal(c) for c in credentials]
+    )
+
+
+@credentials_router.post(
+    path="/credentials",
+    summary="Create integration credential",
+    operation_id="createIntegrationCredential",
+    status_code=status.HTTP_201_CREATED,
+)
+async def create_credential(
+    request: Annotated[CredentialCreateRequest, Body(discriminator="type")],
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.MANAGE_INTEGRATIONS)
+    ),
+) -> CredentialInfo:
+    """
+    Create a new integration credential.
+
+    Supports `api_key`, `user_password`, and `host_scoped` credential types.
+    OAuth credentials must be set up through the web UI.
+    """
+    cred_id = str(uuid4())
+
+    if request.type == "api_key":
+        credentials = APIKeyCredentials(
+            id=cred_id,
+            provider=request.provider,
+            title=request.title,
+            api_key=SecretStr(request.api_key),
+        )
+    elif request.type == "user_password":
+        credentials = UserPasswordCredentials(
+            id=cred_id,
+            provider=request.provider,
+            title=request.title,
+            username=SecretStr(request.username),
+            password=SecretStr(request.password),
+        )
+    else:
+        credentials = HostScopedCredentials(
+            id=cred_id,
+            provider=request.provider,
+            title=request.title,
+            host=request.host,
+            headers={k: SecretStr(v) for k, v in request.headers.items()},
+        )
+
+    await creds_manager.create(auth.user_id, credentials)
+    return CredentialInfo.from_internal(credentials)
+
+
+@credentials_router.delete(
+    path="/credentials/{credential_id}",
+    summary="Delete integration credential",
+    operation_id="deleteIntegrationCredential",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def delete_credential(
+    credential_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.DELETE_INTEGRATIONS)
+    ),
+) -> None:
+    """
+    Delete an integration credential.
+
+    Any agents using this credential will fail on their next run.
+    """
+    existing = await creds_manager.store.get_creds_by_id(
+        user_id=auth.user_id, credentials_id=credential_id
+    )
+    if not existing:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Credential #{credential_id} not found",
+        )
+
+    await creds_manager.delete(auth.user_id, credential_id)

autogpt_platform/backend/backend/api/external/v2/integrations/helpers.py

@@ -0,0 +1,49 @@
+"""
+V2 External API - Integration Helpers
+
+Shared logic for credential-related operations.
+"""
+
+from backend.integrations.creds_manager import IntegrationCredentialsManager
+
+from ..models import CredentialInfo, CredentialRequirement
+
+creds_manager = IntegrationCredentialsManager()
+
+
+async def get_credential_requirements(
+    creds_schema: dict,
+    user_id: str,
+) -> list[CredentialRequirement]:
+    """
+    Extract credential requirements from a graph's credentials input schema
+    and match them against the user's existing credentials.
+    """
+    all_credentials = await creds_manager.store.get_all_creds(user_id)
+
+    requirements = []
+    for field_name, field_schema in creds_schema.get("properties", {}).items():
+        providers: list[str] = []
+        if "anyOf" in field_schema:
+            for option in field_schema["anyOf"]:
+                if "provider" in option:
+                    providers.append(option["provider"])
+        elif "provider" in field_schema:
+            providers.append(field_schema["provider"])
+
+        for provider in providers:
+            matching = [
+                CredentialInfo.from_internal(c)
+                for c in all_credentials
+                if c.provider.lower() == provider.lower()
+            ]
+
+            requirements.append(
+                CredentialRequirement(
+                    provider=provider,
+                    required_scopes=[],
+                    matching_credentials=matching,
+                )
+            )
+
+    return requirements

autogpt_platform/backend/backend/api/external/v2/library/__init__.py

@@ -0,0 +1,17 @@
+"""
+V2 External API - Library Package
+
+Aggregates all library-related sub-routers (agents, folders, presets).
+"""
+
+from fastapi import APIRouter
+
+from .agents import agents_router
+from .folders import folders_router
+from .presets import presets_router
+
+library_router = APIRouter()
+
+library_router.include_router(agents_router)
+library_router.include_router(folders_router)
+library_router.include_router(presets_router)

autogpt_platform/backend/backend/api/external/v2/library/agents.py

@@ -0,0 +1,239 @@
+"""V2 External API - Library Agent Endpoints"""
+
+import logging
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, Query, Security
+from prisma.enums import APIKeyPermission
+from starlette import status
+
+from backend.api.external.middleware import require_permission
+from backend.api.features.library import db as library_db
+from backend.data import graph as graph_db
+from backend.data.auth.base import APIAuthorizationInfo
+from backend.data.credit import get_user_credit_model
+from backend.executor import utils as execution_utils
+
+from ..common import DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE
+from ..integrations.helpers import get_credential_requirements
+from ..models import (
+    AgentGraphRun,
+    AgentRunRequest,
+    CredentialRequirementsResponse,
+    LibraryAgent,
+    LibraryAgentListResponse,
+    LibraryAgentUpdateRequest,
+)
+from ..rate_limit import execute_limiter
+
+logger = logging.getLogger(__name__)
+
+agents_router = APIRouter(tags=["library"])
+
+
+# ============================================================================
+# Endpoints
+# ============================================================================
+
+
+@agents_router.get(
+    path="/agents",
+    summary="List library agents",
+    operation_id="listLibraryAgents",
+)
+async def list_library_agents(
+    published: Optional[bool] = Query(
+        default=None,
+        description="Filter by marketplace publish status",
+    ),
+    favorite: Optional[bool] = Query(
+        default=None,
+        description="Filter by `isFavorite` attribute",
+    ),
+    page: int = Query(default=1, ge=1, description="Page number (1-indexed)"),
+    page_size: int = Query(
+        default=DEFAULT_PAGE_SIZE,
+        ge=1,
+        le=MAX_PAGE_SIZE,
+        description=f"Items per page (max {MAX_PAGE_SIZE})",
+    ),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_LIBRARY)
+    ),
+) -> LibraryAgentListResponse:
+    """List agents in the user's library."""
+    result = await library_db.list_library_agents(
+        user_id=auth.user_id,
+        page=page,
+        page_size=page_size,
+        published=published,
+        favorite=favorite,
+    )
+
+    return LibraryAgentListResponse(
+        agents=[LibraryAgent.from_internal(a) for a in result.agents],
+        page=result.pagination.current_page,
+        page_size=result.pagination.page_size,
+        total_count=result.pagination.total_items,
+        total_pages=result.pagination.total_pages,
+    )
+
+
+@agents_router.get(
+    path="/agents/{agent_id}",
+    summary="Get library agent",
+    operation_id="getLibraryAgent",
+)
+async def get_library_agent(
+    agent_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_LIBRARY)
+    ),
+) -> LibraryAgent:
+    """Get detailed information about a specific agent in the user's library."""
+    agent = await library_db.get_library_agent(
+        id=agent_id,
+        user_id=auth.user_id,
+    )
+    return LibraryAgent.from_internal(agent)
+
+
+@agents_router.patch(
+    path="/agents/{agent_id}",
+    summary="Update library agent",
+    operation_id="updateLibraryAgent",
+)
+async def update_library_agent(
+    request: LibraryAgentUpdateRequest,
+    agent_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_LIBRARY)
+    ),
+) -> LibraryAgent:
+    """Update properties of a library agent."""
+    updated = await library_db.update_library_agent(
+        library_agent_id=agent_id,
+        user_id=auth.user_id,
+        auto_update_version=request.auto_update_version,
+        graph_version=request.graph_version,
+        is_favorite=request.is_favorite,
+        is_archived=request.is_archived,
+        folder_id=request.folder_id,
+    )
+    return LibraryAgent.from_internal(updated)
+
+
+@agents_router.delete(
+    path="/agents/{agent_id}",
+    summary="Delete library agent",
+    operation_id="deleteLibraryAgent",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def delete_library_agent(
+    agent_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_LIBRARY)
+    ),
+) -> None:
+    """Remove an agent from the user's library."""
+    await library_db.delete_library_agent(
+        library_agent_id=agent_id,
+        user_id=auth.user_id,
+    )
+
+
+@agents_router.post(
+    path="/agents/{agent_id}/fork",
+    summary="Fork library agent",
+    operation_id="forkLibraryAgent",
+    status_code=status.HTTP_201_CREATED,
+)
+async def fork_library_agent(
+    agent_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_LIBRARY)
+    ),
+) -> LibraryAgent:
+    """Fork (clone) a library agent.
+
+    Creates a deep copy of the agent's underlying graph and all its nodes,
+    assigning new IDs. The cloned graph is added to the user's library as
+    an independent agent that can be modified without affecting the original.
+    """
+    forked = await library_db.fork_library_agent(
+        library_agent_id=agent_id,
+        user_id=auth.user_id,
+    )
+    return LibraryAgent.from_internal(forked)
+
+
+@agents_router.post(
+    path="/agents/{agent_id}/runs",
+    summary="Execute library agent",
+    operation_id="executeLibraryAgent",
+)
+async def execute_agent(
+    request: AgentRunRequest,
+    agent_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.RUN_AGENT)
+    ),
+) -> AgentGraphRun:
+    """Execute an agent from the library."""
+    execute_limiter.check(auth.user_id)
+
+    # Check credit balance
+    user_credit_model = await get_user_credit_model(auth.user_id)
+    current_balance = await user_credit_model.get_credits(auth.user_id)
+    if current_balance <= 0:
+        raise HTTPException(
+            status_code=status.HTTP_402_PAYMENT_REQUIRED,
+            detail="Insufficient balance to execute the agent. Please top up your account.",
+        )
+
+    # Get the library agent to find the graph ID and version
+    library_agent = await library_db.get_library_agent(
+        id=agent_id,
+        user_id=auth.user_id,
+    )
+
+    result = await execution_utils.add_graph_execution(
+        graph_id=library_agent.graph_id,
+        user_id=auth.user_id,
+        inputs=request.inputs,
+        graph_version=library_agent.graph_version,
+        graph_credentials_inputs=request.credentials_inputs,
+    )
+    return AgentGraphRun.from_internal(result)
+
+
+@agents_router.get(
+    path="/agents/{agent_id}/credentials",
+    summary="Get library agent credential requirements",
+    operation_id="getCredentialRequirementsForLibraryAgent",
+)
+async def list_agent_credential_requirements(
+    agent_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_INTEGRATIONS)
+    ),
+) -> CredentialRequirementsResponse:
+    """List credential requirements and matching user credentials for a library agent."""
+    library_agent = await library_db.get_library_agent(agent_id, user_id=auth.user_id)
+
+    graph = await graph_db.get_graph(
+        graph_id=library_agent.graph_id,
+        version=library_agent.graph_version,
+        user_id=auth.user_id,
+        include_subgraphs=True,
+    )
+    if not graph:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Graph for agent #{agent_id} not found",
+        )
+
+    requirements = await get_credential_requirements(
+        graph.credentials_input_schema, auth.user_id
+    )
+    return CredentialRequirementsResponse(requirements=requirements)

autogpt_platform/backend/backend/api/external/v2/library/folders.py

@@ -0,0 +1,175 @@
+"""V2 External API - Library Folder Endpoints"""
+
+import logging
+from typing import Optional
+
+from fastapi import APIRouter, Query, Security
+from prisma.enums import APIKeyPermission
+from starlette import status
+
+from backend.api.external.middleware import require_permission
+from backend.api.features.library import db as library_db
+from backend.data.auth.base import APIAuthorizationInfo
+
+from ..models import (
+    LibraryFolder,
+    LibraryFolderCreateRequest,
+    LibraryFolderListResponse,
+    LibraryFolderMoveRequest,
+    LibraryFolderTree,
+    LibraryFolderTreeResponse,
+    LibraryFolderUpdateRequest,
+)
+
+logger = logging.getLogger(__name__)
+
+folders_router = APIRouter(tags=["library"])
+
+
+@folders_router.get(
+    path="/folders",
+    summary="List folders in library",
+    operation_id="listLibraryFolders",
+)
+async def list_folders(
+    parent_id: Optional[str] = Query(
+        default=None, description="Filter by parent folder ID. Omit for root folders."
+    ),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_LIBRARY)
+    ),
+) -> LibraryFolderListResponse:
+    """List folders in the user's library."""
+    folders = await library_db.list_folders(
+        user_id=auth.user_id,
+        parent_id=parent_id,
+    )
+
+    return LibraryFolderListResponse(
+        folders=[LibraryFolder.from_internal(f) for f in folders],
+    )
+
+
+@folders_router.get(
+    path="/folders/tree",
+    summary="Get library folder tree",
+    operation_id="getLibraryFolderTree",
+)
+async def get_folder_tree(
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_LIBRARY)
+    ),
+) -> LibraryFolderTreeResponse:
+    """Get the full folder tree for the user's library."""
+    tree = await library_db.get_folder_tree(user_id=auth.user_id)
+
+    return LibraryFolderTreeResponse(
+        tree=[LibraryFolderTree.from_internal(f) for f in tree],
+    )
+
+
+@folders_router.get(
+    path="/folders/{folder_id}",
+    summary="Get folder in library",
+    operation_id="getLibraryFolder",
+)
+async def get_folder(
+    folder_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_LIBRARY)
+    ),
+) -> LibraryFolder:
+    """Get details of a specific folder."""
+    folder = await library_db.get_folder(
+        folder_id=folder_id,
+        user_id=auth.user_id,
+    )
+    return LibraryFolder.from_internal(folder)
+
+
+@folders_router.post(
+    path="/folders",
+    summary="Create folder in library",
+    operation_id="createLibraryFolder",
+    status_code=status.HTTP_201_CREATED,
+)
+async def create_folder(
+    request: LibraryFolderCreateRequest,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_LIBRARY)
+    ),
+) -> LibraryFolder:
+    """Create a new folder in the user's library."""
+    folder = await library_db.create_folder(
+        user_id=auth.user_id,
+        name=request.name,
+        parent_id=request.parent_id,
+        icon=request.icon,
+        color=request.color,
+    )
+    return LibraryFolder.from_internal(folder)
+
+
+@folders_router.patch(
+    path="/folders/{folder_id}",
+    summary="Update folder in library",
+    operation_id="updateLibraryFolder",
+)
+async def update_folder(
+    request: LibraryFolderUpdateRequest,
+    folder_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_LIBRARY)
+    ),
+) -> LibraryFolder:
+    """Update properties of a folder."""
+    folder = await library_db.update_folder(
+        folder_id=folder_id,
+        user_id=auth.user_id,
+        name=request.name,
+        icon=request.icon,
+        color=request.color,
+    )
+    return LibraryFolder.from_internal(folder)
+
+
+@folders_router.post(
+    path="/folders/{folder_id}/move",
+    summary="Move folder in library",
+    operation_id="moveLibraryFolder",
+)
+async def move_folder(
+    request: LibraryFolderMoveRequest,
+    folder_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_LIBRARY)
+    ),
+) -> LibraryFolder:
+    """Move a folder to a new parent. Set target_parent_id to null to move to root."""
+    folder = await library_db.move_folder(
+        folder_id=folder_id,
+        user_id=auth.user_id,
+        target_parent_id=request.target_parent_id,
+    )
+    return LibraryFolder.from_internal(folder)
+
+
+@folders_router.delete(
+    path="/folders/{folder_id}",
+    summary="Delete folder in library",
+    operation_id="deleteLibraryFolder",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def delete_folder(
+    folder_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_LIBRARY)
+    ),
+) -> None:
+    """
+    Delete a folder and its subfolders. Agents in this folder will be moved to root.
+    """
+    await library_db.delete_folder(
+        folder_id=folder_id,
+        user_id=auth.user_id,
+    )

autogpt_platform/backend/backend/api/external/v2/library/presets.py

@@ -0,0 +1,262 @@
+"""
+V2 External API - Library Preset Endpoints
+
+Provides endpoints for managing agent presets (saved run configurations).
+"""
+
+import logging
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, Query, Security
+from prisma.enums import APIKeyPermission
+from starlette import status
+
+from backend.api.external.middleware import require_permission
+from backend.api.features.library import db as library_db
+from backend.api.features.library.model import LibraryAgentPresetCreatable
+from backend.api.features.library.model import (
+    TriggeredPresetSetupRequest as _TriggeredPresetSetupRequest,
+)
+from backend.data.auth.base import APIAuthorizationInfo
+from backend.data.credit import get_user_credit_model
+from backend.executor import utils as execution_utils
+
+from ..common import DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE
+from ..models import (
+    AgentGraphRun,
+    AgentPreset,
+    AgentPresetCreateRequest,
+    AgentPresetListResponse,
+    AgentPresetRunRequest,
+    AgentPresetUpdateRequest,
+    AgentTriggerSetupRequest,
+)
+from ..rate_limit import execute_limiter
+
+logger = logging.getLogger(__name__)
+
+presets_router = APIRouter(tags=["library", "presets"])
+
+
+@presets_router.get(
+    path="/presets",
+    summary="List agent execution presets",
+    operation_id="listAgentRunPresets",
+)
+async def list_presets(
+    graph_id: Optional[str] = Query(default=None, description="Filter by graph ID"),
+    page: int = Query(default=1, ge=1, description="Page number (1-indexed)"),
+    page_size: int = Query(
+        default=DEFAULT_PAGE_SIZE,
+        ge=1,
+        le=MAX_PAGE_SIZE,
+        description=f"Items per page (max {MAX_PAGE_SIZE})",
+    ),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_LIBRARY)
+    ),
+) -> AgentPresetListResponse:
+    """List presets in the user's library, optionally filtered by graph ID."""
+    result = await library_db.list_presets(
+        user_id=auth.user_id,
+        page=page,
+        page_size=page_size,
+        graph_id=graph_id,
+    )
+
+    return AgentPresetListResponse(
+        presets=[AgentPreset.from_internal(p) for p in result.presets],
+        page=result.pagination.current_page,
+        page_size=result.pagination.page_size,
+        total_count=result.pagination.total_items,
+        total_pages=result.pagination.total_pages,
+    )
+
+
+@presets_router.get(
+    path="/presets/{preset_id}",
+    summary="Get agent execution preset",
+    operation_id="getAgentRunPreset",
+)
+async def get_preset(
+    preset_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_LIBRARY)
+    ),
+) -> AgentPreset:
+    """Get details of a specific preset."""
+    preset = await library_db.get_preset(
+        user_id=auth.user_id,
+        preset_id=preset_id,
+    )
+    if not preset:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Preset #{preset_id} not found",
+        )
+
+    return AgentPreset.from_internal(preset)
+
+
+@presets_router.post(
+    path="/presets",
+    summary="Create agent execution preset",
+    operation_id="createAgentRunPreset",
+    status_code=status.HTTP_201_CREATED,
+)
+async def create_preset(
+    request: AgentPresetCreateRequest,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_LIBRARY)
+    ),
+) -> AgentPreset:
+    """Create a new preset with saved inputs and credentials for an agent."""
+    creatable = LibraryAgentPresetCreatable(
+        graph_id=request.graph_id,
+        graph_version=request.graph_version,
+        name=request.name,
+        description=request.description,
+        inputs=request.inputs,
+        credentials=request.credentials,
+        is_active=request.is_active,
+    )
+
+    preset = await library_db.create_preset(
+        user_id=auth.user_id,
+        preset=creatable,
+    )
+    return AgentPreset.from_internal(preset)
+
+
+@presets_router.post(
+    path="/presets/setup-trigger",
+    summary="Setup triggered preset",
+    operation_id="setupAgentRunTrigger",
+    status_code=status.HTTP_201_CREATED,
+)
+async def setup_trigger(
+    request: AgentTriggerSetupRequest,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_LIBRARY)
+    ),
+) -> AgentPreset:
+    """
+    Create a preset with a webhook trigger for automatic execution.
+
+    The agent's `trigger_setup_info` describes the required trigger configuration
+    schema and credentials. Use it to populate `trigger_config` and
+    `agent_credentials`.
+    """
+    # Use internal trigger setup endpoint to avoid logic duplication:
+    from backend.api.features.library.routes.presets import (
+        setup_trigger as _internal_setup_trigger,
+    )
+
+    internal_request = _TriggeredPresetSetupRequest(
+        name=request.name,
+        description=request.description,
+        graph_id=request.graph_id,
+        graph_version=request.graph_version,
+        trigger_config=request.trigger_config,
+        agent_credentials=request.agent_credentials,
+    )
+
+    preset = await _internal_setup_trigger(
+        params=internal_request,
+        user_id=auth.user_id,
+    )
+    return AgentPreset.from_internal(preset)
+
+
+@presets_router.patch(
+    path="/presets/{preset_id}",
+    operation_id="updateAgentRunPreset",
+    summary="Update agent execution preset",
+)
+async def update_preset(
+    request: AgentPresetUpdateRequest,
+    preset_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_LIBRARY)
+    ),
+) -> AgentPreset:
+    """Update properties of a preset. Only provided fields will be updated."""
+    preset = await library_db.update_preset(
+        user_id=auth.user_id,
+        preset_id=preset_id,
+        name=request.name,
+        description=request.description,
+        inputs=request.inputs,
+        credentials=request.credentials,
+        is_active=request.is_active,
+    )
+    return AgentPreset.from_internal(preset)
+
+
+@presets_router.delete(
+    path="/presets/{preset_id}",
+    summary="Delete agent execution preset",
+    operation_id="deleteAgentRunPreset",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def delete_preset(
+    preset_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_LIBRARY)
+    ),
+) -> None:
+    """Delete a preset."""
+    await library_db.delete_preset(
+        user_id=auth.user_id,
+        preset_id=preset_id,
+    )
+
+
+@presets_router.post(
+    path="/presets/{preset_id}/execute",
+    summary="Execute agent preset",
+    operation_id="executeAgentRunPreset",
+)
+async def execute_preset(
+    preset_id: str,
+    request: AgentPresetRunRequest = AgentPresetRunRequest(),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.RUN_AGENT)
+    ),
+) -> AgentGraphRun:
+    """Execute a preset, optionally overriding saved inputs and credentials."""
+    execute_limiter.check(auth.user_id)
+
+    # Check credit balance
+    user_credit_model = await get_user_credit_model(auth.user_id)
+    current_balance = await user_credit_model.get_credits(auth.user_id)
+    if current_balance <= 0:
+        raise HTTPException(
+            status_code=status.HTTP_402_PAYMENT_REQUIRED,
+            detail="Insufficient balance to execute the agent. Please top up your account.",
+        )
+
+    # Fetch preset
+    preset = await library_db.get_preset(
+        user_id=auth.user_id,
+        preset_id=preset_id,
+    )
+    if not preset:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Preset #{preset_id} not found",
+        )
+
+    # Merge preset inputs with overrides
+    merged_inputs = {**preset.inputs, **request.inputs}
+    merged_credentials = {**preset.credentials, **request.credentials_inputs}
+
+    result = await execution_utils.add_graph_execution(
+        graph_id=preset.graph_id,
+        user_id=auth.user_id,
+        inputs=merged_inputs,
+        graph_version=preset.graph_version,
+        graph_credentials_inputs=merged_credentials,
+        preset_id=preset_id,
+    )
+    return AgentGraphRun.from_internal(result)

autogpt_platform/backend/backend/api/external/v2/marketplace.py

@@ -0,0 +1,443 @@
+"""
+V2 External API - Marketplace Endpoints
+
+Provides access to the agent marketplace (store).
+"""
+
+import logging
+import urllib.parse
+from typing import Literal, Optional
+
+from fastapi import APIRouter, File, HTTPException, Path, Query, Security, UploadFile
+from prisma.enums import APIKeyPermission
+from starlette import status
+
+from backend.api.external.middleware import require_auth, require_permission
+from backend.api.features.store import cache as store_cache
+from backend.api.features.store import db as store_db
+from backend.api.features.store import media as store_media
+from backend.api.features.store.db import (
+    StoreAgentsSortOptions,
+    StoreCreatorsSortOptions,
+)
+from backend.data.auth.base import APIAuthorizationInfo
+from backend.util.virus_scanner import scan_content_safe
+
+from .common import DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE
+from .models import (
+    LibraryAgent,
+    MarketplaceAgent,
+    MarketplaceAgentDetails,
+    MarketplaceAgentListResponse,
+    MarketplaceAgentSubmission,
+    MarketplaceAgentSubmissionCreateRequest,
+    MarketplaceAgentSubmissionEditRequest,
+    MarketplaceAgentSubmissionsListResponse,
+    MarketplaceCreatorDetails,
+    MarketplaceCreatorsResponse,
+    MarketplaceMediaUploadResponse,
+    MarketplaceUserProfile,
+    MarketplaceUserProfileUpdateRequest,
+)
+from .rate_limit import media_upload_limiter
+
+logger = logging.getLogger(__name__)
+
+marketplace_router = APIRouter(tags=["marketplace"])
+
+
+# ============================================================================
+# Agents
+# ============================================================================
+
+
+@marketplace_router.get(
+    path="/agents",
+    summary="List or search marketplace agents",
+    operation_id="listMarketplaceAgents",
+)
+async def list_agents(
+    featured: bool = Query(
+        default=False, description="Filter to only show featured agents"
+    ),
+    creator: Optional[str] = Query(
+        default=None, description="Filter by creator username"
+    ),
+    category: Optional[str] = Query(default=None, description="Filter by category"),
+    search_query: Optional[str] = Query(
+        default=None, description="Literal + semantic search on names and descriptions"
+    ),
+    sorted_by: Optional[Literal["rating", "runs", "name", "updated_at"]] = Query(
+        default=None,
+        description="Property to sort results by. Ignored if search_query is provided.",
+    ),
+    page: int = Query(ge=1, default=1),
+    page_size: int = Query(ge=1, le=MAX_PAGE_SIZE, default=DEFAULT_PAGE_SIZE),
+    # This data is public, but we still require auth for access tracking and rate limits
+    auth: APIAuthorizationInfo = Security(require_auth),
+) -> MarketplaceAgentListResponse:
+    """List agents available in the marketplace, with optional filtering and sorting."""
+    result = await store_cache._get_cached_store_agents(
+        featured=featured,
+        creator=creator,
+        sorted_by=StoreAgentsSortOptions(sorted_by) if sorted_by else None,
+        search_query=search_query,
+        category=category,
+        page=page,
+        page_size=page_size,
+    )
+
+    return MarketplaceAgentListResponse(
+        agents=[MarketplaceAgent.from_internal(a) for a in result.agents],
+        page=result.pagination.current_page,
+        page_size=result.pagination.page_size,
+        total_count=result.pagination.total_items,
+        total_pages=result.pagination.total_pages,
+    )
+
+
+@marketplace_router.get(
+    path="/agents/by-version/{version_id}",
+    summary="Get marketplace agent by version ID",
+    operation_id="getMarketplaceAgentByListingVersion",
+)
+async def get_agent_by_version(
+    version_id: str,
+    # This data is public, but we still require auth for access tracking and rate limits
+    auth: APIAuthorizationInfo = Security(require_auth),
+) -> MarketplaceAgentDetails:
+    """Get details of a marketplace agent by its store listing version ID."""
+    agent = await store_db.get_store_agent_by_version_id(version_id)
+    return MarketplaceAgentDetails.from_internal(agent)
+
+
+@marketplace_router.get(
+    path="/agents/{username}/{agent_name}",
+    summary="Get marketplace agent details",
+    operation_id="getMarketplaceAgent",
+)
+async def get_agent_details(
+    username: str,
+    agent_name: str,
+    # This data is public, but we still require auth for access tracking and rate limits
+    auth: APIAuthorizationInfo = Security(require_auth),
+) -> MarketplaceAgentDetails:
+    """Get details of a specific marketplace agent."""
+    username = urllib.parse.unquote(username).lower()
+    agent_name = urllib.parse.unquote(agent_name).lower()
+
+    agent = await store_cache._get_cached_agent_details(
+        username=username, agent_name=agent_name
+    )
+
+    return MarketplaceAgentDetails.from_internal(agent)
+
+
+@marketplace_router.post(
+    path="/agents/{username}/{agent_name}/add-to-library",
+    summary="Add marketplace agent to library",
+    operation_id="addMarketplaceAgentToLibrary",
+    status_code=status.HTTP_201_CREATED,
+)
+async def add_agent_to_library(
+    username: str,
+    agent_name: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_LIBRARY)
+    ),
+) -> LibraryAgent:
+    """Add a marketplace agent to the authenticated user's library."""
+    from backend.api.features.library import db as library_db
+
+    username = urllib.parse.unquote(username).lower()
+    agent_name = urllib.parse.unquote(agent_name).lower()
+
+    agent_details = await store_cache._get_cached_agent_details(
+        username=username, agent_name=agent_name
+    )
+
+    agent = await library_db.add_store_agent_to_library(
+        store_listing_version_id=agent_details.store_listing_version_id,
+        user_id=auth.user_id,
+    )
+
+    return LibraryAgent.from_internal(agent)
+
+
+# ============================================================================
+# Creators
+# ============================================================================
+
+
+@marketplace_router.get(
+    path="/creators",
+    summary="List marketplace creators",
+    operation_id="listMarketplaceCreators",
+)
+async def list_creators(
+    featured: bool = Query(
+        default=False, description="Filter to featured creators only"
+    ),
+    search_query: Optional[str] = Query(
+        default=None, description="Literal + semantic search on names and descriptions"
+    ),
+    sorted_by: Optional[Literal["agent_rating", "agent_runs", "num_agents"]] = Query(
+        default=None, description="Sort field"
+    ),
+    page: int = Query(ge=1, default=1),
+    page_size: int = Query(ge=1, le=MAX_PAGE_SIZE, default=DEFAULT_PAGE_SIZE),
+    # This data is public, but we still require auth for access tracking and rate limits
+    auth: APIAuthorizationInfo = Security(require_auth),
+) -> MarketplaceCreatorsResponse:
+    """List or search marketplace creators."""
+    result = await store_cache._get_cached_store_creators(
+        featured=featured,
+        search_query=search_query,
+        sorted_by=StoreCreatorsSortOptions(sorted_by) if sorted_by else None,
+        page=page,
+        page_size=page_size,
+    )
+
+    return MarketplaceCreatorsResponse(
+        creators=[MarketplaceCreatorDetails.from_internal(c) for c in result.creators],
+        page=result.pagination.current_page,
+        page_size=result.pagination.page_size,
+        total_count=result.pagination.total_items,
+        total_pages=result.pagination.total_pages,
+    )
+
+
+@marketplace_router.get(
+    path="/creators/{username}",
+    summary="Get marketplace creator details",
+    operation_id="getMarketplaceCreator",
+)
+async def get_creator_details(
+    username: str,
+    # This data is public, but we still require auth for access tracking and rate limits
+    auth: APIAuthorizationInfo = Security(require_auth),
+) -> MarketplaceCreatorDetails:
+    """Get a marketplace creator's profile w/ stats."""
+    username = urllib.parse.unquote(username).lower()
+    creator = await store_cache._get_cached_creator_details(username=username)
+    return MarketplaceCreatorDetails.from_internal(creator)
+
+
+# ============================================================================
+# Profile
+# ============================================================================
+
+
+@marketplace_router.get(
+    path="/profile",
+    summary="Get my marketplace profile",
+    operation_id="getMarketplaceMyProfile",
+)
+async def get_profile(
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_STORE)
+    ),
+) -> MarketplaceCreatorDetails:
+    """Get the authenticated user's marketplace profile w/ creator stats."""
+    profile = await store_db.get_user_profile(auth.user_id)
+    if not profile:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Profile not found",
+        )
+
+    creator = await store_cache._get_cached_creator_details(username=profile.username)
+    return MarketplaceCreatorDetails.from_internal(creator)
+
+
+@marketplace_router.patch(
+    path="/profile",
+    summary="Update my marketplace profile",
+    operation_id="updateMarketplaceMyProfile",
+)
+async def update_profile(
+    request: MarketplaceUserProfileUpdateRequest,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_STORE)
+    ),
+) -> MarketplaceUserProfile:
+    """Update the authenticated user's marketplace profile."""
+    from backend.api.features.store.model import ProfileUpdateRequest
+
+    profile = ProfileUpdateRequest(
+        name=request.name,
+        username=request.username,
+        description=request.description,
+        links=request.links,
+        avatar_url=request.avatar_url,
+    )
+
+    updated_profile = await store_db.update_profile(auth.user_id, profile)
+    return MarketplaceUserProfile.from_internal(updated_profile)
+
+
+# ============================================================================
+# Submissions
+# ============================================================================
+
+
+@marketplace_router.get(
+    path="/submissions",
+    summary="List my marketplace submissions",
+    operation_id="listMarketplaceSubmissions",
+)
+async def list_submissions(
+    page: int = Query(ge=1, default=1),
+    page_size: int = Query(ge=1, le=MAX_PAGE_SIZE, default=DEFAULT_PAGE_SIZE),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_STORE)
+    ),
+) -> MarketplaceAgentSubmissionsListResponse:
+    """List the authenticated user's marketplace listing submissions."""
+    result = await store_db.get_store_submissions(
+        user_id=auth.user_id,
+        page=page,
+        page_size=page_size,
+    )
+
+    return MarketplaceAgentSubmissionsListResponse(
+        submissions=[
+            MarketplaceAgentSubmission.from_internal(s) for s in result.submissions
+        ],
+        page=result.pagination.current_page,
+        page_size=result.pagination.page_size,
+        total_count=result.pagination.total_items,
+        total_pages=result.pagination.total_pages,
+    )
+
+
+@marketplace_router.post(
+    path="/submissions",
+    summary="Create marketplace submission",
+    operation_id="createMarketplaceSubmission",
+)
+async def create_submission(
+    request: MarketplaceAgentSubmissionCreateRequest,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_STORE)
+    ),
+) -> MarketplaceAgentSubmission:
+    """Submit a new marketplace listing for review."""
+    submission = await store_db.create_store_submission(
+        user_id=auth.user_id,
+        graph_id=request.graph_id,
+        graph_version=request.graph_version,
+        slug=request.slug,
+        name=request.name,
+        sub_heading=request.sub_heading,
+        description=request.description,
+        instructions=request.instructions,
+        categories=request.categories,
+        image_urls=request.image_urls,
+        video_url=request.video_url,
+        agent_output_demo_url=request.agent_output_demo_url,
+        changes_summary=request.changes_summary or "Initial Submission",
+        recommended_schedule_cron=request.recommended_schedule_cron,
+    )
+
+    return MarketplaceAgentSubmission.from_internal(submission)
+
+
+@marketplace_router.put(
+    path="/submissions/{version_id}",
+    summary="Edit marketplace submission",
+    operation_id="updateMarketplaceSubmission",
+)
+async def edit_submission(
+    request: MarketplaceAgentSubmissionEditRequest,
+    version_id: str = Path(description="Store listing version ID"),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_STORE)
+    ),
+) -> MarketplaceAgentSubmission:
+    """Update a pending marketplace listing submission."""
+    try:
+        submission = await store_db.edit_store_submission(
+            user_id=auth.user_id,
+            store_listing_version_id=version_id,
+            name=request.name,
+            sub_heading=request.sub_heading,
+            description=request.description,
+            image_urls=request.image_urls,
+            video_url=request.video_url,
+            agent_output_demo_url=request.agent_output_demo_url,
+            categories=request.categories,
+            changes_summary=request.changes_summary,
+            recommended_schedule_cron=request.recommended_schedule_cron,
+            instructions=request.instructions,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+    return MarketplaceAgentSubmission.from_internal(submission)
+
+
+@marketplace_router.delete(
+    path="/submissions/{version_id}",
+    summary="Delete marketplace submission",
+    operation_id="deleteMarketplaceSubmission",
+)
+async def delete_submission(
+    version_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_STORE)
+    ),
+) -> None:
+    """Delete a marketplace listing submission. Approved listings can not be deleted."""
+    success = await store_db.delete_store_submission(
+        user_id=auth.user_id,
+        store_listing_version_id=version_id,
+    )
+
+    if not success:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Submission #{version_id} not found",
+        )
+
+
+# ============================================================================
+# Submission Media
+# ============================================================================
+
+
+@marketplace_router.post(
+    path="/submissions/media",
+    summary="Upload marketplace submission media",
+    operation_id="uploadMarketplaceSubmissionMedia",
+)
+async def upload_submission_media(
+    file: UploadFile = File(...),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_STORE)
+    ),
+) -> MarketplaceMediaUploadResponse:
+    """Upload an image or video for a marketplace submission. Max size: 10MB."""
+    media_upload_limiter.check(auth.user_id)
+
+    max_size = 10 * 1024 * 1024  # 10MB limit for external API
+
+    content = await file.read()
+    if len(content) > max_size:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"File size ({len(content)} bytes) exceeds the 10MB limit",
+        )
+
+    # Virus scan
+    await scan_content_safe(content, filename=file.filename or "upload")
+
+    # Reset file position for store_media to read
+    await file.seek(0)
+
+    url = await store_media.upload_media(
+        user_id=auth.user_id,
+        file=file,
+    )
+
+    return MarketplaceMediaUploadResponse(url=url)

autogpt_platform/backend/backend/api/external/v2/mcp_server.py

@@ -0,0 +1,197 @@
+"""
+V2 External API - MCP Server Endpoint
+
+Exposes the platform's Copilot tools as an MCP (Model Context Protocol) server,
+allowing external MCP clients (Claude Desktop, Cursor, etc.) to interact with
+agents, runs, library, and other platform features programmatically.
+
+Uses Streamable HTTP transport with stateless sessions, authenticated via the
+same API key / OAuth bearer token mechanism as the rest of the external API.
+"""
+
+import logging
+from typing import Any, Sequence
+
+import pydantic
+from mcp.server.auth.middleware.auth_context import get_access_token
+from mcp.server.auth.provider import AccessToken, TokenVerifier
+from mcp.server.auth.settings import AuthSettings
+from mcp.server.fastmcp import FastMCP
+from mcp.server.fastmcp.server import Context
+from mcp.server.fastmcp.tools.base import Tool as MCPTool
+from mcp.server.fastmcp.utilities.func_metadata import ArgModelBase, FuncMetadata
+from prisma.enums import APIKeyPermission
+from pydantic import AnyHttpUrl
+from starlette.applications import Starlette
+
+from backend.copilot.model import ChatSession
+from backend.copilot.sdk.tool_adapter import _build_input_schema, _execute_tool_sync
+from backend.copilot.tools import TOOL_REGISTRY
+from backend.copilot.tools.base import BaseTool
+from backend.data.auth.api_key import validate_api_key
+from backend.data.auth.oauth import (
+    InvalidClientError,
+    InvalidTokenError,
+    validate_access_token,
+)
+from backend.util.settings import Settings
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Server factory
+# ---------------------------------------------------------------------------
+
+
+def create_mcp_server() -> FastMCP:
+    """Create the MCP server with all eligible Copilot tools registered."""
+    settings = Settings()
+    base_url = settings.config.platform_base_url or "https://platform.agpt.co"
+
+    server = FastMCP(
+        name="autogpt-platform",
+        instructions=(
+            "AutoGPT Platform MCP Server. "
+            "Use these tools to find, create, run, and manage AI agents."
+        ),
+        token_verifier=ExternalAPITokenVerifier(),
+        auth=AuthSettings(
+            issuer_url=AnyHttpUrl(base_url),
+            resource_server_url=AnyHttpUrl(f"{base_url}/external-api/v2/mcp"),
+        ),
+        stateless_http=True,
+        streamable_http_path="/",
+    )
+
+    registered: list[str] = []
+    for tool in TOOL_REGISTRY.values():
+        allowed, required_perms = tool.allow_external_use
+        if not allowed or required_perms is None:
+            logger.debug(f"Skipping MCP tool {tool.name} (not allowed externally)")
+            continue
+        _register_tool(server, tool, required_perms)
+        registered.append(tool.name)
+
+    logger.info(f"MCP server created with {len(registered)} tools: {registered}")
+    return server
+
+
+def create_mcp_app() -> Starlette:
+    """Create the Starlette ASGI app for the MCP server."""
+    server = create_mcp_server()
+    return server.streamable_http_app()
+
+
+# ---------------------------------------------------------------------------
+# Token verification — reuses existing external API auth infrastructure
+# ---------------------------------------------------------------------------
+
+
+class ExternalAPITokenVerifier(TokenVerifier):
+    """Validates API keys and OAuth tokens via external API auth."""
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        # Try API key first
+        api_key_info = await validate_api_key(token)
+        if api_key_info:
+            return AccessToken(
+                token=token,
+                client_id=api_key_info.user_id,
+                scopes=[s.value for s in api_key_info.scopes],
+            )
+
+        # Try OAuth bearer token
+        try:
+            token_info, _ = await validate_access_token(token)
+            return AccessToken(
+                token=token,
+                client_id=token_info.user_id,
+                scopes=[s.value for s in token_info.scopes],
+            )
+        except (InvalidClientError, InvalidTokenError):
+            return None
+
+
+# ---------------------------------------------------------------------------
+# Tool registration
+# ---------------------------------------------------------------------------
+
+
+def _create_tool_handler(
+    tool: BaseTool,
+    required_scopes: Sequence[str],
+):
+    """Create an async MCP tool handler that wraps a BaseTool subclass.
+
+    The handler checks that the caller's API key / OAuth token
+    has all `required_scopes` before executing the tool.
+    """
+
+    async def handler(ctx: Context, **kwargs: Any) -> str:
+        access_token = get_access_token()
+        if not access_token:
+            return "Authentication required"
+
+        # Enforce per-tool permission scopes
+        if required_scopes:
+            missing = [s for s in required_scopes if s not in access_token.scopes]
+            if missing:
+                return f"Missing required permission(s): " f"{', '.join(missing)}"
+
+        user_id = access_token.client_id
+        session = ChatSession.new(user_id)
+
+        result = await _execute_tool_sync(tool, user_id, session, kwargs)
+
+        parts = []
+        for block in result.get("content", []):
+            if block.get("type") == "text":
+                parts.append(block["text"])
+        return "\n".join(parts) if parts else ""
+
+    return handler
+
+
+def _register_tool(
+    server: FastMCP, tool: BaseTool, required_perms: Sequence[APIKeyPermission]
+) -> None:
+    """Register a Copilot tool on the MCP server."""
+    required_scopes = [p.value for p in required_perms]
+    handler = _create_tool_handler(tool, required_scopes)
+
+    mcp_tool = MCPTool(
+        fn=handler,
+        name=tool.name,
+        title=None,
+        description=tool.description,
+        parameters=_build_input_schema(tool),
+        fn_metadata=_PASSTHROUGH_META,
+        is_async=True,
+        context_kwarg="ctx",
+        annotations=None,
+    )
+    server._tool_manager._tools[tool.name] = mcp_tool
+
+
+# ---------------------------------------------------------------------------
+# Passthrough arg model — lets us specify JSON Schema directly instead of
+# having FastMCP introspect the handler function's signature.
+# ---------------------------------------------------------------------------
+
+
+class _PassthroughArgs(ArgModelBase):
+    """Accepts any fields and passes them through as kwargs."""
+
+    model_config = pydantic.ConfigDict(extra="allow")
+
+    def model_dump_one_level(self, **_kwargs: Any) -> dict[str, Any]:
+        return dict(self.__pydantic_extra__ or {})
+
+
+_PASSTHROUGH_META = FuncMetadata(
+    arg_model=_PassthroughArgs,
+    output_schema=None,
+    output_model=None,
+    wrap_output=False,
+)

autogpt_platform/backend/backend/api/external/v2/rate_limit.py

@@ -0,0 +1,43 @@
+"""
+V2 External API - Rate Limiting
+
+Simple in-memory sliding window rate limiter per user.
+"""
+
+import time
+from collections import defaultdict
+
+from fastapi import HTTPException
+
+
+class RateLimiter:
+    """Sliding window rate limiter."""
+
+    def __init__(self, max_requests: int, window_seconds: int):
+        self.max_requests = max_requests
+        self.window_seconds = window_seconds
+        self._requests: dict[str, list[float]] = defaultdict(list)
+
+    def check(self, key: str) -> None:
+        """Check if the request is within rate limits. Raises 429 if exceeded."""
+        now = time.monotonic()
+        cutoff = now - self.window_seconds
+
+        # Remove expired timestamps
+        timestamps = self._requests[key]
+        self._requests[key] = [t for t in timestamps if t > cutoff]
+
+        if len(self._requests[key]) >= self.max_requests:
+            raise HTTPException(
+                status_code=429,
+                detail=f"Rate limit exceeded. Max {self.max_requests} requests per {self.window_seconds}s.",
+            )
+
+        self._requests[key].append(now)
+
+
+# Pre-configured rate limiters for specific endpoints
+media_upload_limiter = RateLimiter(max_requests=10, window_seconds=300)  # 10 / 5min
+search_limiter = RateLimiter(max_requests=30, window_seconds=60)  # 30 / min
+execute_limiter = RateLimiter(max_requests=60, window_seconds=60)  # 60 / min
+file_upload_limiter = RateLimiter(max_requests=20, window_seconds=300)  # 20 / 5min

autogpt_platform/backend/backend/api/external/v2/routes.py

@@ -0,0 +1,33 @@
+"""
+V2 External API Routes
+
+This module defines the main v2 router that aggregates all v2 API endpoints.
+"""
+
+from fastapi import APIRouter
+
+from .blocks import blocks_router
+from .credits import credits_router
+from .files import file_workspace_router
+from .graphs import graphs_router
+from .integrations import integrations_router
+from .library import library_router
+from .marketplace import marketplace_router
+from .runs import runs_router
+from .schedules import graph_schedules_router, schedules_router
+from .search import search_router
+
+v2_router = APIRouter()
+
+# Include all sub-routers
+v2_router.include_router(blocks_router, prefix="/blocks")
+v2_router.include_router(credits_router, prefix="/credits")
+v2_router.include_router(file_workspace_router, prefix="/files")
+v2_router.include_router(graph_schedules_router, prefix="/graphs")
+v2_router.include_router(graphs_router, prefix="/graphs")
+v2_router.include_router(integrations_router, prefix="/integrations")
+v2_router.include_router(library_router, prefix="/library")
+v2_router.include_router(marketplace_router, prefix="/marketplace")
+v2_router.include_router(runs_router, prefix="/runs")
+v2_router.include_router(schedules_router, prefix="/schedules")
+v2_router.include_router(search_router, prefix="/search")

autogpt_platform/backend/backend/api/external/v2/runs.py

@@ -0,0 +1,345 @@
+"""
+V2 External API - Runs Endpoints
+
+Provides access to agent runs and human-in-the-loop reviews.
+"""
+
+import logging
+import uuid
+from datetime import datetime, timezone
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, Path, Query, Security
+from prisma.enums import APIKeyPermission, ReviewStatus
+from pydantic import JsonValue
+from starlette import status
+
+from backend.api.external.middleware import require_permission
+from backend.data import execution as execution_db
+from backend.data import human_review as review_db
+from backend.data.auth.base import APIAuthorizationInfo
+from backend.executor import utils as execution_utils
+from backend.util.settings import Settings
+
+from .common import DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE
+from .models import (
+    AgentGraphRun,
+    AgentGraphRunDetails,
+    AgentRunListResponse,
+    AgentRunReview,
+    AgentRunReviewsResponse,
+    AgentRunReviewsSubmitRequest,
+    AgentRunReviewsSubmitResponse,
+    AgentRunShareResponse,
+)
+
+logger = logging.getLogger(__name__)
+settings = Settings()
+
+runs_router = APIRouter(tags=["runs"])
+
+
+# ============================================================================
+# Endpoints - Runs
+# ============================================================================
+
+
+@runs_router.get(
+    path="",
+    summary="List agent runs",
+    operation_id="listAgentRuns",
+)
+async def list_runs(
+    graph_id: Optional[str] = Query(default=None, description="Filter by graph ID"),
+    page: int = Query(default=1, ge=1, description="Page number (1-indexed)"),
+    page_size: int = Query(
+        default=DEFAULT_PAGE_SIZE,
+        ge=1,
+        le=MAX_PAGE_SIZE,
+        description=f"Items per page (max {MAX_PAGE_SIZE})",
+    ),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_RUN)
+    ),
+) -> AgentRunListResponse:
+    """List agent runs, optionally filtered by graph ID."""
+    result = await execution_db.get_graph_executions_paginated(
+        user_id=auth.user_id,
+        graph_id=graph_id,
+        page=page,
+        page_size=page_size,
+    )
+
+    return AgentRunListResponse(
+        runs=[AgentGraphRun.from_internal(e) for e in result.executions],
+        page=result.pagination.current_page,
+        page_size=result.pagination.page_size,
+        total_count=result.pagination.total_items,
+        total_pages=result.pagination.total_pages,
+    )
+
+
+@runs_router.get(
+    path="/{run_id}",
+    summary="Get agent run details",
+    operation_id="getAgentRunDetails",
+)
+async def get_run(
+    run_id: str = Path(description="Graph Execution ID"),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_RUN)
+    ),
+) -> AgentGraphRunDetails:
+    """Get detailed information about a specific run."""
+    result = await execution_db.get_graph_execution(
+        user_id=auth.user_id,
+        execution_id=run_id,
+        include_node_executions=True,
+    )
+
+    if not result:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Run #{run_id} not found",
+        )
+
+    return AgentGraphRunDetails.from_internal(result)
+
+
+@runs_router.post(
+    path="/{run_id}/stop",
+    summary="Stop agent run",
+    operation_id="stopAgentRun",
+)
+async def stop_run(
+    run_id: str = Path(description="Graph Execution ID"),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_RUN)
+    ),
+) -> AgentGraphRun:
+    """
+    Stop a running execution.
+
+    Only runs with status QUEUED or RUNNING can be stopped.
+    """
+    # Verify the run exists and belongs to the user
+    exec = await execution_db.get_graph_execution(
+        user_id=auth.user_id,
+        execution_id=run_id,
+    )
+    if not exec:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Run #{run_id} not found",
+        )
+
+    # Stop the execution
+    await execution_utils.stop_graph_execution(
+        graph_exec_id=run_id,
+        user_id=auth.user_id,
+    )
+
+    # Fetch updated execution
+    updated_exec = await execution_db.get_graph_execution(
+        user_id=auth.user_id,
+        execution_id=run_id,
+    )
+
+    if not updated_exec:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Run #{run_id} not found",
+        )
+
+    return AgentGraphRun.from_internal(updated_exec)
+
+
+@runs_router.delete(
+    path="/{run_id}",
+    summary="Delete agent run",
+    operation_id="deleteAgentRun",
+)
+async def delete_run(
+    run_id: str = Path(description="Graph Execution ID"),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_RUN)
+    ),
+) -> None:
+    """Delete an agent run."""
+    await execution_db.delete_graph_execution(
+        graph_exec_id=run_id,
+        user_id=auth.user_id,
+    )
+
+
+# ============================================================================
+# Endpoints - Sharing
+# ============================================================================
+
+
+@runs_router.post(
+    path="/{run_id}/share",
+    summary="Enable sharing for an agent run",
+    operation_id="enableAgentRunShare",
+)
+async def enable_sharing(
+    run_id: str = Path(description="Graph Execution ID"),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_RUN, APIKeyPermission.SHARE_RUN)
+    ),
+) -> AgentRunShareResponse:
+    """Enable public sharing for a run."""
+    execution = await execution_db.get_graph_execution(
+        user_id=auth.user_id,
+        execution_id=run_id,
+    )
+    if not execution:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Run #{run_id} not found",
+        )
+
+    share_token = str(uuid.uuid4())
+
+    await execution_db.update_graph_execution_share_status(
+        execution_id=run_id,
+        user_id=auth.user_id,
+        is_shared=True,
+        share_token=share_token,
+        shared_at=datetime.now(timezone.utc),
+    )
+
+    frontend_url = settings.config.frontend_base_url or "http://localhost:3000"
+    share_url = f"{frontend_url}/share/{share_token}"
+
+    return AgentRunShareResponse(share_url=share_url, share_token=share_token)
+
+
+@runs_router.delete(
+    path="/{run_id}/share",
+    summary="Disable sharing for an agent run",
+    operation_id="disableAgentRunShare",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+async def disable_sharing(
+    run_id: str = Path(description="Graph Execution ID"),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.SHARE_RUN)
+    ),
+) -> None:
+    """Disable public sharing for a run."""
+    execution = await execution_db.get_graph_execution(
+        user_id=auth.user_id,
+        execution_id=run_id,
+    )
+    if not execution:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Run #{run_id} not found",
+        )
+
+    await execution_db.update_graph_execution_share_status(
+        execution_id=run_id,
+        user_id=auth.user_id,
+        is_shared=False,
+        share_token=None,
+        shared_at=None,
+    )
+
+
+# ============================================================================
+# Endpoints - Reviews (Human-in-the-loop)
+# ============================================================================
+
+
+@runs_router.get(
+    path="/reviews",
+    summary="List agent run human-in-the-loop reviews",
+    operation_id="listAgentRunReviews",
+)
+async def list_reviews(
+    run_id: Optional[str] = Query(
+        default=None, description="Filter by graph execution ID"
+    ),
+    status: Optional[ReviewStatus] = Query(
+        description="Filter by review status",
+    ),
+    page: int = Query(default=1, ge=1, description="Page number (1-indexed)"),
+    page_size: int = Query(
+        default=DEFAULT_PAGE_SIZE,
+        ge=1,
+        le=MAX_PAGE_SIZE,
+        description=f"Items per page (max {MAX_PAGE_SIZE})",
+    ),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_RUN_REVIEW)
+    ),
+) -> AgentRunReviewsResponse:
+    """
+    List human-in-the-loop reviews for agent runs.
+
+    Returns reviews with status WAITING if no status filter is given.
+    """
+    reviews, pagination = await review_db.get_reviews(
+        user_id=auth.user_id,
+        graph_exec_id=run_id,
+        status=status,
+        page=page,
+        page_size=page_size,
+    )
+
+    return AgentRunReviewsResponse(
+        reviews=[AgentRunReview.from_internal(r) for r in reviews],
+        page=pagination.current_page,
+        page_size=pagination.page_size,
+        total_count=pagination.total_items,
+        total_pages=pagination.total_pages,
+    )
+
+
+@runs_router.post(
+    path="/{run_id}/reviews",
+    summary="Submit agent run human-in-the-loop reviews",
+    operation_id="submitAgentRunReviews",
+)
+async def submit_reviews(
+    request: AgentRunReviewsSubmitRequest,
+    run_id: str = Path(description="Graph Execution ID"),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_RUN_REVIEW)
+    ),
+) -> AgentRunReviewsSubmitResponse:
+    """
+    Submit responses to all pending human-in-the-loop reviews for a run.
+
+    All pending reviews for the run must be included in the request.
+    Approving a review continues execution; rejecting terminates that branch.
+    """
+    # Build review decisions dict for process_all_reviews_for_execution
+    review_decisions: dict[str, tuple[ReviewStatus, JsonValue | None, str | None]] = {}
+
+    for decision in request.reviews:
+        status = ReviewStatus.APPROVED if decision.approved else ReviewStatus.REJECTED
+        review_decisions[decision.node_exec_id] = (
+            status,
+            decision.edited_payload,
+            decision.message,
+        )
+
+    results = await review_db.process_all_reviews_for_execution(
+        user_id=auth.user_id,
+        review_decisions=review_decisions,
+    )
+
+    approved_count = sum(
+        1 for r in results.values() if r.status == ReviewStatus.APPROVED
+    )
+    rejected_count = sum(
+        1 for r in results.values() if r.status == ReviewStatus.REJECTED
+    )
+
+    return AgentRunReviewsSubmitResponse(
+        run_id=run_id,
+        approved_count=approved_count,
+        rejected_count=rejected_count,
+    )

autogpt_platform/backend/backend/api/external/v2/schedules.py

@@ -0,0 +1,155 @@
+"""
+V2 External API - Schedules Endpoints
+
+Provides endpoints for managing execution schedules.
+"""
+
+import logging
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, Query, Security
+from prisma.enums import APIKeyPermission
+from starlette import status
+
+from backend.api.external.middleware import require_permission
+from backend.data import graph as graph_db
+from backend.data.auth.base import APIAuthorizationInfo
+from backend.data.user import get_user_by_id
+from backend.util.clients import get_scheduler_client
+from backend.util.timezone_utils import get_user_timezone_or_utc
+
+from .common import DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE
+from .models import (
+    AgentRunSchedule,
+    AgentRunScheduleCreateRequest,
+    AgentRunScheduleListResponse,
+)
+
+logger = logging.getLogger(__name__)
+
+schedules_router = APIRouter(tags=["graphs", "schedules"])
+
+
+# ============================================================================
+# Endpoints
+# ============================================================================
+
+
+@schedules_router.get(
+    path="",
+    summary="List run schedules",
+    operation_id="listGraphRunSchedules",
+)
+async def list_all_schedules(
+    graph_id: Optional[str] = Query(default=None, description="Filter by graph ID"),
+    page: int = Query(default=1, ge=1, description="Page number (1-indexed)"),
+    page_size: int = Query(
+        default=DEFAULT_PAGE_SIZE,
+        ge=1,
+        le=MAX_PAGE_SIZE,
+        description=f"Items per page (max {MAX_PAGE_SIZE})",
+    ),
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.READ_SCHEDULE)
+    ),
+) -> AgentRunScheduleListResponse:
+    """List schedules for the authenticated user."""
+    schedules = await get_scheduler_client().get_execution_schedules(
+        user_id=auth.user_id,
+        graph_id=graph_id,
+    )
+    converted = [AgentRunSchedule.from_internal(s) for s in schedules]
+
+    # Manual pagination (scheduler doesn't support pagination natively)
+    total_count = len(converted)
+    total_pages = (total_count + page_size - 1) // page_size if total_count > 0 else 1
+    start = (page - 1) * page_size
+    end = start + page_size
+    paginated = converted[start:end]
+
+    return AgentRunScheduleListResponse(
+        schedules=paginated,
+        page=page,
+        page_size=page_size,
+        total_count=total_count,
+        total_pages=total_pages,
+    )
+
+
+@schedules_router.delete(
+    path="/{schedule_id}",
+    summary="Delete run schedule",
+    operation_id="deleteGraphRunSchedule",
+)
+async def delete_schedule(
+    schedule_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_SCHEDULE)
+    ),
+) -> None:
+    """Delete an execution schedule."""
+    try:
+        await get_scheduler_client().delete_schedule(
+            schedule_id=schedule_id,
+            user_id=auth.user_id,
+        )
+    except Exception as e:
+        if "not found" in str(e).lower():
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Schedule #{schedule_id} not found",
+            )
+        raise
+
+
+# ============================================================================
+# Graph-specific Schedule Endpoints (nested under /graphs)
+# These are included in the graphs router via include_router
+# ============================================================================
+
+graph_schedules_router = APIRouter(tags=["graphs"])
+
+
+@graph_schedules_router.post(
+    path="/{graph_id}/schedules",
+    summary="Create run schedule",
+    operation_id="createGraphRunSchedule",
+)
+async def create_graph_schedule(
+    request: AgentRunScheduleCreateRequest,
+    graph_id: str,
+    auth: APIAuthorizationInfo = Security(
+        require_permission(APIKeyPermission.WRITE_SCHEDULE)
+    ),
+) -> AgentRunSchedule:
+    """Create a new execution schedule for a graph."""
+    graph = await graph_db.get_graph(
+        graph_id=graph_id,
+        version=request.graph_version,
+        user_id=auth.user_id,
+    )
+    if not graph:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Graph #{graph_id} v{request.graph_version} not found.",
+        )
+
+    # Determine timezone
+    if request.timezone:
+        user_timezone = request.timezone
+    else:
+        user = await get_user_by_id(auth.user_id)
+        user_timezone = get_user_timezone_or_utc(user.timezone if user else None)
+
+    result = await get_scheduler_client().add_execution_schedule(
+        user_id=auth.user_id,
+        graph_id=graph_id,
+        graph_version=graph.version,
+        name=request.name,
+        cron=request.cron,
+        input_data=request.input_data,
+        input_credentials=request.credentials_inputs,
+        user_timezone=user_timezone,
+    )
+
+    return AgentRunSchedule.from_internal(result)

autogpt_platform/backend/backend/api/external/v2/search.py

@@ -0,0 +1,76 @@
+"""
+V2 External API - Search Endpoints
+
+Cross-domain hybrid search across agents, blocks, and documentation.
+"""
+
+import logging
+from typing import Optional
+
+from fastapi import APIRouter, Query, Security
+from prisma.enums import ContentType as SearchContentType
+
+from backend.api.external.middleware import require_auth
+from backend.api.features.store.hybrid_search import unified_hybrid_search
+from backend.data.auth.base import APIAuthorizationInfo
+
+from .common import DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE
+from .models import MarketplaceSearchResponse, MarketplaceSearchResult
+from .rate_limit import search_limiter
+
+logger = logging.getLogger(__name__)
+
+search_router = APIRouter(tags=["search"])
+
+
+@search_router.get(
+    path="",
+    summary="Search content and capabilities of the platform",
+    operation_id="search",
+)
+async def search(
+    query: str = Query(description="Search query"),
+    content_types: Optional[list[SearchContentType]] = Query(
+        default=None, description="Content types to filter by"
+    ),
+    category: Optional[str] = Query(default=None, description="Filter by category"),
+    page: int = Query(ge=1, default=1),
+    page_size: int = Query(ge=1, le=MAX_PAGE_SIZE, default=DEFAULT_PAGE_SIZE),
+    auth: APIAuthorizationInfo = Security(require_auth),
+) -> MarketplaceSearchResponse:
+    """
+    Search the platform's content and capabilities (hybrid search: literal + semantic).
+
+    Searches across agents, blocks, and documentation. Results are ranked
+    by a combination of keyword matching and semantic similarity.
+    """
+    search_limiter.check(auth.user_id)
+
+    results, total_count = await unified_hybrid_search(
+        query=query,
+        content_types=content_types,
+        category=category,
+        page=page,
+        page_size=page_size,
+        user_id=auth.user_id,
+    )
+
+    total_pages = max(1, (total_count + page_size - 1) // page_size)
+
+    return MarketplaceSearchResponse(
+        results=[
+            MarketplaceSearchResult(
+                content_type=r.get("content_type", ""),
+                content_id=r.get("content_id", ""),
+                searchable_text=r.get("searchable_text", ""),
+                metadata=r.get("metadata"),
+                updated_at=r.get("updated_at"),
+                combined_score=r.get("combined_score"),
+            )
+            for r in results
+        ],
+        page=page,
+        page_size=page_size,
+        total_count=total_count,
+        total_pages=total_pages,
+    )

autogpt_platform/backend/backend/api/features/admin/store_admin_routes.py

@@ -24,14 +24,13 @@ router = fastapi.APIRouter(
 @router.get(
     "/listings",
     summary="Get Admin Listings History",
-    response_model=store_model.StoreListingsWithVersionsResponse,
 )
 async def get_admin_listings_with_versions(
     status: typing.Optional[prisma.enums.SubmissionStatus] = None,
     search: typing.Optional[str] = None,
     page: int = 1,
     page_size: int = 20,
-):
+) -> store_model.StoreListingsWithVersionsAdminViewResponse:
     """
     Get store listings with their version history for admins.
 
@@ -45,36 +44,26 @@ async def get_admin_listings_with_versions(
         page_size: Number of items per page
 
     Returns:
-        StoreListingsWithVersionsResponse with listings and their versions
+        Paginated listings with their versions
     """
-    try:
-        listings = await store_db.get_admin_listings_with_versions(
-            status=status,
-            search_query=search,
-            page=page,
-            page_size=page_size,
-        )
-        return listings
-    except Exception as e:
-        logger.exception("Error getting admin listings with versions: %s", e)
-        return fastapi.responses.JSONResponse(
-            status_code=500,
-            content={
-                "detail": "An error occurred while retrieving listings with versions"
-            },
-        )
+    listings = await store_db.get_admin_listings_with_versions(
+        status=status,
+        search_query=search,
+        page=page,
+        page_size=page_size,
+    )
+    return listings
 
 
 @router.post(
     "/submissions/{store_listing_version_id}/review",
     summary="Review Store Submission",
-    response_model=store_model.StoreSubmission,
 )
 async def review_submission(
     store_listing_version_id: str,
     request: store_model.ReviewSubmissionRequest,
     user_id: str = fastapi.Security(autogpt_libs.auth.get_user_id),
-):
+) -> store_model.StoreSubmissionAdminView:
     """
     Review a store listing submission.
 
@@ -84,31 +73,24 @@ async def review_submission(
         user_id: Authenticated admin user performing the review
 
     Returns:
-        StoreSubmission with updated review information
+        StoreSubmissionAdminView with updated review information
     """
-    try:
-        already_approved = await store_db.check_submission_already_approved(
-            store_listing_version_id=store_listing_version_id,
-        )
-        submission = await store_db.review_store_submission(
-            store_listing_version_id=store_listing_version_id,
-            is_approved=request.is_approved,
-            external_comments=request.comments,
-            internal_comments=request.internal_comments or "",
-            reviewer_id=user_id,
-        )
+    already_approved = await store_db.check_submission_already_approved(
+        store_listing_version_id=store_listing_version_id,
+    )
+    submission = await store_db.review_store_submission(
+        store_listing_version_id=store_listing_version_id,
+        is_approved=request.is_approved,
+        external_comments=request.comments,
+        internal_comments=request.internal_comments or "",
+        reviewer_id=user_id,
+    )
 
-        state_changed = already_approved != request.is_approved
-        # Clear caches when the request is approved as it updates what is shown on the store
-        if state_changed:
-            store_cache.clear_all_caches()
-        return submission
-    except Exception as e:
-        logger.exception("Error reviewing submission: %s", e)
-        return fastapi.responses.JSONResponse(
-            status_code=500,
-            content={"detail": "An error occurred while reviewing the submission"},
-        )
+    state_changed = already_approved != request.is_approved
+    # Clear caches whenever approval state changes, since store visibility can change
+    if state_changed:
+        store_cache.clear_all_caches()
+    return submission
 
 
 @router.get(

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

@@ -28,6 +28,7 @@ from backend.copilot.model import (
     update_session_title,
 )
 from backend.copilot.response_model import StreamError, StreamFinish, StreamHeartbeat
+from backend.copilot.tools.e2b_sandbox import kill_sandbox
 from backend.copilot.tools.models import (
     AgentDetailsResponse,
     AgentOutputResponse,
@@ -265,12 +266,12 @@ async def delete_session(
         )
 
     # Best-effort cleanup of the E2B sandbox (if any).
-    config = ChatConfig()
-    if config.use_e2b_sandbox and config.e2b_api_key:
-        from backend.copilot.tools.e2b_sandbox import kill_sandbox
-
+    # sandbox_id is in Redis; kill_sandbox() fetches it from there.
+    e2b_cfg = ChatConfig()
+    if e2b_cfg.e2b_active:
+        assert e2b_cfg.e2b_api_key  # guaranteed by e2b_active check
         try:
-            await kill_sandbox(session_id, config.e2b_api_key)
+            await kill_sandbox(session_id, e2b_cfg.e2b_api_key)
         except Exception:
             logger.warning(
                 "[E2B] Failed to kill sandbox for session %s", session_id[:12]
@@ -805,7 +806,6 @@ async def resume_session_stream(
 @router.patch(
     "/sessions/{session_id}/assign-user",
     dependencies=[Security(auth.requires_user)],
-    status_code=200,
 )
 async def session_assign_user(
     session_id: str,

autogpt_platform/backend/backend/api/features/executions/review/review_routes_test.py

@@ -638,7 +638,7 @@ async def test_process_review_action_auto_approve_creates_auto_approval_records(
 
     # Mock get_node_executions to return node_id mapping
     mock_get_node_executions = mocker.patch(
-        "backend.data.execution.get_node_executions"
+        "backend.api.features.executions.review.routes.get_node_executions"
     )
     mock_node_exec = mocker.Mock(spec=NodeExecutionResult)
     mock_node_exec.node_exec_id = "test_node_123"
@@ -936,7 +936,7 @@ async def test_process_review_action_auto_approve_only_applies_to_approved_revie
 
     # Mock get_node_executions to return node_id mapping
     mock_get_node_executions = mocker.patch(
-        "backend.data.execution.get_node_executions"
+        "backend.api.features.executions.review.routes.get_node_executions"
     )
     mock_node_exec = mocker.Mock(spec=NodeExecutionResult)
     mock_node_exec.node_exec_id = "node_exec_approved"
@@ -1148,7 +1148,7 @@ async def test_process_review_action_per_review_auto_approve_granularity(
 
     # Mock get_node_executions to return batch node data
     mock_get_node_executions = mocker.patch(
-        "backend.data.execution.get_node_executions"
+        "backend.api.features.executions.review.routes.get_node_executions"
     )
     # Create mock node executions for each review
     mock_node_execs = []

autogpt_platform/backend/backend/api/features/executions/review/routes.py

@@ -6,10 +6,15 @@ import autogpt_libs.auth as autogpt_auth_lib
 from fastapi import APIRouter, HTTPException, Query, Security, status
 from prisma.enums import ReviewStatus
 
+from backend.copilot.constants import (
+    is_copilot_synthetic_id,
+    parse_node_id_from_exec_id,
+)
 from backend.data.execution import (
     ExecutionContext,
     ExecutionStatus,
     get_graph_execution_meta,
+    get_node_executions,
 )
 from backend.data.graph import get_graph_settings
 from backend.data.human_review import (
@@ -36,6 +41,38 @@ router = APIRouter(
 )
 
 
+async def _resolve_node_ids(
+    node_exec_ids: list[str],
+    graph_exec_id: str,
+    is_copilot: bool,
+) -> dict[str, str]:
+    """Resolve node_exec_id -> node_id for auto-approval records.
+
+    CoPilot synthetic IDs encode node_id in the format "{node_id}:{random}".
+    Graph executions look up node_id from NodeExecution records.
+    """
+    if not node_exec_ids:
+        return {}
+
+    if is_copilot:
+        return {neid: parse_node_id_from_exec_id(neid) for neid in node_exec_ids}
+
+    node_execs = await get_node_executions(
+        graph_exec_id=graph_exec_id, include_exec_data=False
+    )
+    node_exec_map = {ne.node_exec_id: ne.node_id for ne in node_execs}
+
+    result = {}
+    for neid in node_exec_ids:
+        if neid in node_exec_map:
+            result[neid] = node_exec_map[neid]
+        else:
+            logger.error(
+                f"Failed to resolve node_id for {neid}: Node execution not found."
+            )
+    return result
+
+
 @router.get(
     "/pending",
     summary="Get Pending Reviews",
@@ -110,14 +147,16 @@ async def list_pending_reviews_for_execution(
     """
 
     # Verify user owns the graph execution before returning reviews
-    graph_exec = await get_graph_execution_meta(
-        user_id=user_id, execution_id=graph_exec_id
-    )
-    if not graph_exec:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"Graph execution #{graph_exec_id} not found",
+    # (CoPilot synthetic IDs don't have graph execution records)
+    if not is_copilot_synthetic_id(graph_exec_id):
+        graph_exec = await get_graph_execution_meta(
+            user_id=user_id, execution_id=graph_exec_id
         )
+        if not graph_exec:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Graph execution #{graph_exec_id} not found",
+            )
 
     return await get_pending_reviews_for_execution(graph_exec_id, user_id)
 
@@ -160,30 +199,26 @@ async def process_review_action(
         )
 
     graph_exec_id = next(iter(graph_exec_ids))
+    is_copilot = is_copilot_synthetic_id(graph_exec_id)
 
-    # Validate execution status before processing reviews
-    graph_exec_meta = await get_graph_execution_meta(
-        user_id=user_id, execution_id=graph_exec_id
-    )
-
-    if not graph_exec_meta:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"Graph execution #{graph_exec_id} not found",
-        )
-
-    # Only allow processing reviews if execution is paused for review
-    # or incomplete (partial execution with some reviews already processed)
-    if graph_exec_meta.status not in (
-        ExecutionStatus.REVIEW,
-        ExecutionStatus.INCOMPLETE,
-    ):
-        raise HTTPException(
-            status_code=status.HTTP_409_CONFLICT,
-            detail=f"Cannot process reviews while execution status is {graph_exec_meta.status}. "
-            f"Reviews can only be processed when execution is paused (REVIEW status). "
-            f"Current status: {graph_exec_meta.status}",
+    # Validate execution status for graph executions (skip for CoPilot synthetic IDs)
+    if not is_copilot:
+        graph_exec_meta = await get_graph_execution_meta(
+            user_id=user_id, execution_id=graph_exec_id
         )
+        if not graph_exec_meta:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Graph execution #{graph_exec_id} not found",
+            )
+        if graph_exec_meta.status not in (
+            ExecutionStatus.REVIEW,
+            ExecutionStatus.INCOMPLETE,
+        ):
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail=f"Cannot process reviews while execution status is {graph_exec_meta.status}",
+            )
 
     # Build review decisions map and track which reviews requested auto-approval
     # Auto-approved reviews use original data (no modifications allowed)
@@ -236,7 +271,7 @@ async def process_review_action(
             )
             return (node_id, False)
 
-    # Collect node_exec_ids that need auto-approval
+    # Collect node_exec_ids that need auto-approval and resolve their node_ids
     node_exec_ids_needing_auto_approval = [
         node_exec_id
         for node_exec_id, review_result in updated_reviews.items()
@@ -244,29 +279,16 @@ async def process_review_action(
         and auto_approve_requests.get(node_exec_id, False)
     ]
 
-    # Batch-fetch node executions to get node_ids
+    node_id_map = await _resolve_node_ids(
+        node_exec_ids_needing_auto_approval, graph_exec_id, is_copilot
+    )
+
+    # Deduplicate by node_id — one auto-approval per node
     nodes_needing_auto_approval: dict[str, Any] = {}
-    if node_exec_ids_needing_auto_approval:
-        from backend.data.execution import get_node_executions
-
-        node_execs = await get_node_executions(
-            graph_exec_id=graph_exec_id, include_exec_data=False
-        )
-        node_exec_map = {node_exec.node_exec_id: node_exec for node_exec in node_execs}
-
-        for node_exec_id in node_exec_ids_needing_auto_approval:
-            node_exec = node_exec_map.get(node_exec_id)
-            if node_exec:
-                review_result = updated_reviews[node_exec_id]
-                # Use the first approved review for this node (deduplicate by node_id)
-                if node_exec.node_id not in nodes_needing_auto_approval:
-                    nodes_needing_auto_approval[node_exec.node_id] = review_result
-            else:
-                logger.error(
-                    f"Failed to create auto-approval record for {node_exec_id}: "
-                    f"Node execution not found. This may indicate a race condition "
-                    f"or data inconsistency."
-                )
+    for node_exec_id in node_exec_ids_needing_auto_approval:
+        node_id = node_id_map.get(node_exec_id)
+        if node_id and node_id not in nodes_needing_auto_approval:
+            nodes_needing_auto_approval[node_id] = updated_reviews[node_exec_id]
 
     # Execute all auto-approval creations in parallel (deduplicated by node_id)
     auto_approval_results = await asyncio.gather(
@@ -281,13 +303,11 @@ async def process_review_action(
     auto_approval_failed_count = 0
     for result in auto_approval_results:
         if isinstance(result, Exception):
-            # Unexpected exception during auto-approval creation
             auto_approval_failed_count += 1
             logger.error(
                 f"Unexpected exception during auto-approval creation: {result}"
             )
         elif isinstance(result, tuple) and len(result) == 2 and not result[1]:
-            # Auto-approval creation failed (returned False)
             auto_approval_failed_count += 1
 
     # Count results
@@ -302,22 +322,20 @@ async def process_review_action(
         if review.status == ReviewStatus.REJECTED
     )
 
-    # Resume execution only if ALL pending reviews for this execution have been processed
-    if updated_reviews:
+    # Resume graph execution only for real graph executions (not CoPilot)
+    # CoPilot sessions are resumed by the LLM retrying run_block with review_id
+    if not is_copilot and updated_reviews:
         still_has_pending = await has_pending_reviews_for_graph_exec(graph_exec_id)
 
         if not still_has_pending:
-            # Get the graph_id from any processed review
             first_review = next(iter(updated_reviews.values()))
 
             try:
-                # Fetch user and settings to build complete execution context
                 user = await get_user_by_id(user_id)
                 settings = await get_graph_settings(
                     user_id=user_id, graph_id=first_review.graph_id
                 )
 
-                # Preserve user's timezone preference when resuming execution
                 user_timezone = (
                     user.timezone if user.timezone != USER_TIMEZONE_NOT_SET else "UTC"
                 )

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

@@ -4,11 +4,12 @@ import logging
 from typing import Literal, Optional
 
 import fastapi
+import prisma.enums
 import prisma.errors
 import prisma.models
 import prisma.types
+from prisma.enums import SubmissionStatus
 
-import backend.api.features.store.exceptions as store_exceptions
 import backend.api.features.store.image_gen as store_image_gen
 import backend.api.features.store.media as store_media
 import backend.data.graph as graph_db
@@ -47,6 +48,8 @@ integration_creds_manager = IntegrationCredentialsManager()
 async def list_library_agents(
     user_id: str,
     search_term: Optional[str] = None,
+    published: Optional[bool] = None,
+    favorite: Optional[bool] = None,
     sort_by: library_model.LibraryAgentSort = library_model.LibraryAgentSort.UPDATED_AT,
     page: int = 1,
     page_size: int = 50,
@@ -60,6 +63,8 @@ async def list_library_agents(
     Args:
         user_id: The ID of the user whose LibraryAgents we want to retrieve.
         search_term: Optional string to filter agents by name/description.
+        published: Allows filtering by marketplace publish status;
+            `True` -> only published agents, `False` -> only unpublished agents.
         sort_by: Sorting field (createdAt, updatedAt, isFavorite, isCreatedByUser).
         page: Current page (1-indexed).
         page_size: Number of items per page.
@@ -118,6 +123,28 @@ async def list_library_agents(
             },
         ]
 
+    # Filter by marketplace publish status
+    if published is not None:
+        active_listing_filter: prisma.types.StoreListingVersionWhereInput = {
+            "isAvailable": True,
+            "isDeleted": False,
+            "submissionStatus": prisma.enums.SubmissionStatus.APPROVED,
+            "StoreListing": {"is": {"isDeleted": False}},
+        }
+        where_clause["AgentGraph"] = {
+            "is": {
+                "StoreListingVersions": (
+                    {"some": active_listing_filter}
+                    if published
+                    else {"none": active_listing_filter}
+                )
+            }
+        }
+
+    # Filter by favorite status
+    if favorite is not None:
+        where_clause["isFavorite"] = favorite
+
     order_by: prisma.types.LibraryAgentOrderByInput | None = None
 
     if sort_by == library_model.LibraryAgentSort.CREATED_AT:
@@ -251,7 +278,7 @@ async def get_library_agent(id: str, user_id: str) -> library_model.LibraryAgent
         The requested LibraryAgent.
 
     Raises:
-        AgentNotFoundError: If the specified agent does not exist.
+        NotFoundError: If the specified agent does not exist.
         DatabaseError: If there's an error during retrieval.
     """
     library_agent = await prisma.models.LibraryAgent.prisma().find_first(
@@ -260,32 +287,12 @@ async def get_library_agent(id: str, user_id: str) -> library_model.LibraryAgent
             "userId": user_id,
             "isDeleted": False,
         },
-        include=library_agent_include(user_id),
+        include=library_agent_include(user_id, include_store_listing=True),
     )
 
     if not library_agent:
         raise NotFoundError(f"Library agent #{id} not found")
 
-    # Fetch marketplace listing if the agent has been published
-    store_listing = None
-    profile = None
-    if library_agent.AgentGraph:
-        store_listing = await prisma.models.StoreListing.prisma().find_first(
-            where={
-                "agentGraphId": library_agent.AgentGraph.id,
-                "isDeleted": False,
-                "hasApprovedVersion": True,
-            },
-            include={
-                "ActiveVersion": True,
-            },
-        )
-        if store_listing and store_listing.ActiveVersion and store_listing.owningUserId:
-            # Fetch Profile separately since User doesn't have a direct Profile relation
-            profile = await prisma.models.Profile.prisma().find_first(
-                where={"userId": store_listing.owningUserId}
-            )
-
     return library_model.LibraryAgent.from_db(
         library_agent,
         sub_graphs=(
@@ -293,8 +300,6 @@ async def get_library_agent(id: str, user_id: str) -> library_model.LibraryAgent
             if library_agent.AgentGraph
             else None
         ),
-        store_listing=store_listing,
-        profile=profile,
     )
 
 
@@ -398,6 +403,7 @@ async def create_library_agent(
     hitl_safe_mode: bool = True,
     sensitive_action_safe_mode: bool = False,
     create_library_agents_for_sub_graphs: bool = True,
+    folder_id: str | None = None,
 ) -> list[library_model.LibraryAgent]:
     """
     Adds an agent to the user's library (LibraryAgent table).
@@ -414,12 +420,18 @@ async def create_library_agent(
         If the graph has sub-graphs, the parent graph will always be the first entry in the list.
 
     Raises:
-        AgentNotFoundError: If the specified agent does not exist.
+        NotFoundError: If the specified agent does not exist.
         DatabaseError: If there's an error during creation or if image generation fails.
     """
     logger.info(
         f"Creating library agent for graph #{graph.id} v{graph.version}; user:<redacted>"
     )
+
+    # Authorization: FK only checks existence, not ownership.
+    # Verify the folder belongs to this user to prevent cross-user nesting.
+    if folder_id:
+        await get_folder(folder_id, user_id)
+
     graph_entries = (
         [graph, *graph.sub_graphs] if create_library_agents_for_sub_graphs else [graph]
     )
@@ -432,7 +444,6 @@ async def create_library_agent(
                         isCreatedByUser=(user_id == user_id),
                         useGraphIsActiveVersion=True,
                         User={"connect": {"id": user_id}},
-                        # Creator={"connect": {"id": user_id}},
                         AgentGraph={
                             "connect": {
                                 "graphVersionId": {
@@ -442,12 +453,16 @@ async def create_library_agent(
                             }
                         },
                         settings=SafeJson(
-                            GraphSettings.from_graph(
-                                graph_entry,
-                                hitl_safe_mode=hitl_safe_mode,
+                            GraphSettings(
+                                human_in_the_loop_safe_mode=hitl_safe_mode,
                                 sensitive_action_safe_mode=sensitive_action_safe_mode,
                             ).model_dump()
                         ),
+                        **(
+                            {"Folder": {"connect": {"id": folder_id}}}
+                            if folder_id and graph_entry is graph
+                            else {}
+                        ),
                     ),
                     include=library_agent_include(
                         user_id, include_nodes=False, include_executions=False
@@ -529,6 +544,7 @@ async def update_agent_version_in_library(
 async def create_graph_in_library(
     graph: graph_db.Graph,
     user_id: str,
+    folder_id: str | None = None,
 ) -> tuple[graph_db.GraphModel, library_model.LibraryAgent]:
     """Create a new graph and add it to the user's library."""
     graph.version = 1
@@ -542,6 +558,7 @@ async def create_graph_in_library(
         user_id=user_id,
         sensitive_action_safe_mode=True,
         create_library_agents_for_sub_graphs=False,
+        folder_id=folder_id,
     )
 
     if created_graph.is_active:
@@ -574,8 +591,8 @@ async def update_graph_in_library(
     if not library_agent:
         raise NotFoundError(f"Library agent not found for graph {created_graph.id}")
 
-    library_agent = await update_library_agent_version_and_settings(
-        user_id, created_graph
+    library_agent = await update_agent_version_in_library(
+        user_id, created_graph.id, created_graph.version
     )
 
     if created_graph.is_active:
@@ -591,27 +608,6 @@ async def update_graph_in_library(
     return created_graph, library_agent
 
 
-async def update_library_agent_version_and_settings(
-    user_id: str, agent_graph: graph_db.GraphModel
-) -> library_model.LibraryAgent:
-    """Update library agent to point to new graph version and sync settings."""
-    library = await update_agent_version_in_library(
-        user_id, agent_graph.id, agent_graph.version
-    )
-    updated_settings = GraphSettings.from_graph(
-        graph=agent_graph,
-        hitl_safe_mode=library.settings.human_in_the_loop_safe_mode,
-        sensitive_action_safe_mode=library.settings.sensitive_action_safe_mode,
-    )
-    if updated_settings != library.settings:
-        library = await update_library_agent(
-            library_agent_id=library.id,
-            user_id=user_id,
-            settings=updated_settings,
-        )
-    return library
-
-
 async def update_library_agent(
     library_agent_id: str,
     user_id: str,
@@ -811,13 +807,13 @@ async def add_store_agent_to_library(
 
     Args:
         store_listing_version_id: The ID of the store listing version containing the agent.
-        user_id: The user’s library to which the agent is being added.
+        user_id: The user's library to which the agent is being added.
 
     Returns:
         The newly created LibraryAgent if successfully added, the existing corresponding one if any.
 
     Raises:
-        AgentNotFoundError: If the store listing or associated agent is not found.
+        NotFoundError: If the store listing or associated agent is not found.
         DatabaseError: If there's an issue creating the LibraryAgent record.
     """
     logger.debug(
@@ -825,34 +821,30 @@ async def add_store_agent_to_library(
         f"to library for user #{user_id}"
     )
 
-    store_listing_version = (
-        await prisma.models.StoreListingVersion.prisma().find_unique(
-            where={"id": store_listing_version_id}, include={"AgentGraph": True}
-        )
+    listing_version = await prisma.models.StoreListingVersion.prisma().find_unique(
+        where={"id": store_listing_version_id}
     )
-    if not store_listing_version or not store_listing_version.AgentGraph:
-        logger.warning(f"Store listing version not found: {store_listing_version_id}")
-        raise store_exceptions.AgentNotFoundError(
-            f"Store listing version {store_listing_version_id} not found or invalid"
+    if (
+        not listing_version
+        or not listing_version.AgentGraph
+        or listing_version.submissionStatus != SubmissionStatus.APPROVED
+        or listing_version.isDeleted
+    ):
+        logger.warning(
+            "Store listing version not found or not available: "
+            f"{store_listing_version_id}"
+        )
+        raise NotFoundError(
+            f"Store listing version {store_listing_version_id} not found "
+            "or not available"
         )
 
-    graph = store_listing_version.AgentGraph
-
-    # Convert to GraphModel to check for HITL blocks
-    graph_model = await graph_db.get_graph(
-        graph_id=graph.id,
-        version=graph.version,
-        user_id=user_id,
-        include_subgraphs=False,
-    )
-    if not graph_model:
-        raise store_exceptions.AgentNotFoundError(
-            f"Graph #{graph.id} v{graph.version} not found or accessible"
-        )
+    graph_id = listing_version.agentGraphId
+    graph_version = listing_version.agentGraphVersion
 
     # Check if user already has this agent (non-deleted)
     if existing := await get_library_agent_by_graph_id(
-        user_id, graph.id, graph.version
+        user_id, graph_id, graph_version
     ):
         return existing
 
@@ -861,8 +853,8 @@ async def add_store_agent_to_library(
         where={
             "userId_agentGraphId_agentGraphVersion": {
                 "userId": user_id,
-                "agentGraphId": graph.id,
-                "agentGraphVersion": graph.version,
+                "agentGraphId": graph_id,
+                "agentGraphVersion": graph_version,
             }
         },
     )
@@ -875,20 +867,20 @@ async def add_store_agent_to_library(
             "User": {"connect": {"id": user_id}},
             "AgentGraph": {
                 "connect": {
-                    "graphVersionId": {"id": graph.id, "version": graph.version}
+                    "graphVersionId": {"id": graph_id, "version": graph_version}
                 }
             },
             "isCreatedByUser": False,
             "useGraphIsActiveVersion": False,
-            "settings": SafeJson(GraphSettings.from_graph(graph_model).model_dump()),
+            "settings": SafeJson(GraphSettings().model_dump()),
         },
         include=library_agent_include(
             user_id, include_nodes=False, include_executions=False
         ),
     )
     logger.debug(
-        f"Added graph #{graph.id} v{graph.version}"
-        f"for store listing version #{store_listing_version.id} "
+        f"Added graph #{graph_id} v{graph_version}"
+        f"for store listing version #{listing_version.id} "
         f"to library for user #{user_id}"
     )
     return library_model.LibraryAgent.from_db(added_agent)
@@ -899,37 +891,6 @@ async def add_store_agent_to_library(
 ##############################################
 
 
-async def _fetch_user_folders(
-    user_id: str,
-    extra_where: Optional[prisma.types.LibraryFolderWhereInput] = None,
-    include_relations: bool = True,
-) -> list[prisma.models.LibraryFolder]:
-    """
-    Shared helper to fetch folders for a user with consistent query params.
-
-    Args:
-        user_id: The ID of the user.
-        extra_where: Additional where-clause filters to merge in.
-        include_relations: Whether to include LibraryAgents and Children relations
-            (used to derive counts via len(); Prisma Python has no _count include).
-
-    Returns:
-        A list of raw Prisma LibraryFolder records.
-    """
-    where_clause: prisma.types.LibraryFolderWhereInput = {
-        "userId": user_id,
-        "isDeleted": False,
-    }
-    if extra_where:
-        where_clause.update(extra_where)
-
-    return await prisma.models.LibraryFolder.prisma().find_many(
-        where=where_clause,
-        order={"createdAt": "asc"},
-        include=LIBRARY_FOLDER_INCLUDE if include_relations else None,
-    )
-
-
 async def list_folders(
     user_id: str,
     parent_id: Optional[str] = None,
@@ -1007,6 +968,37 @@ async def get_folder_tree(
     return root_folders
 
 
+async def _fetch_user_folders(
+    user_id: str,
+    extra_where: Optional[prisma.types.LibraryFolderWhereInput] = None,
+    include_relations: bool = True,
+) -> list[prisma.models.LibraryFolder]:
+    """
+    Shared helper to fetch folders for a user with consistent query params.
+
+    Args:
+        user_id: The ID of the user.
+        extra_where: Additional where-clause filters to merge in.
+        include_relations: Whether to include LibraryAgents and Children relations
+            (used to derive counts via len(); Prisma Python has no _count include).
+
+    Returns:
+        A list of raw Prisma LibraryFolder records.
+    """
+    where_clause: prisma.types.LibraryFolderWhereInput = {
+        "userId": user_id,
+        "isDeleted": False,
+    }
+    if extra_where:
+        where_clause.update(extra_where)
+
+    return await prisma.models.LibraryFolder.prisma().find_many(
+        where=where_clause,
+        order={"createdAt": "asc"},
+        include=LIBRARY_FOLDER_INCLUDE if include_relations else None,
+    )
+
+
 async def get_folder(
     folder_id: str,
     user_id: str,
@@ -1043,43 +1035,6 @@ async def get_folder(
     )
 
 
-async def _is_descendant_of(
-    folder_id: str,
-    potential_ancestor_id: str,
-    user_id: str,
-) -> bool:
-    """
-    Check if folder_id is a descendant of (or equal to) potential_ancestor_id.
-
-    Fetches all user folders in a single query and walks the parent chain
-    in memory to avoid N database round-trips.
-
-    Args:
-        folder_id: The ID of the folder to check.
-        potential_ancestor_id: The ID of the potential ancestor.
-        user_id: The ID of the user.
-
-    Returns:
-        True if folder_id is a descendant of (or equal to) potential_ancestor_id.
-    """
-    all_folders = await prisma.models.LibraryFolder.prisma().find_many(
-        where={"userId": user_id, "isDeleted": False},
-    )
-    parent_map = {f.id: f.parentId for f in all_folders}
-
-    visited: set[str] = set()
-    current_id: str | None = folder_id
-    while current_id:
-        if current_id == potential_ancestor_id:
-            return True
-        if current_id in visited:
-            break  # cycle detected
-        visited.add(current_id)
-        current_id = parent_map.get(current_id)
-
-    return False
-
-
 async def create_folder(
     user_id: str,
     name: str,
@@ -1291,6 +1246,43 @@ async def move_folder(
     )
 
 
+async def _is_descendant_of(
+    folder_id: str,
+    potential_ancestor_id: str,
+    user_id: str,
+) -> bool:
+    """
+    Check if folder_id is a descendant of (or equal to) potential_ancestor_id.
+
+    Fetches all user folders in a single query and walks the parent chain
+    in memory to avoid N database round-trips.
+
+    Args:
+        folder_id: The ID of the folder to check.
+        potential_ancestor_id: The ID of the potential ancestor.
+        user_id: The ID of the user.
+
+    Returns:
+        True if folder_id is a descendant of (or equal to) potential_ancestor_id.
+    """
+    all_folders = await prisma.models.LibraryFolder.prisma().find_many(
+        where={"userId": user_id, "isDeleted": False},
+    )
+    parent_map = {f.id: f.parentId for f in all_folders}
+
+    visited: set[str] = set()
+    current_id: str | None = folder_id
+    while current_id:
+        if current_id == potential_ancestor_id:
+            return True
+        if current_id in visited:
+            break  # cycle detected
+        visited.add(current_id)
+        current_id = parent_map.get(current_id)
+
+    return False
+
+
 async def delete_folder(
     folder_id: str,
     user_id: str,
@@ -1481,6 +1473,67 @@ async def bulk_move_agents_to_folder(
     return [library_model.LibraryAgent.from_db(agent) for agent in agents]
 
 
+def collect_tree_ids(
+    nodes: list[library_model.LibraryFolderTree],
+    visited: set[str] | None = None,
+) -> list[str]:
+    """Collect all folder IDs from a folder tree."""
+    if visited is None:
+        visited = set()
+    ids: list[str] = []
+    for n in nodes:
+        if n.id in visited:
+            continue
+        visited.add(n.id)
+        ids.append(n.id)
+        ids.extend(collect_tree_ids(n.children, visited))
+    return ids
+
+
+async def get_folder_agent_summaries(
+    user_id: str, folder_id: str
+) -> list[dict[str, str | None]]:
+    """Get a lightweight list of agents in a folder (id, name, description)."""
+    all_agents: list[library_model.LibraryAgent] = []
+    for page in itertools.count(1):
+        resp = await list_library_agents(
+            user_id=user_id, folder_id=folder_id, page=page
+        )
+        all_agents.extend(resp.agents)
+        if page >= resp.pagination.total_pages:
+            break
+    return [
+        {"id": a.id, "name": a.name, "description": a.description} for a in all_agents
+    ]
+
+
+async def get_root_agent_summaries(
+    user_id: str,
+) -> list[dict[str, str | None]]:
+    """Get a lightweight list of root-level agents (folderId IS NULL)."""
+    all_agents: list[library_model.LibraryAgent] = []
+    for page in itertools.count(1):
+        resp = await list_library_agents(
+            user_id=user_id, include_root_only=True, page=page
+        )
+        all_agents.extend(resp.agents)
+        if page >= resp.pagination.total_pages:
+            break
+    return [
+        {"id": a.id, "name": a.name, "description": a.description} for a in all_agents
+    ]
+
+
+async def get_folder_agents_map(
+    user_id: str, folder_ids: list[str]
+) -> dict[str, list[dict[str, str | None]]]:
+    """Get agent summaries for multiple folders concurrently."""
+    results = await asyncio.gather(
+        *(get_folder_agent_summaries(user_id, fid) for fid in folder_ids)
+    )
+    return dict(zip(folder_ids, results))
+
+
 ##############################################
 ########### Presets DB Functions #############
 ##############################################

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

@@ -4,7 +4,6 @@ import prisma.enums
 import prisma.models
 import pytest
 
-import backend.api.features.store.exceptions
 from backend.data.db import connect
 from backend.data.includes import library_agent_include
 
@@ -218,7 +217,7 @@ async def test_add_agent_to_library_not_found(mocker):
     )
 
     # Call function and verify exception
-    with pytest.raises(backend.api.features.store.exceptions.AgentNotFoundError):
+    with pytest.raises(db.NotFoundError):
         await db.add_store_agent_to_library("version123", "test-user")
 
     # Verify mock called correctly

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

@@ -220,8 +220,6 @@ class LibraryAgent(pydantic.BaseModel):
     def from_db(
         agent: prisma.models.LibraryAgent,
         sub_graphs: Optional[list[prisma.models.AgentGraph]] = None,
-        store_listing: Optional[prisma.models.StoreListing] = None,
-        profile: Optional[prisma.models.Profile] = None,
     ) -> "LibraryAgent":
         """
         Factory method that constructs a LibraryAgent from a Prisma LibraryAgent
@@ -306,19 +304,33 @@ class LibraryAgent(pydantic.BaseModel):
         can_access_graph = agent.AgentGraph.userId == agent.userId
         is_latest_version = True
 
-        marketplace_listing_data = None
-        if store_listing and store_listing.ActiveVersion and profile:
-            creator_data = MarketplaceListingCreator(
-                name=profile.name,
-                id=profile.id,
-                slug=profile.username,
-            )
-            marketplace_listing_data = MarketplaceListing(
+        # NOTE: this access pattern is designed for use with
+        # `library_agent_include(..., include_store_listing=True)`
+        active_listing = (
+            agent.AgentGraph.StoreListingVersions[0]
+            if agent.AgentGraph.StoreListingVersions
+            else None
+        )
+        store_listing = active_listing.StoreListing if active_listing else None
+        active_listing = store_listing.ActiveVersion if store_listing else None
+        creator_profile = store_listing.CreatorProfile if store_listing else None
+        marketplace_listing_info = (
+            MarketplaceListing(
                 id=store_listing.id,
-                name=store_listing.ActiveVersion.name,
+                name=active_listing.name,
                 slug=store_listing.slug,
-                creator=creator_data,
+                creator=MarketplaceListingCreator(
+                    name=creator_profile.name,
+                    id=creator_profile.id,
+                    slug=creator_profile.username,
+                ),
             )
+            if store_listing
+            and active_listing
+            and creator_profile
+            and not store_listing.isDeleted
+            else None
+        )
 
         return LibraryAgent(
             id=agent.id,
@@ -355,7 +367,7 @@ class LibraryAgent(pydantic.BaseModel):
             folder_name=agent.Folder.name if agent.Folder else None,
             recommended_schedule_cron=agent.AgentGraph.recommendedScheduleCron,
             settings=_parse_settings(agent.settings),
-            marketplace_listing=marketplace_listing_data,
+            marketplace_listing=marketplace_listing_info,
         )
 
 

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

@@ -24,7 +24,7 @@ from backend.blocks.mcp.oauth import MCPOAuthHandler
 from backend.data.model import OAuth2Credentials
 from backend.integrations.creds_manager import IntegrationCredentialsManager
 from backend.integrations.providers import ProviderName
-from backend.util.request import HTTPClientError, Requests, validate_url
+from backend.util.request import HTTPClientError, Requests, validate_url_host
 from backend.util.settings import Settings
 
 logger = logging.getLogger(__name__)
@@ -80,7 +80,7 @@ async def discover_tools(
     """
     # Validate URL to prevent SSRF — blocks loopback and private IP ranges.
     try:
-        await validate_url(request.server_url, trusted_origins=[])
+        await validate_url_host(request.server_url)
     except ValueError as e:
         raise fastapi.HTTPException(status_code=400, detail=f"Invalid server URL: {e}")
 
@@ -167,7 +167,7 @@ async def mcp_oauth_login(
     """
     # Validate URL to prevent SSRF — blocks loopback and private IP ranges.
     try:
-        await validate_url(request.server_url, trusted_origins=[])
+        await validate_url_host(request.server_url)
     except ValueError as e:
         raise fastapi.HTTPException(status_code=400, detail=f"Invalid server URL: {e}")
 
@@ -187,7 +187,7 @@ async def mcp_oauth_login(
 
         # Validate the auth server URL from metadata to prevent SSRF.
         try:
-            await validate_url(auth_server_url, trusted_origins=[])
+            await validate_url_host(auth_server_url)
         except ValueError as e:
             raise fastapi.HTTPException(
                 status_code=400,
@@ -234,7 +234,7 @@ async def mcp_oauth_login(
     if registration_endpoint:
         # Validate the registration endpoint to prevent SSRF via metadata.
         try:
-            await validate_url(registration_endpoint, trusted_origins=[])
+            await validate_url_host(registration_endpoint)
         except ValueError:
             pass  # Skip registration, fall back to default client_id
         else:
@@ -429,7 +429,7 @@ async def mcp_store_token(
 
     # Validate URL to prevent SSRF — blocks loopback and private IP ranges.
     try:
-        await validate_url(request.server_url, trusted_origins=[])
+        await validate_url_host(request.server_url)
     except ValueError as e:
         raise fastapi.HTTPException(status_code=400, detail=f"Invalid server URL: {e}")
 

autogpt_platform/backend/backend/api/features/mcp/test_routes.py

@@ -32,9 +32,9 @@ async def client():
 
 @pytest.fixture(autouse=True)
 def _bypass_ssrf_validation():
-    """Bypass validate_url in all route tests (test URLs don't resolve)."""
+    """Bypass validate_url_host in all route tests (test URLs don't resolve)."""
     with patch(
-        "backend.api.features.mcp.routes.validate_url",
+        "backend.api.features.mcp.routes.validate_url_host",
         new_callable=AsyncMock,
     ):
         yield
@@ -282,7 +282,7 @@ class TestOAuthLogin:
             )
             mock_register.return_value = {
                 "client_id": "registered-client-id",
-                "client_secret": "registered-secret",
+                "client_secret": "registered-secret",  # pragma: allowlist secret
             }
             mock_cm.store.store_state_token = AsyncMock(
                 return_value=("state-token-123", "code-challenge-abc")
@@ -383,7 +383,7 @@ class TestOAuthCallback:
                 "authorize_url": "https://auth.sentry.io/authorize",
                 "token_url": "https://auth.sentry.io/token",
                 "client_id": "test-client-id",
-                "client_secret": "test-secret",
+                "client_secret": "test-secret",  # pragma: allowlist secret
                 "server_url": "https://mcp.sentry.dev/mcp",
             }
             mock_state.scopes = ["openid"]
@@ -521,12 +521,12 @@ class TestStoreToken:
 
 
 class TestSSRFValidation:
-    """Verify that validate_url is enforced on all endpoints."""
+    """Verify that validate_url_host is enforced on all endpoints."""
 
     @pytest.mark.asyncio(loop_scope="session")
     async def test_discover_tools_ssrf_blocked(self, client):
         with patch(
-            "backend.api.features.mcp.routes.validate_url",
+            "backend.api.features.mcp.routes.validate_url_host",
             new_callable=AsyncMock,
             side_effect=ValueError("blocked loopback"),
         ):
@@ -541,7 +541,7 @@ class TestSSRFValidation:
     @pytest.mark.asyncio(loop_scope="session")
     async def test_oauth_login_ssrf_blocked(self, client):
         with patch(
-            "backend.api.features.mcp.routes.validate_url",
+            "backend.api.features.mcp.routes.validate_url_host",
             new_callable=AsyncMock,
             side_effect=ValueError("blocked private IP"),
         ):
@@ -556,7 +556,7 @@ class TestSSRFValidation:
     @pytest.mark.asyncio(loop_scope="session")
     async def test_store_token_ssrf_blocked(self, client):
         with patch(
-            "backend.api.features.mcp.routes.validate_url",
+            "backend.api.features.mcp.routes.validate_url_host",
             new_callable=AsyncMock,
             side_effect=ValueError("blocked loopback"),
         ):

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

@@ -1,5 +1,3 @@
-from typing import Literal
-
 from backend.util.cache import cached
 
 from . import db as store_db
@@ -23,7 +21,7 @@ def clear_all_caches():
 async def _get_cached_store_agents(
     featured: bool,
     creator: str | None,
-    sorted_by: Literal["rating", "runs", "name", "updated_at"] | None,
+    sorted_by: store_db.StoreAgentsSortOptions | None,
     search_query: str | None,
     category: str | None,
     page: int,
@@ -57,7 +55,7 @@ async def _get_cached_agent_details(
 async def _get_cached_store_creators(
     featured: bool,
     search_query: str | None,
-    sorted_by: Literal["agent_rating", "agent_runs", "num_agents"] | None,
+    sorted_by: store_db.StoreCreatorsSortOptions | None,
     page: int,
     page_size: int,
 ):
@@ -75,4 +73,4 @@ async def _get_cached_store_creators(
 @cached(maxsize=100, ttl_seconds=300, shared_cache=True)
 async def _get_cached_creator_details(username: str):
     """Cached helper to get creator details."""
-    return await store_db.get_store_creator_details(username=username.lower())
+    return await store_db.get_store_creator(username=username.lower())

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

@@ -7,7 +7,7 @@ import pytest
 from prisma import Prisma
 
 from . import db
-from .model import Profile
+from .model import ProfileUpdateRequest
 
 
 @pytest.fixture(autouse=True)
@@ -26,7 +26,7 @@ async def test_get_store_agents(mocker):
     mock_agents = [
         prisma.models.StoreAgent(
             listing_id="test-id",
-            storeListingVersionId="version123",
+            listing_version_id="version123",
             slug="test-agent",
             agent_name="Test Agent",
             agent_video=None,
@@ -40,11 +40,11 @@ async def test_get_store_agents(mocker):
             runs=10,
             rating=4.5,
             versions=["1.0"],
-            agentGraphVersions=["1"],
-            agentGraphId="test-graph-id",
+            graph_id="test-graph-id",
+            graph_versions=["1"],
             updated_at=datetime.now(),
             is_available=False,
-            useForOnboarding=False,
+            use_for_onboarding=False,
         )
     ]
 
@@ -68,10 +68,10 @@ async def test_get_store_agents(mocker):
 
 @pytest.mark.asyncio(loop_scope="session")
 async def test_get_store_agent_details(mocker):
-    # Mock data
+    # Mock data - StoreAgent view already contains the active version data
     mock_agent = prisma.models.StoreAgent(
         listing_id="test-id",
-        storeListingVersionId="version123",
+        listing_version_id="version123",
         slug="test-agent",
         agent_name="Test Agent",
         agent_video="video.mp4",
@@ -85,102 +85,38 @@ async def test_get_store_agent_details(mocker):
         runs=10,
         rating=4.5,
         versions=["1.0"],
-        agentGraphVersions=["1"],
-        agentGraphId="test-graph-id",
-        updated_at=datetime.now(),
-        is_available=False,
-        useForOnboarding=False,
-    )
-
-    # Mock active version agent (what we want to return for active version)
-    mock_active_agent = prisma.models.StoreAgent(
-        listing_id="test-id",
-        storeListingVersionId="active-version-id",
-        slug="test-agent",
-        agent_name="Test Agent Active",
-        agent_video="active_video.mp4",
-        agent_image=["active_image.jpg"],
-        featured=False,
-        creator_username="creator",
-        creator_avatar="avatar.jpg",
-        sub_heading="Test heading active",
-        description="Test description active",
-        categories=["test"],
-        runs=15,
-        rating=4.8,
-        versions=["1.0", "2.0"],
-        agentGraphVersions=["1", "2"],
-        agentGraphId="test-graph-id-active",
+        graph_id="test-graph-id",
+        graph_versions=["1"],
         updated_at=datetime.now(),
         is_available=True,
-        useForOnboarding=False,
+        use_for_onboarding=False,
     )
 
-    # Create a mock StoreListing result
-    mock_store_listing = mocker.MagicMock()
-    mock_store_listing.activeVersionId = "active-version-id"
-    mock_store_listing.hasApprovedVersion = True
-    mock_store_listing.ActiveVersion = mocker.MagicMock()
-    mock_store_listing.ActiveVersion.recommendedScheduleCron = None
-
-    # Mock StoreAgent prisma call - need to handle multiple calls
+    # Mock StoreAgent prisma call
     mock_store_agent = mocker.patch("prisma.models.StoreAgent.prisma")
-
-    # Set up side_effect to return different results for different calls
-    def mock_find_first_side_effect(*args, **kwargs):
-        where_clause = kwargs.get("where", {})
-        if "storeListingVersionId" in where_clause:
-            # Second call for active version
-            return mock_active_agent
-        else:
-            # First call for initial lookup
-            return mock_agent
-
-    mock_store_agent.return_value.find_first = mocker.AsyncMock(
-        side_effect=mock_find_first_side_effect
-    )
-
-    # Mock Profile prisma call
-    mock_profile = mocker.MagicMock()
-    mock_profile.userId = "user-id-123"
-    mock_profile_db = mocker.patch("prisma.models.Profile.prisma")
-    mock_profile_db.return_value.find_first = mocker.AsyncMock(
-        return_value=mock_profile
-    )
-
-    # Mock StoreListing prisma call
-    mock_store_listing_db = mocker.patch("prisma.models.StoreListing.prisma")
-    mock_store_listing_db.return_value.find_first = mocker.AsyncMock(
-        return_value=mock_store_listing
-    )
+    mock_store_agent.return_value.find_first = mocker.AsyncMock(return_value=mock_agent)
 
     # Call function
     result = await db.get_store_agent_details("creator", "test-agent")
 
-    # Verify results - should use active version data
+    # Verify results - constructed from the StoreAgent view
     assert result.slug == "test-agent"
-    assert result.agent_name == "Test Agent Active"  # From active version
-    assert result.active_version_id == "active-version-id"
+    assert result.agent_name == "Test Agent"
+    assert result.active_version_id == "version123"
     assert result.has_approved_version is True
-    assert (
-        result.store_listing_version_id == "active-version-id"
-    )  # Should be active version ID
+    assert result.store_listing_version_id == "version123"
+    assert result.graph_id == "test-graph-id"
+    assert result.runs == 10
+    assert result.rating == 4.5
 
-    # Verify mocks called correctly - now expecting 2 calls
-    assert mock_store_agent.return_value.find_first.call_count == 2
-
-    # Check the specific calls
-    calls = mock_store_agent.return_value.find_first.call_args_list
-    assert calls[0] == mocker.call(
+    # Verify single StoreAgent lookup
+    mock_store_agent.return_value.find_first.assert_called_once_with(
         where={"creator_username": "creator", "slug": "test-agent"}
     )
-    assert calls[1] == mocker.call(where={"storeListingVersionId": "active-version-id"})
-
-    mock_store_listing_db.return_value.find_first.assert_called_once()
 
 
 @pytest.mark.asyncio(loop_scope="session")
-async def test_get_store_creator_details(mocker):
+async def test_get_store_creator(mocker):
     # Mock data
     mock_creator_data = prisma.models.Creator(
         name="Test Creator",
@@ -202,7 +138,7 @@ async def test_get_store_creator_details(mocker):
     mock_creator.return_value.find_unique.return_value = mock_creator_data
 
     # Call function
-    result = await db.get_store_creator_details("creator")
+    result = await db.get_store_creator("creator")
 
     # Verify results
     assert result.username == "creator"
@@ -218,61 +154,110 @@ async def test_get_store_creator_details(mocker):
 
 @pytest.mark.asyncio(loop_scope="session")
 async def test_create_store_submission(mocker):
-    # Mock data
+    now = datetime.now()
+
+    # Mock agent graph (with no pending submissions) and user with profile
+    mock_profile = prisma.models.Profile(
+        id="profile-id",
+        userId="user-id",
+        name="Test User",
+        username="testuser",
+        description="Test",
+        isFeatured=False,
+        links=[],
+        createdAt=now,
+        updatedAt=now,
+    )
+    mock_user = prisma.models.User(
+        id="user-id",
+        email="test@example.com",
+        createdAt=now,
+        updatedAt=now,
+        Profile=[mock_profile],
+        emailVerified=True,
+        metadata="{}",  # type: ignore[reportArgumentType]
+        integrations="",
+        maxEmailsPerDay=1,
+        notifyOnAgentRun=True,
+        notifyOnZeroBalance=True,
+        notifyOnLowBalance=True,
+        notifyOnBlockExecutionFailed=True,
+        notifyOnContinuousAgentError=True,
+        notifyOnDailySummary=True,
+        notifyOnWeeklySummary=True,
+        notifyOnMonthlySummary=True,
+        notifyOnAgentApproved=True,
+        notifyOnAgentRejected=True,
+        timezone="Europe/Delft",
+    )
     mock_agent = prisma.models.AgentGraph(
         id="agent-id",
         version=1,
         userId="user-id",
-        createdAt=datetime.now(),
+        createdAt=now,
         isActive=True,
+        StoreListingVersions=[],
+        User=mock_user,
     )
 
-    mock_listing = prisma.models.StoreListing(
+    # Mock the created StoreListingVersion (returned by create)
+    mock_store_listing_obj = prisma.models.StoreListing(
         id="listing-id",
-        createdAt=datetime.now(),
-        updatedAt=datetime.now(),
+        createdAt=now,
+        updatedAt=now,
         isDeleted=False,
         hasApprovedVersion=False,
         slug="test-agent",
         agentGraphId="agent-id",
-        agentGraphVersion=1,
         owningUserId="user-id",
-        Versions=[
-            prisma.models.StoreListingVersion(
-                id="version-id",
-                agentGraphId="agent-id",
-                agentGraphVersion=1,
-                name="Test Agent",
-                description="Test description",
-                createdAt=datetime.now(),
-                updatedAt=datetime.now(),
-                subHeading="Test heading",
-                imageUrls=["image.jpg"],
-                categories=["test"],
-                isFeatured=False,
-                isDeleted=False,
-                version=1,
-                storeListingId="listing-id",
-                submissionStatus=prisma.enums.SubmissionStatus.PENDING,
-                isAvailable=True,
-            )
-        ],
         useForOnboarding=False,
     )
+    mock_version = prisma.models.StoreListingVersion(
+        id="version-id",
+        agentGraphId="agent-id",
+        agentGraphVersion=1,
+        name="Test Agent",
+        description="Test description",
+        createdAt=now,
+        updatedAt=now,
+        subHeading="",
+        imageUrls=[],
+        categories=[],
+        isFeatured=False,
+        isDeleted=False,
+        version=1,
+        storeListingId="listing-id",
+        submissionStatus=prisma.enums.SubmissionStatus.PENDING,
+        isAvailable=True,
+        submittedAt=now,
+        StoreListing=mock_store_listing_obj,
+    )
 
     # Mock prisma calls
     mock_agent_graph = mocker.patch("prisma.models.AgentGraph.prisma")
     mock_agent_graph.return_value.find_first = mocker.AsyncMock(return_value=mock_agent)
 
-    mock_store_listing = mocker.patch("prisma.models.StoreListing.prisma")
-    mock_store_listing.return_value.find_first = mocker.AsyncMock(return_value=None)
-    mock_store_listing.return_value.create = mocker.AsyncMock(return_value=mock_listing)
+    # Mock transaction context manager
+    mock_tx = mocker.MagicMock()
+    mocker.patch(
+        "backend.api.features.store.db.transaction",
+        return_value=mocker.AsyncMock(
+            __aenter__=mocker.AsyncMock(return_value=mock_tx),
+            __aexit__=mocker.AsyncMock(return_value=False),
+        ),
+    )
+
+    mock_sl = mocker.patch("prisma.models.StoreListing.prisma")
+    mock_sl.return_value.find_unique = mocker.AsyncMock(return_value=None)
+
+    mock_slv = mocker.patch("prisma.models.StoreListingVersion.prisma")
+    mock_slv.return_value.create = mocker.AsyncMock(return_value=mock_version)
 
     # Call function
     result = await db.create_store_submission(
         user_id="user-id",
-        agent_id="agent-id",
-        agent_version=1,
+        graph_id="agent-id",
+        graph_version=1,
         slug="test-agent",
         name="Test Agent",
         description="Test description",
@@ -281,11 +266,11 @@ async def test_create_store_submission(mocker):
     # Verify results
     assert result.name == "Test Agent"
     assert result.description == "Test description"
-    assert result.store_listing_version_id == "version-id"
+    assert result.listing_version_id == "version-id"
 
     # Verify mocks called correctly
     mock_agent_graph.return_value.find_first.assert_called_once()
-    mock_store_listing.return_value.create.assert_called_once()
+    mock_slv.return_value.create.assert_called_once()
 
 
 @pytest.mark.asyncio(loop_scope="session")
@@ -312,13 +297,12 @@ async def test_update_profile(mocker):
     mock_profile_db.return_value.update = mocker.AsyncMock(return_value=mock_profile)
 
     # Test data
-    profile = Profile(
+    profile = ProfileUpdateRequest(
         name="Test Creator",
         username="creator",
         description="Test description",
         links=["link1"],
         avatar_url="avatar.jpg",
-        is_featured=False,
     )
 
     # Call function
@@ -389,7 +373,7 @@ async def test_get_store_agents_with_search_and_filters_parameterized():
         creators=["creator1'; DROP TABLE Users; --", "creator2"],
         category="AI'; DELETE FROM StoreAgent; --",
         featured=True,
-        sorted_by="rating",
+        sorted_by=db.StoreAgentsSortOptions.RATING,
         page=1,
         page_size=20,
     )

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

@@ -57,12 +57,6 @@ class StoreError(ValueError):
     pass
 
 
-class AgentNotFoundError(NotFoundError):
-    """Raised when an agent is not found"""
-
-    pass
-
-
 class CreatorNotFoundError(NotFoundError):
     """Raised when a creator is not found"""
 

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

@@ -568,7 +568,7 @@ async def hybrid_search(
             SELECT uce."contentId" as "storeListingVersionId"
             FROM {{schema_prefix}}"UnifiedContentEmbedding" uce
             INNER JOIN {{schema_prefix}}"StoreAgent" sa
-                ON uce."contentId" = sa."storeListingVersionId"
+                ON uce."contentId" = sa.listing_version_id
             WHERE uce."contentType" = 'STORE_AGENT'::{{schema_prefix}}"ContentType"
             AND uce."userId" IS NULL
             AND uce.search @@ plainto_tsquery('english', {query_param})
@@ -582,7 +582,7 @@ async def hybrid_search(
                 SELECT uce."contentId", uce.embedding
                 FROM {{schema_prefix}}"UnifiedContentEmbedding" uce
                 INNER JOIN {{schema_prefix}}"StoreAgent" sa
-                    ON uce."contentId" = sa."storeListingVersionId"
+                    ON uce."contentId" = sa.listing_version_id
                 WHERE uce."contentType" = 'STORE_AGENT'::{{schema_prefix}}"ContentType"
                 AND uce."userId" IS NULL
                 AND {where_clause}
@@ -605,7 +605,7 @@ async def hybrid_search(
                 sa.featured,
                 sa.is_available,
                 sa.updated_at,
-                sa."agentGraphId",
+                sa.graph_id,
                 -- Searchable text for BM25 reranking
                 COALESCE(sa.agent_name, '') || ' ' || COALESCE(sa.sub_heading, '') || ' ' || COALESCE(sa.description, '') as searchable_text,
                 -- Semantic score
@@ -627,9 +627,9 @@ async def hybrid_search(
                 sa.runs as popularity_raw
             FROM candidates c
             INNER JOIN {{schema_prefix}}"StoreAgent" sa
-                ON c."storeListingVersionId" = sa."storeListingVersionId"
+                ON c."storeListingVersionId" = sa.listing_version_id
             INNER JOIN {{schema_prefix}}"UnifiedContentEmbedding" uce
-                ON sa."storeListingVersionId" = uce."contentId"
+                ON sa.listing_version_id = uce."contentId"
                 AND uce."contentType" = 'STORE_AGENT'::{{schema_prefix}}"ContentType"
         ),
         max_vals AS (
@@ -665,7 +665,7 @@ async def hybrid_search(
                 featured,
                 is_available,
                 updated_at,
-                "agentGraphId",
+                graph_id,
                 searchable_text,
                 semantic_score,
                 lexical_score,

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

@@ -1,11 +1,14 @@
 import datetime
-from typing import List
+from typing import TYPE_CHECKING, List, Self
 
 import prisma.enums
 import pydantic
 
 from backend.util.models import Pagination
 
+if TYPE_CHECKING:
+    import prisma.models
+
 
 class ChangelogEntry(pydantic.BaseModel):
     version: str
@@ -13,9 +16,9 @@ class ChangelogEntry(pydantic.BaseModel):
     date: datetime.datetime
 
 
-class MyAgent(pydantic.BaseModel):
-    agent_id: str
-    agent_version: int
+class MyUnpublishedAgent(pydantic.BaseModel):
+    graph_id: str
+    graph_version: int
     agent_name: str
     agent_image: str | None = None
     description: str
@@ -23,8 +26,8 @@ class MyAgent(pydantic.BaseModel):
     recommended_schedule_cron: str | None = None
 
 
-class MyAgentsResponse(pydantic.BaseModel):
-    agents: list[MyAgent]
+class MyUnpublishedAgentsResponse(pydantic.BaseModel):
+    agents: list[MyUnpublishedAgent]
     pagination: Pagination
 
 
@@ -40,6 +43,21 @@ class StoreAgent(pydantic.BaseModel):
     rating: float
     agent_graph_id: str
 
+    @classmethod
+    def from_db(cls, agent: "prisma.models.StoreAgent") -> "StoreAgent":
+        return cls(
+            slug=agent.slug,
+            agent_name=agent.agent_name,
+            agent_image=agent.agent_image[0] if agent.agent_image else "",
+            creator=agent.creator_username or "Needs Profile",
+            creator_avatar=agent.creator_avatar or "",
+            sub_heading=agent.sub_heading,
+            description=agent.description,
+            runs=agent.runs,
+            rating=agent.rating,
+            agent_graph_id=agent.graph_id,
+        )
+
 
 class StoreAgentsResponse(pydantic.BaseModel):
     agents: list[StoreAgent]
@@ -62,81 +80,197 @@ class StoreAgentDetails(pydantic.BaseModel):
     runs: int
     rating: float
     versions: list[str]
-    agentGraphVersions: list[str]
-    agentGraphId: str
+    graph_id: str
+    graph_versions: list[str]
     last_updated: datetime.datetime
     recommended_schedule_cron: str | None = None
 
-    active_version_id: str | None = None
-    has_approved_version: bool = False
+    active_version_id: str
+    has_approved_version: bool
 
     # Optional changelog data when include_changelog=True
     changelog: list[ChangelogEntry] | None = None
 
+    @classmethod
+    def from_db(cls, agent: "prisma.models.StoreAgent") -> "StoreAgentDetails":
+        return cls(
+            store_listing_version_id=agent.listing_version_id,
+            slug=agent.slug,
+            agent_name=agent.agent_name,
+            agent_video=agent.agent_video or "",
+            agent_output_demo=agent.agent_output_demo or "",
+            agent_image=agent.agent_image,
+            creator=agent.creator_username or "",
+            creator_avatar=agent.creator_avatar or "",
+            sub_heading=agent.sub_heading,
+            description=agent.description,
+            categories=agent.categories,
+            runs=agent.runs,
+            rating=agent.rating,
+            versions=agent.versions,
+            graph_id=agent.graph_id,
+            graph_versions=agent.graph_versions,
+            last_updated=agent.updated_at,
+            recommended_schedule_cron=agent.recommended_schedule_cron,
+            active_version_id=agent.listing_version_id,
+            has_approved_version=True,  # StoreAgent view only has approved agents
+        )
+
+
+class ProfileUpdateRequest(pydantic.BaseModel):
+    """Marketplace user profile (only attributes that the user can update)"""
+
+    username: str | None = None
+    name: str | None = None
+    description: str | None = None
+    avatar_url: str | None = None
+    links: list[str] | None = None
+
+
+class ProfileDetails(pydantic.BaseModel):
+    """Marketplace user profile (including read-only fields)"""
 
-class Creator(pydantic.BaseModel):
-    name: str
     username: str
+    name: str
     description: str
-    avatar_url: str
-    num_agents: int
-    agent_rating: float
-    agent_runs: int
+    avatar_url: str | None
+    links: list[str]
     is_featured: bool
 
+    @classmethod
+    def from_db(cls, profile: "prisma.models.Profile") -> "ProfileDetails":
+        return cls(
+            name=profile.name,
+            username=profile.username,
+            avatar_url=profile.avatarUrl,
+            description=profile.description,
+            links=profile.links,
+            is_featured=profile.isFeatured,
+        )
+
+
+class CreatorDetails(ProfileDetails):
+    """Marketplace creator profile details, including aggregated stats"""
+
+    num_agents: int
+    agent_runs: int
+    agent_rating: float
+    top_categories: list[str]
+
+    @classmethod
+    def from_db(cls, creator: "prisma.models.Creator") -> "CreatorDetails":  # type: ignore[override]
+        return cls(
+            name=creator.name,
+            username=creator.username,
+            avatar_url=creator.avatar_url,
+            description=creator.description,
+            links=creator.links,
+            is_featured=creator.is_featured,
+            num_agents=creator.num_agents,
+            agent_runs=creator.agent_runs,
+            agent_rating=creator.agent_rating,
+            top_categories=creator.top_categories,
+        )
+
 
 class CreatorsResponse(pydantic.BaseModel):
-    creators: List[Creator]
+    creators: List[CreatorDetails]
     pagination: Pagination
 
 
-class CreatorDetails(pydantic.BaseModel):
-    name: str
-    username: str
-    description: str
-    links: list[str]
-    avatar_url: str
-    agent_rating: float
-    agent_runs: int
-    top_categories: list[str]
-
-
-class Profile(pydantic.BaseModel):
-    name: str
-    username: str
-    description: str
-    links: list[str]
-    avatar_url: str
-    is_featured: bool = False
-
-
 class StoreSubmission(pydantic.BaseModel):
+    # From StoreListing:
     listing_id: str
-    agent_id: str
-    agent_version: int
+    user_id: str
+    slug: str
+
+    # From StoreListingVersion:
+    listing_version_id: str
+    listing_version: int
+    graph_id: str
+    graph_version: int
     name: str
     sub_heading: str
-    slug: str
     description: str
-    instructions: str | None = None
+    instructions: str | None
+    categories: list[str]
     image_urls: list[str]
-    date_submitted: datetime.datetime
-    status: prisma.enums.SubmissionStatus
-    runs: int
-    rating: float
-    store_listing_version_id: str | None = None
-    version: int | None = None  # Actual version number from the database
+    video_url: str | None
+    agent_output_demo_url: str | None
 
+    submitted_at: datetime.datetime | None
+    changes_summary: str | None
+    status: prisma.enums.SubmissionStatus
+    reviewed_at: datetime.datetime | None = None
     reviewer_id: str | None = None
     review_comments: str | None = None  # External comments visible to creator
-    internal_comments: str | None = None  # Private notes for admin use only
-    reviewed_at: datetime.datetime | None = None
-    changes_summary: str | None = None
 
-    # Additional fields for editing
-    video_url: str | None = None
-    agent_output_demo_url: str | None = None
-    categories: list[str] = []
+    # Aggregated from AgentGraphExecutions and StoreListingReviews:
+    run_count: int = 0
+    review_count: int = 0
+    review_avg_rating: float = 0.0
+
+    @classmethod
+    def from_db(cls, _sub: "prisma.models.StoreSubmission") -> Self:
+        """Construct from the StoreSubmission Prisma view."""
+        return cls(
+            listing_id=_sub.listing_id,
+            user_id=_sub.user_id,
+            slug=_sub.slug,
+            listing_version_id=_sub.listing_version_id,
+            listing_version=_sub.listing_version,
+            graph_id=_sub.graph_id,
+            graph_version=_sub.graph_version,
+            name=_sub.name,
+            sub_heading=_sub.sub_heading,
+            description=_sub.description,
+            instructions=_sub.instructions,
+            categories=_sub.categories,
+            image_urls=_sub.image_urls,
+            video_url=_sub.video_url,
+            agent_output_demo_url=_sub.agent_output_demo_url,
+            submitted_at=_sub.submitted_at,
+            changes_summary=_sub.changes_summary,
+            status=_sub.status,
+            reviewed_at=_sub.reviewed_at,
+            reviewer_id=_sub.reviewer_id,
+            review_comments=_sub.review_comments,
+            run_count=_sub.run_count,
+            review_count=_sub.review_count,
+            review_avg_rating=_sub.review_avg_rating,
+        )
+
+    @classmethod
+    def from_listing_version(cls, _lv: "prisma.models.StoreListingVersion") -> Self:
+        """
+        Construct from the StoreListingVersion Prisma model (with StoreListing included)
+        """
+        if not (_l := _lv.StoreListing):
+            raise ValueError("StoreListingVersion must have included StoreListing")
+
+        return cls(
+            listing_id=_l.id,
+            user_id=_l.owningUserId,
+            slug=_l.slug,
+            listing_version_id=_lv.id,
+            listing_version=_lv.version,
+            graph_id=_lv.agentGraphId,
+            graph_version=_lv.agentGraphVersion,
+            name=_lv.name,
+            sub_heading=_lv.subHeading,
+            description=_lv.description,
+            instructions=_lv.instructions,
+            categories=_lv.categories,
+            image_urls=_lv.imageUrls,
+            video_url=_lv.videoUrl,
+            agent_output_demo_url=_lv.agentOutputDemoUrl,
+            submitted_at=_lv.submittedAt,
+            changes_summary=_lv.changesSummary,
+            status=_lv.submissionStatus,
+            reviewed_at=_lv.reviewedAt,
+            reviewer_id=_lv.reviewerId,
+            review_comments=_lv.reviewComments,
+        )
 
 
 class StoreSubmissionsResponse(pydantic.BaseModel):
@@ -144,33 +278,12 @@ class StoreSubmissionsResponse(pydantic.BaseModel):
     pagination: Pagination
 
 
-class StoreListingWithVersions(pydantic.BaseModel):
-    """A store listing with its version history"""
-
-    listing_id: str
-    slug: str
-    agent_id: str
-    agent_version: int
-    active_version_id: str | None = None
-    has_approved_version: bool = False
-    creator_email: str | None = None
-    latest_version: StoreSubmission | None = None
-    versions: list[StoreSubmission] = []
-
-
-class StoreListingsWithVersionsResponse(pydantic.BaseModel):
-    """Response model for listings with version history"""
-
-    listings: list[StoreListingWithVersions]
-    pagination: Pagination
-
-
 class StoreSubmissionRequest(pydantic.BaseModel):
-    agent_id: str = pydantic.Field(
-        ..., min_length=1, description="Agent ID cannot be empty"
+    graph_id: str = pydantic.Field(
+        ..., min_length=1, description="Graph ID cannot be empty"
     )
-    agent_version: int = pydantic.Field(
-        ..., gt=0, description="Agent version must be greater than 0"
+    graph_version: int = pydantic.Field(
+        ..., gt=0, description="Graph version must be greater than 0"
     )
     slug: str
     name: str
@@ -198,12 +311,42 @@ class StoreSubmissionEditRequest(pydantic.BaseModel):
     recommended_schedule_cron: str | None = None
 
 
-class ProfileDetails(pydantic.BaseModel):
-    name: str
-    username: str
-    description: str
-    links: list[str]
-    avatar_url: str | None = None
+class StoreSubmissionAdminView(StoreSubmission):
+    internal_comments: str | None  # Private admin notes
+
+    @classmethod
+    def from_db(cls, _sub: "prisma.models.StoreSubmission") -> Self:
+        return cls(
+            **StoreSubmission.from_db(_sub).model_dump(),
+            internal_comments=_sub.internal_comments,
+        )
+
+    @classmethod
+    def from_listing_version(cls, _lv: "prisma.models.StoreListingVersion") -> Self:
+        return cls(
+            **StoreSubmission.from_listing_version(_lv).model_dump(),
+            internal_comments=_lv.internalComments,
+        )
+
+
+class StoreListingWithVersionsAdminView(pydantic.BaseModel):
+    """A store listing with its version history"""
+
+    listing_id: str
+    graph_id: str
+    slug: str
+    active_listing_version_id: str | None = None
+    has_approved_version: bool = False
+    creator_email: str | None = None
+    latest_version: StoreSubmissionAdminView | None = None
+    versions: list[StoreSubmissionAdminView] = []
+
+
+class StoreListingsWithVersionsAdminViewResponse(pydantic.BaseModel):
+    """Response model for listings with version history"""
+
+    listings: list[StoreListingWithVersionsAdminView]
+    pagination: Pagination
 
 
 class StoreReview(pydantic.BaseModel):

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

@@ -1,203 +0,0 @@
-import datetime
-
-import prisma.enums
-
-from . import model as store_model
-
-
-def test_pagination():
-    pagination = store_model.Pagination(
-        total_items=100, total_pages=5, current_page=2, page_size=20
-    )
-    assert pagination.total_items == 100
-    assert pagination.total_pages == 5
-    assert pagination.current_page == 2
-    assert pagination.page_size == 20
-
-
-def test_store_agent():
-    agent = store_model.StoreAgent(
-        slug="test-agent",
-        agent_name="Test Agent",
-        agent_image="test.jpg",
-        creator="creator1",
-        creator_avatar="avatar.jpg",
-        sub_heading="Test subheading",
-        description="Test description",
-        runs=50,
-        rating=4.5,
-        agent_graph_id="test-graph-id",
-    )
-    assert agent.slug == "test-agent"
-    assert agent.agent_name == "Test Agent"
-    assert agent.runs == 50
-    assert agent.rating == 4.5
-    assert agent.agent_graph_id == "test-graph-id"
-
-
-def test_store_agents_response():
-    response = store_model.StoreAgentsResponse(
-        agents=[
-            store_model.StoreAgent(
-                slug="test-agent",
-                agent_name="Test Agent",
-                agent_image="test.jpg",
-                creator="creator1",
-                creator_avatar="avatar.jpg",
-                sub_heading="Test subheading",
-                description="Test description",
-                runs=50,
-                rating=4.5,
-                agent_graph_id="test-graph-id",
-            )
-        ],
-        pagination=store_model.Pagination(
-            total_items=1, total_pages=1, current_page=1, page_size=20
-        ),
-    )
-    assert len(response.agents) == 1
-    assert response.pagination.total_items == 1
-
-
-def test_store_agent_details():
-    details = store_model.StoreAgentDetails(
-        store_listing_version_id="version123",
-        slug="test-agent",
-        agent_name="Test Agent",
-        agent_video="video.mp4",
-        agent_output_demo="demo.mp4",
-        agent_image=["image1.jpg", "image2.jpg"],
-        creator="creator1",
-        creator_avatar="avatar.jpg",
-        sub_heading="Test subheading",
-        description="Test description",
-        categories=["cat1", "cat2"],
-        runs=50,
-        rating=4.5,
-        versions=["1.0", "2.0"],
-        agentGraphVersions=["1", "2"],
-        agentGraphId="test-graph-id",
-        last_updated=datetime.datetime.now(),
-    )
-    assert details.slug == "test-agent"
-    assert len(details.agent_image) == 2
-    assert len(details.categories) == 2
-    assert len(details.versions) == 2
-
-
-def test_creator():
-    creator = store_model.Creator(
-        agent_rating=4.8,
-        agent_runs=1000,
-        name="Test Creator",
-        username="creator1",
-        description="Test description",
-        avatar_url="avatar.jpg",
-        num_agents=5,
-        is_featured=False,
-    )
-    assert creator.name == "Test Creator"
-    assert creator.num_agents == 5
-
-
-def test_creators_response():
-    response = store_model.CreatorsResponse(
-        creators=[
-            store_model.Creator(
-                agent_rating=4.8,
-                agent_runs=1000,
-                name="Test Creator",
-                username="creator1",
-                description="Test description",
-                avatar_url="avatar.jpg",
-                num_agents=5,
-                is_featured=False,
-            )
-        ],
-        pagination=store_model.Pagination(
-            total_items=1, total_pages=1, current_page=1, page_size=20
-        ),
-    )
-    assert len(response.creators) == 1
-    assert response.pagination.total_items == 1
-
-
-def test_creator_details():
-    details = store_model.CreatorDetails(
-        name="Test Creator",
-        username="creator1",
-        description="Test description",
-        links=["link1.com", "link2.com"],
-        avatar_url="avatar.jpg",
-        agent_rating=4.8,
-        agent_runs=1000,
-        top_categories=["cat1", "cat2"],
-    )
-    assert details.name == "Test Creator"
-    assert len(details.links) == 2
-    assert details.agent_rating == 4.8
-    assert len(details.top_categories) == 2
-
-
-def test_store_submission():
-    submission = store_model.StoreSubmission(
-        listing_id="listing123",
-        agent_id="agent123",
-        agent_version=1,
-        sub_heading="Test subheading",
-        name="Test Agent",
-        slug="test-agent",
-        description="Test description",
-        image_urls=["image1.jpg", "image2.jpg"],
-        date_submitted=datetime.datetime(2023, 1, 1),
-        status=prisma.enums.SubmissionStatus.PENDING,
-        runs=50,
-        rating=4.5,
-    )
-    assert submission.name == "Test Agent"
-    assert len(submission.image_urls) == 2
-    assert submission.status == prisma.enums.SubmissionStatus.PENDING
-
-
-def test_store_submissions_response():
-    response = store_model.StoreSubmissionsResponse(
-        submissions=[
-            store_model.StoreSubmission(
-                listing_id="listing123",
-                agent_id="agent123",
-                agent_version=1,
-                sub_heading="Test subheading",
-                name="Test Agent",
-                slug="test-agent",
-                description="Test description",
-                image_urls=["image1.jpg"],
-                date_submitted=datetime.datetime(2023, 1, 1),
-                status=prisma.enums.SubmissionStatus.PENDING,
-                runs=50,
-                rating=4.5,
-            )
-        ],
-        pagination=store_model.Pagination(
-            total_items=1, total_pages=1, current_page=1, page_size=20
-        ),
-    )
-    assert len(response.submissions) == 1
-    assert response.pagination.total_items == 1
-
-
-def test_store_submission_request():
-    request = store_model.StoreSubmissionRequest(
-        agent_id="agent123",
-        agent_version=1,
-        slug="test-agent",
-        name="Test Agent",
-        sub_heading="Test subheading",
-        video_url="video.mp4",
-        image_urls=["image1.jpg", "image2.jpg"],
-        description="Test description",
-        categories=["cat1", "cat2"],
-    )
-    assert request.agent_id == "agent123"
-    assert request.agent_version == 1
-    assert len(request.image_urls) == 2
-    assert len(request.categories) == 2

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

@@ -1,16 +1,17 @@
 import logging
 import tempfile
-import typing
 import urllib.parse
-from typing import Literal
 
 import autogpt_libs.auth
 import fastapi
 import fastapi.responses
 import prisma.enums
+from fastapi import Query, Security
+from pydantic import BaseModel
 
 import backend.data.graph
 import backend.util.json
+from backend.util.exceptions import NotFoundError
 from backend.util.models import Pagination
 
 from . import cache as store_cache
@@ -34,22 +35,15 @@ router = fastapi.APIRouter()
     "/profile",
     summary="Get user profile",
     tags=["store", "private"],
-    dependencies=[fastapi.Security(autogpt_libs.auth.requires_user)],
-    response_model=store_model.ProfileDetails,
+    dependencies=[Security(autogpt_libs.auth.requires_user)],
 )
 async def get_profile(
-    user_id: str = fastapi.Security(autogpt_libs.auth.get_user_id),
-):
-    """
-    Get the profile details for the authenticated user.
-    Cached for 1 hour per user.
-    """
+    user_id: str = Security(autogpt_libs.auth.get_user_id),
+) -> store_model.ProfileDetails:
+    """Get the profile details for the authenticated user."""
     profile = await store_db.get_user_profile(user_id)
     if profile is None:
-        return fastapi.responses.JSONResponse(
-            status_code=404,
-            content={"detail": "Profile not found"},
-        )
+        raise NotFoundError("User does not have a profile yet")
     return profile
 
 
@@ -57,98 +51,17 @@ async def get_profile(
     "/profile",
     summary="Update user profile",
     tags=["store", "private"],
-    dependencies=[fastapi.Security(autogpt_libs.auth.requires_user)],
-    response_model=store_model.CreatorDetails,
+    dependencies=[Security(autogpt_libs.auth.requires_user)],
 )
 async def update_or_create_profile(
-    profile: store_model.Profile,
-    user_id: str = fastapi.Security(autogpt_libs.auth.get_user_id),
-):
-    """
-    Update the store profile for the authenticated user.
-
-    Args:
-        profile (Profile): The updated profile details
-        user_id (str): ID of the authenticated user
-
-    Returns:
-        CreatorDetails: The updated profile
-
-    Raises:
-        HTTPException: If there is an error updating the profile
-    """
+    profile: store_model.ProfileUpdateRequest,
+    user_id: str = Security(autogpt_libs.auth.get_user_id),
+) -> store_model.ProfileDetails:
+    """Update the store profile for the authenticated user."""
     updated_profile = await store_db.update_profile(user_id=user_id, profile=profile)
     return updated_profile
 
 
-##############################################
-############### Agent Endpoints ##############
-##############################################
-
-
-@router.get(
-    "/agents",
-    summary="List store agents",
-    tags=["store", "public"],
-    response_model=store_model.StoreAgentsResponse,
-)
-async def get_agents(
-    featured: bool = False,
-    creator: str | None = None,
-    sorted_by: Literal["rating", "runs", "name", "updated_at"] | None = None,
-    search_query: str | None = None,
-    category: str | None = None,
-    page: int = 1,
-    page_size: int = 20,
-):
-    """
-    Get a paginated list of agents from the store with optional filtering and sorting.
-
-    Args:
-        featured (bool, optional): Filter to only show featured agents. Defaults to False.
-        creator (str | None, optional): Filter agents by creator username. Defaults to None.
-        sorted_by (str | None, optional): Sort agents by "runs" or "rating". Defaults to None.
-        search_query (str | None, optional): Search agents by name, subheading and description. Defaults to None.
-        category (str | None, optional): Filter agents by category. Defaults to None.
-        page (int, optional): Page number for pagination. Defaults to 1.
-        page_size (int, optional): Number of agents per page. Defaults to 20.
-
-    Returns:
-        StoreAgentsResponse: Paginated list of agents matching the filters
-
-    Raises:
-        HTTPException: If page or page_size are less than 1
-
-    Used for:
-    - Home Page Featured Agents
-    - Home Page Top Agents
-    - Search Results
-    - Agent Details - Other Agents By Creator
-    - Agent Details - Similar Agents
-    - Creator Details - Agents By Creator
-    """
-    if page < 1:
-        raise fastapi.HTTPException(
-            status_code=422, detail="Page must be greater than 0"
-        )
-
-    if page_size < 1:
-        raise fastapi.HTTPException(
-            status_code=422, detail="Page size must be greater than 0"
-        )
-
-    agents = await store_cache._get_cached_store_agents(
-        featured=featured,
-        creator=creator,
-        sorted_by=sorted_by,
-        search_query=search_query,
-        category=category,
-        page=page,
-        page_size=page_size,
-    )
-    return agents
-
-
 ##############################################
 ############### Search Endpoints #############
 ##############################################
@@ -158,60 +71,30 @@ async def get_agents(
     "/search",
     summary="Unified search across all content types",
     tags=["store", "public"],
-    response_model=store_model.UnifiedSearchResponse,
 )
 async def unified_search(
     query: str,
-    content_types: list[str] | None = fastapi.Query(
+    content_types: list[prisma.enums.ContentType] | None = Query(
         default=None,
-        description="Content types to search: STORE_AGENT, BLOCK, DOCUMENTATION. If not specified, searches all.",
+        description="Content types to search. If not specified, searches all.",
     ),
-    page: int = 1,
-    page_size: int = 20,
-    user_id: str | None = fastapi.Security(
+    page: int = Query(ge=1, default=1),
+    page_size: int = Query(ge=1, default=20),
+    user_id: str | None = Security(
         autogpt_libs.auth.get_optional_user_id, use_cache=False
     ),
-):
+) -> store_model.UnifiedSearchResponse:
     """
-    Search across all content types (store agents, blocks, documentation) using hybrid search.
+    Search across all content types (marketplace agents, blocks, documentation)
+    using hybrid search.
 
     Combines semantic (embedding-based) and lexical (text-based) search for best results.
-
-    Args:
-        query: The search query string
-        content_types: Optional list of content types to filter by (STORE_AGENT, BLOCK, DOCUMENTATION)
-        page: Page number for pagination (default 1)
-        page_size: Number of results per page (default 20)
-        user_id: Optional authenticated user ID (for user-scoped content in future)
-
-    Returns:
-        UnifiedSearchResponse: Paginated list of search results with relevance scores
     """
-    if page < 1:
-        raise fastapi.HTTPException(
-            status_code=422, detail="Page must be greater than 0"
-        )
-
-    if page_size < 1:
-        raise fastapi.HTTPException(
-            status_code=422, detail="Page size must be greater than 0"
-        )
-
-    # Convert string content types to enum
-    content_type_enums: list[prisma.enums.ContentType] | None = None
-    if content_types:
-        try:
-            content_type_enums = [prisma.enums.ContentType(ct) for ct in content_types]
-        except ValueError as e:
-            raise fastapi.HTTPException(
-                status_code=422,
-                detail=f"Invalid content type. Valid values: STORE_AGENT, BLOCK, DOCUMENTATION. Error: {e}",
-            )
 
     # Perform unified hybrid search
     results, total = await store_hybrid_search.unified_hybrid_search(
         query=query,
-        content_types=content_type_enums,
+        content_types=content_types,
         user_id=user_id,
         page=page,
         page_size=page_size,
@@ -245,22 +128,69 @@ async def unified_search(
     )
 
 
+##############################################
+############### Agent Endpoints ##############
+##############################################
+
+
+@router.get(
+    "/agents",
+    summary="List store agents",
+    tags=["store", "public"],
+)
+async def get_agents(
+    featured: bool = Query(
+        default=False, description="Filter to only show featured agents"
+    ),
+    creator: str | None = Query(
+        default=None, description="Filter agents by creator username"
+    ),
+    category: str | None = Query(default=None, description="Filter agents by category"),
+    search_query: str | None = Query(
+        default=None, description="Literal + semantic search on names and descriptions"
+    ),
+    sorted_by: store_db.StoreAgentsSortOptions | None = Query(
+        default=None,
+        description="Property to sort results by. Ignored if search_query is provided.",
+    ),
+    page: int = Query(ge=1, default=1),
+    page_size: int = Query(ge=1, default=20),
+) -> store_model.StoreAgentsResponse:
+    """
+    Get a paginated list of agents from the marketplace,
+    with optional filtering and sorting.
+
+    Used for:
+    - Home Page Featured Agents
+    - Home Page Top Agents
+    - Search Results
+    - Agent Details - Other Agents By Creator
+    - Agent Details - Similar Agents
+    - Creator Details - Agents By Creator
+    """
+    agents = await store_cache._get_cached_store_agents(
+        featured=featured,
+        creator=creator,
+        sorted_by=sorted_by,
+        search_query=search_query,
+        category=category,
+        page=page,
+        page_size=page_size,
+    )
+    return agents
+
+
 @router.get(
     "/agents/{username}/{agent_name}",
     summary="Get specific agent",
     tags=["store", "public"],
-    response_model=store_model.StoreAgentDetails,
 )
-async def get_agent(
+async def get_agent_by_name(
     username: str,
     agent_name: str,
-    include_changelog: bool = fastapi.Query(default=False),
-):
-    """
-    This is only used on the AgentDetails Page.
-
-    It returns the store listing agents details.
-    """
+    include_changelog: bool = Query(default=False),
+) -> store_model.StoreAgentDetails:
+    """Get details of a marketplace agent"""
     username = urllib.parse.unquote(username).lower()
     # URL decode the agent name since it comes from the URL path
     agent_name = urllib.parse.unquote(agent_name).lower()
@@ -270,76 +200,82 @@ async def get_agent(
     return agent
 
 
-@router.get(
-    "/graph/{store_listing_version_id}",
-    summary="Get agent graph",
-    tags=["store"],
-    dependencies=[fastapi.Security(autogpt_libs.auth.requires_user)],
-)
-async def get_graph_meta_by_store_listing_version_id(
-    store_listing_version_id: str,
-) -> backend.data.graph.GraphModelWithoutNodes:
-    """
-    Get Agent Graph from Store Listing Version ID.
-    """
-    graph = await store_db.get_available_graph(store_listing_version_id)
-    return graph
-
-
-@router.get(
-    "/agents/{store_listing_version_id}",
-    summary="Get agent by version",
-    tags=["store"],
-    dependencies=[fastapi.Security(autogpt_libs.auth.requires_user)],
-    response_model=store_model.StoreAgentDetails,
-)
-async def get_store_agent(store_listing_version_id: str):
-    """
-    Get Store Agent Details from Store Listing Version ID.
-    """
-    agent = await store_db.get_store_agent_by_version_id(store_listing_version_id)
-
-    return agent
-
-
 @router.post(
     "/agents/{username}/{agent_name}/review",
     summary="Create agent review",
     tags=["store"],
-    dependencies=[fastapi.Security(autogpt_libs.auth.requires_user)],
-    response_model=store_model.StoreReview,
+    dependencies=[Security(autogpt_libs.auth.requires_user)],
 )
-async def create_review(
+async def post_user_review_for_agent(
     username: str,
     agent_name: str,
     review: store_model.StoreReviewCreate,
-    user_id: str = fastapi.Security(autogpt_libs.auth.get_user_id),
-):
-    """
-    Create a review for a store agent.
-
-    Args:
-        username: Creator's username
-        agent_name: Name/slug of the agent
-        review: Review details including score and optional comments
-        user_id: ID of authenticated user creating the review
-
-    Returns:
-        The created review
-    """
+    user_id: str = Security(autogpt_libs.auth.get_user_id),
+) -> store_model.StoreReview:
+    """Post a user review on a marketplace agent listing"""
     username = urllib.parse.unquote(username).lower()
     agent_name = urllib.parse.unquote(agent_name).lower()
-    # Create the review
+
     created_review = await store_db.create_store_review(
         user_id=user_id,
         store_listing_version_id=review.store_listing_version_id,
         score=review.score,
         comments=review.comments,
     )
-
     return created_review
 
 
+@router.get(
+    "/listings/versions/{store_listing_version_id}",
+    summary="Get agent by version",
+    tags=["store"],
+    dependencies=[Security(autogpt_libs.auth.requires_user)],
+)
+async def get_agent_by_listing_version(
+    store_listing_version_id: str,
+) -> store_model.StoreAgentDetails:
+    agent = await store_db.get_store_agent_by_version_id(store_listing_version_id)
+    return agent
+
+
+@router.get(
+    "/listings/versions/{store_listing_version_id}/graph",
+    summary="Get agent graph",
+    tags=["store"],
+    dependencies=[Security(autogpt_libs.auth.requires_user)],
+)
+async def get_graph_meta_by_store_listing_version_id(
+    store_listing_version_id: str,
+) -> backend.data.graph.GraphModelWithoutNodes:
+    """Get outline of graph belonging to a specific marketplace listing version"""
+    graph = await store_db.get_available_graph(store_listing_version_id)
+    return graph
+
+
+@router.get(
+    "/listings/versions/{store_listing_version_id}/graph/download",
+    summary="Download agent file",
+    tags=["store", "public"],
+)
+async def download_agent_file(
+    store_listing_version_id: str,
+) -> fastapi.responses.FileResponse:
+    """Download agent graph file for a specific marketplace listing version"""
+    graph_data = await store_db.get_agent(store_listing_version_id)
+    file_name = f"agent_{graph_data.id}_v{graph_data.version or 'latest'}.json"
+
+    # Sending graph as a stream (similar to marketplace v1)
+    with tempfile.NamedTemporaryFile(
+        mode="w", suffix=".json", delete=False
+    ) as tmp_file:
+        tmp_file.write(backend.util.json.dumps(graph_data))
+        tmp_file.flush()
+
+        return fastapi.responses.FileResponse(
+            tmp_file.name, filename=file_name, media_type="application/json"
+        )
+
+
 ##############################################
 ############# Creator Endpoints #############
 ##############################################
@@ -349,37 +285,19 @@ async def create_review(
     "/creators",
     summary="List store creators",
     tags=["store", "public"],
-    response_model=store_model.CreatorsResponse,
 )
 async def get_creators(
-    featured: bool = False,
-    search_query: str | None = None,
-    sorted_by: Literal["agent_rating", "agent_runs", "num_agents"] | None = None,
-    page: int = 1,
-    page_size: int = 20,
-):
-    """
-    This is needed for:
-    - Home Page Featured Creators
-    - Search Results Page
-
-    ---
-
-    To support this functionality we need:
-    - featured: bool - to limit the list to just featured agents
-    - search_query: str - vector search based on the creators profile description.
-    - sorted_by: [agent_rating, agent_runs] -
-    """
-    if page < 1:
-        raise fastapi.HTTPException(
-            status_code=422, detail="Page must be greater than 0"
-        )
-
-    if page_size < 1:
-        raise fastapi.HTTPException(
-            status_code=422, detail="Page size must be greater than 0"
-        )
-
+    featured: bool = Query(
+        default=False, description="Filter to only show featured creators"
+    ),
+    search_query: str | None = Query(
+        default=None, description="Literal + semantic search on names and descriptions"
+    ),
+    sorted_by: store_db.StoreCreatorsSortOptions | None = None,
+    page: int = Query(ge=1, default=1),
+    page_size: int = Query(ge=1, default=20),
+) -> store_model.CreatorsResponse:
+    """List or search marketplace creators"""
     creators = await store_cache._get_cached_store_creators(
         featured=featured,
         search_query=search_query,
@@ -391,18 +309,12 @@ async def get_creators(
 
 
 @router.get(
-    "/creator/{username}",
+    "/creators/{username}",
     summary="Get creator details",
     tags=["store", "public"],
-    response_model=store_model.CreatorDetails,
 )
-async def get_creator(
-    username: str,
-):
-    """
-    Get the details of a creator.
-    - Creator Details Page
-    """
+async def get_creator(username: str) -> store_model.CreatorDetails:
+    """Get details on a marketplace creator"""
     username = urllib.parse.unquote(username).lower()
     creator = await store_cache._get_cached_creator_details(username=username)
     return creator
@@ -414,20 +326,17 @@ async def get_creator(
 
 
 @router.get(
-    "/myagents",
+    "/my-unpublished-agents",
     summary="Get my agents",
     tags=["store", "private"],
-    dependencies=[fastapi.Security(autogpt_libs.auth.requires_user)],
-    response_model=store_model.MyAgentsResponse,
+    dependencies=[Security(autogpt_libs.auth.requires_user)],
 )
-async def get_my_agents(
-    user_id: str = fastapi.Security(autogpt_libs.auth.get_user_id),
-    page: typing.Annotated[int, fastapi.Query(ge=1)] = 1,
-    page_size: typing.Annotated[int, fastapi.Query(ge=1)] = 20,
-):
-    """
-    Get user's own agents.
-    """
+async def get_my_unpublished_agents(
+    user_id: str = Security(autogpt_libs.auth.get_user_id),
+    page: int = Query(ge=1, default=1),
+    page_size: int = Query(ge=1, default=20),
+) -> store_model.MyUnpublishedAgentsResponse:
+    """List the authenticated user's unpublished agents"""
     agents = await store_db.get_my_agents(user_id, page=page, page_size=page_size)
     return agents
 
@@ -436,28 +345,17 @@ async def get_my_agents(
     "/submissions/{submission_id}",
     summary="Delete store submission",
     tags=["store", "private"],
-    dependencies=[fastapi.Security(autogpt_libs.auth.requires_user)],
-    response_model=bool,
+    dependencies=[Security(autogpt_libs.auth.requires_user)],
 )
 async def delete_submission(
     submission_id: str,
-    user_id: str = fastapi.Security(autogpt_libs.auth.get_user_id),
-):
-    """
-    Delete a store listing submission.
-
-    Args:
-        user_id (str): ID of the authenticated user
-        submission_id (str): ID of the submission to be deleted
-
-    Returns:
-        bool: True if the submission was successfully deleted, False otherwise
-    """
+    user_id: str = Security(autogpt_libs.auth.get_user_id),
+) -> bool:
+    """Delete a marketplace listing submission"""
     result = await store_db.delete_store_submission(
         user_id=user_id,
-        submission_id=submission_id,
+        store_listing_version_id=submission_id,
     )
-
     return result
 
 
@@ -465,37 +363,14 @@ async def delete_submission(
     "/submissions",
     summary="List my submissions",
     tags=["store", "private"],
-    dependencies=[fastapi.Security(autogpt_libs.auth.requires_user)],
-    response_model=store_model.StoreSubmissionsResponse,
+    dependencies=[Security(autogpt_libs.auth.requires_user)],
 )
 async def get_submissions(
-    user_id: str = fastapi.Security(autogpt_libs.auth.get_user_id),
-    page: int = 1,
-    page_size: int = 20,
-):
-    """
-    Get a paginated list of store submissions for the authenticated user.
-
-    Args:
-        user_id (str): ID of the authenticated user
-        page (int, optional): Page number for pagination. Defaults to 1.
-        page_size (int, optional): Number of submissions per page. Defaults to 20.
-
-    Returns:
-        StoreListingsResponse: Paginated list of store submissions
-
-    Raises:
-        HTTPException: If page or page_size are less than 1
-    """
-    if page < 1:
-        raise fastapi.HTTPException(
-            status_code=422, detail="Page must be greater than 0"
-        )
-
-    if page_size < 1:
-        raise fastapi.HTTPException(
-            status_code=422, detail="Page size must be greater than 0"
-        )
+    user_id: str = Security(autogpt_libs.auth.get_user_id),
+    page: int = Query(ge=1, default=1),
+    page_size: int = Query(ge=1, default=20),
+) -> store_model.StoreSubmissionsResponse:
+    """List the authenticated user's marketplace listing submissions"""
     listings = await store_db.get_store_submissions(
         user_id=user_id,
         page=page,
@@ -508,30 +383,17 @@ async def get_submissions(
     "/submissions",
     summary="Create store submission",
     tags=["store", "private"],
-    dependencies=[fastapi.Security(autogpt_libs.auth.requires_user)],
-    response_model=store_model.StoreSubmission,
+    dependencies=[Security(autogpt_libs.auth.requires_user)],
 )
 async def create_submission(
     submission_request: store_model.StoreSubmissionRequest,
-    user_id: str = fastapi.Security(autogpt_libs.auth.get_user_id),
-):
-    """
-    Create a new store listing submission.
-
-    Args:
-        submission_request (StoreSubmissionRequest): The submission details
-        user_id (str): ID of the authenticated user submitting the listing
-
-    Returns:
-        StoreSubmission: The created store submission
-
-    Raises:
-        HTTPException: If there is an error creating the submission
-    """
+    user_id: str = Security(autogpt_libs.auth.get_user_id),
+) -> store_model.StoreSubmission:
+    """Submit a new marketplace listing for review"""
     result = await store_db.create_store_submission(
         user_id=user_id,
-        agent_id=submission_request.agent_id,
-        agent_version=submission_request.agent_version,
+        graph_id=submission_request.graph_id,
+        graph_version=submission_request.graph_version,
         slug=submission_request.slug,
         name=submission_request.name,
         video_url=submission_request.video_url,
@@ -544,7 +406,6 @@ async def create_submission(
         changes_summary=submission_request.changes_summary or "Initial Submission",
         recommended_schedule_cron=submission_request.recommended_schedule_cron,
     )
-
     return result
 
 
@@ -552,28 +413,14 @@ async def create_submission(
     "/submissions/{store_listing_version_id}",
     summary="Edit store submission",
     tags=["store", "private"],
-    dependencies=[fastapi.Security(autogpt_libs.auth.requires_user)],
-    response_model=store_model.StoreSubmission,
+    dependencies=[Security(autogpt_libs.auth.requires_user)],
 )
 async def edit_submission(
     store_listing_version_id: str,
     submission_request: store_model.StoreSubmissionEditRequest,
-    user_id: str = fastapi.Security(autogpt_libs.auth.get_user_id),
-):
-    """
-    Edit an existing store listing submission.
-
-    Args:
-        store_listing_version_id (str): ID of the store listing version to edit
-        submission_request (StoreSubmissionRequest): The updated submission details
-        user_id (str): ID of the authenticated user editing the listing
-
-    Returns:
-        StoreSubmission: The updated store submission
-
-    Raises:
-        HTTPException: If there is an error editing the submission
-    """
+    user_id: str = Security(autogpt_libs.auth.get_user_id),
+) -> store_model.StoreSubmission:
+    """Update a pending marketplace listing submission"""
     result = await store_db.edit_store_submission(
         user_id=user_id,
         store_listing_version_id=store_listing_version_id,
@@ -588,7 +435,6 @@ async def edit_submission(
         changes_summary=submission_request.changes_summary,
         recommended_schedule_cron=submission_request.recommended_schedule_cron,
     )
-
     return result
 
 
@@ -596,115 +442,61 @@ async def edit_submission(
     "/submissions/media",
     summary="Upload submission media",
     tags=["store", "private"],
-    dependencies=[fastapi.Security(autogpt_libs.auth.requires_user)],
+    dependencies=[Security(autogpt_libs.auth.requires_user)],
 )
 async def upload_submission_media(
     file: fastapi.UploadFile,
-    user_id: str = fastapi.Security(autogpt_libs.auth.get_user_id),
-):
-    """
-    Upload media (images/videos) for a store listing submission.
-
-    Args:
-        file (UploadFile): The media file to upload
-        user_id (str): ID of the authenticated user uploading the media
-
-    Returns:
-        str: URL of the uploaded media file
-
-    Raises:
-        HTTPException: If there is an error uploading the media
-    """
+    user_id: str = Security(autogpt_libs.auth.get_user_id),
+) -> str:
+    """Upload media for a marketplace listing submission"""
     media_url = await store_media.upload_media(user_id=user_id, file=file)
     return media_url
 
 
+class ImageURLResponse(BaseModel):
+    image_url: str
+
+
 @router.post(
     "/submissions/generate_image",
     summary="Generate submission image",
     tags=["store", "private"],
-    dependencies=[fastapi.Security(autogpt_libs.auth.requires_user)],
+    dependencies=[Security(autogpt_libs.auth.requires_user)],
 )
 async def generate_image(
-    agent_id: str,
-    user_id: str = fastapi.Security(autogpt_libs.auth.get_user_id),
-) -> fastapi.responses.Response:
+    graph_id: str,
+    user_id: str = Security(autogpt_libs.auth.get_user_id),
+) -> ImageURLResponse:
     """
-    Generate an image for a store listing submission.
-
-    Args:
-        agent_id (str): ID of the agent to generate an image for
-        user_id (str): ID of the authenticated user
-
-    Returns:
-        JSONResponse: JSON containing the URL of the generated image
+    Generate an image for a marketplace listing submission based on the properties
+    of a given graph.
     """
-    agent = await backend.data.graph.get_graph(
-        graph_id=agent_id, version=None, user_id=user_id
+    graph = await backend.data.graph.get_graph(
+        graph_id=graph_id, version=None, user_id=user_id
     )
 
-    if not agent:
-        raise fastapi.HTTPException(
-            status_code=404, detail=f"Agent with ID {agent_id} not found"
-        )
+    if not graph:
+        raise NotFoundError(f"Agent graph #{graph_id} not found")
     # Use .jpeg here since we are generating JPEG images
-    filename = f"agent_{agent_id}.jpeg"
+    filename = f"agent_{graph_id}.jpeg"
 
     existing_url = await store_media.check_media_exists(user_id, filename)
     if existing_url:
-        logger.info(f"Using existing image for agent {agent_id}")
-        return fastapi.responses.JSONResponse(content={"image_url": existing_url})
+        logger.info(f"Using existing image for agent graph {graph_id}")
+        return ImageURLResponse(image_url=existing_url)
     # Generate agent image as JPEG
-    image = await store_image_gen.generate_agent_image(agent=agent)
+    image = await store_image_gen.generate_agent_image(agent=graph)
 
     # Create UploadFile with the correct filename and content_type
     image_file = fastapi.UploadFile(
         file=image,
         filename=filename,
     )
-
     image_url = await store_media.upload_media(
         user_id=user_id, file=image_file, use_file_name=True
     )
 
-    return fastapi.responses.JSONResponse(content={"image_url": image_url})
-
-
-@router.get(
-    "/download/agents/{store_listing_version_id}",
-    summary="Download agent file",
-    tags=["store", "public"],
-)
-async def download_agent_file(
-    store_listing_version_id: str = fastapi.Path(
-        ..., description="The ID of the agent to download"
-    ),
-) -> fastapi.responses.FileResponse:
-    """
-    Download the agent file by streaming its content.
-
-    Args:
-        store_listing_version_id (str): The ID of the agent to download
-
-    Returns:
-        StreamingResponse: A streaming response containing the agent's graph data.
-
-    Raises:
-        HTTPException: If the agent is not found or an unexpected error occurs.
-    """
-    graph_data = await store_db.get_agent(store_listing_version_id)
-    file_name = f"agent_{graph_data.id}_v{graph_data.version or 'latest'}.json"
-
-    # Sending graph as a stream (similar to marketplace v1)
-    with tempfile.NamedTemporaryFile(
-        mode="w", suffix=".json", delete=False
-    ) as tmp_file:
-        tmp_file.write(backend.util.json.dumps(graph_data))
-        tmp_file.flush()
-
-        return fastapi.responses.FileResponse(
-            tmp_file.name, filename=file_name, media_type="application/json"
-        )
+    return ImageURLResponse(image_url=image_url)
 
 
 ##############################################

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

@@ -8,6 +8,8 @@ import pytest
 import pytest_mock
 from pytest_snapshot.plugin import Snapshot
 
+from backend.api.features.store.db import StoreAgentsSortOptions
+
 from . import model as store_model
 from . import routes as store_routes
 
@@ -196,7 +198,7 @@ def test_get_agents_sorted(
     mock_db_call.assert_called_once_with(
         featured=False,
         creators=None,
-        sorted_by="runs",
+        sorted_by=StoreAgentsSortOptions.RUNS,
         search_query=None,
         category=None,
         page=1,
@@ -380,9 +382,11 @@ def test_get_agent_details(
         runs=100,
         rating=4.5,
         versions=["1.0.0", "1.1.0"],
-        agentGraphVersions=["1", "2"],
-        agentGraphId="test-graph-id",
+        graph_versions=["1", "2"],
+        graph_id="test-graph-id",
         last_updated=FIXED_NOW,
+        active_version_id="test-version-id",
+        has_approved_version=True,
     )
     mock_db_call = mocker.patch("backend.api.features.store.db.get_store_agent_details")
     mock_db_call.return_value = mocked_value
@@ -435,15 +439,17 @@ def test_get_creators_pagination(
 ) -> None:
     mocked_value = store_model.CreatorsResponse(
         creators=[
-            store_model.Creator(
+            store_model.CreatorDetails(
                 name=f"Creator {i}",
                 username=f"creator{i}",
-                description=f"Creator {i} description",
                 avatar_url=f"avatar{i}.jpg",
-                num_agents=1,
-                agent_rating=4.5,
-                agent_runs=100,
+                description=f"Creator {i} description",
+                links=[f"user{i}.link.com"],
                 is_featured=False,
+                num_agents=1,
+                agent_runs=100,
+                agent_rating=4.5,
+                top_categories=["cat1", "cat2", "cat3"],
             )
             for i in range(5)
         ],
@@ -496,19 +502,19 @@ def test_get_creator_details(
     mocked_value = store_model.CreatorDetails(
         name="Test User",
         username="creator1",
+        avatar_url="avatar.jpg",
         description="Test creator description",
         links=["link1.com", "link2.com"],
-        avatar_url="avatar.jpg",
-        agent_rating=4.8,
+        is_featured=True,
+        num_agents=5,
         agent_runs=1000,
+        agent_rating=4.8,
         top_categories=["category1", "category2"],
     )
-    mock_db_call = mocker.patch(
-        "backend.api.features.store.db.get_store_creator_details"
-    )
+    mock_db_call = mocker.patch("backend.api.features.store.db.get_store_creator")
     mock_db_call.return_value = mocked_value
 
-    response = client.get("/creator/creator1")
+    response = client.get("/creators/creator1")
     assert response.status_code == 200
 
     data = store_model.CreatorDetails.model_validate(response.json())
@@ -528,19 +534,26 @@ def test_get_submissions_success(
         submissions=[
             store_model.StoreSubmission(
                 listing_id="test-listing-id",
-                name="Test Agent",
-                description="Test agent description",
-                image_urls=["test.jpg"],
-                date_submitted=FIXED_NOW,
-                status=prisma.enums.SubmissionStatus.APPROVED,
-                runs=50,
-                rating=4.2,
-                agent_id="test-agent-id",
-                agent_version=1,
-                sub_heading="Test agent subheading",
+                user_id="test-user-id",
                 slug="test-agent",
-                video_url="test.mp4",
+                listing_version_id="test-version-id",
+                listing_version=1,
+                graph_id="test-agent-id",
+                graph_version=1,
+                name="Test Agent",
+                sub_heading="Test agent subheading",
+                description="Test agent description",
+                instructions="Click the button!",
                 categories=["test-category"],
+                image_urls=["test.jpg"],
+                video_url="test.mp4",
+                agent_output_demo_url="demo_video.mp4",
+                submitted_at=FIXED_NOW,
+                changes_summary="Initial Submission",
+                status=prisma.enums.SubmissionStatus.APPROVED,
+                run_count=50,
+                review_count=5,
+                review_avg_rating=4.2,
             )
         ],
         pagination=store_model.Pagination(

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

@@ -11,6 +11,7 @@ import pytest
 from backend.util.models import Pagination
 
 from . import cache as store_cache
+from .db import StoreAgentsSortOptions
 from .model import StoreAgent, StoreAgentsResponse
 
 
@@ -215,7 +216,7 @@ class TestCacheDeletion:
             await store_cache._get_cached_store_agents(
                 featured=True,
                 creator="testuser",
-                sorted_by="rating",
+                sorted_by=StoreAgentsSortOptions.RATING,
                 search_query="AI assistant",
                 category="productivity",
                 page=2,
@@ -227,7 +228,7 @@ class TestCacheDeletion:
             deleted = store_cache._get_cached_store_agents.cache_delete(
                 featured=True,
                 creator="testuser",
-                sorted_by="rating",
+                sorted_by=StoreAgentsSortOptions.RATING,
                 search_query="AI assistant",
                 category="productivity",
                 page=2,
@@ -239,7 +240,7 @@ class TestCacheDeletion:
             deleted = store_cache._get_cached_store_agents.cache_delete(
                 featured=True,
                 creator="testuser",
-                sorted_by="rating",
+                sorted_by=StoreAgentsSortOptions.RATING,
                 search_query="AI assistant",
                 category="productivity",
                 page=2,

autogpt_platform/backend/backend/api/features/v1.py

@@ -449,7 +449,6 @@ async def execute_graph_block(
 async def upload_file(
     user_id: Annotated[str, Security(get_user_id)],
     file: UploadFile = File(...),
-    provider: str = "gcs",
     expiration_hours: int = 24,
 ) -> UploadFileResponse:
     """
@@ -512,7 +511,6 @@ async def upload_file(
     storage_path = await cloud_storage.store_file(
         content=content,
         filename=file_name,
-        provider=provider,
         expiration_hours=expiration_hours,
         user_id=user_id,
     )
@@ -738,13 +736,13 @@ class DeleteGraphResponse(TypedDict):
 async def list_graphs(
     user_id: Annotated[str, Security(get_user_id)],
 ) -> Sequence[graph_db.GraphMeta]:
-    paginated_result = await graph_db.list_graphs_paginated(
+    graphs, _ = await graph_db.list_graphs_paginated(
         user_id=user_id,
         page=1,
         page_size=250,
         filter_by="active",
     )
-    return paginated_result.graphs
+    return graphs
 
 
 @v1_router.get(
@@ -861,8 +859,8 @@ async def update_graph(
     new_graph_version = await graph_db.create_graph(graph, user_id=user_id)
 
     if new_graph_version.is_active:
-        await library_db.update_library_agent_version_and_settings(
-            user_id, new_graph_version
+        await library_db.update_agent_version_in_library(
+            user_id, new_graph_version.id, new_graph_version.version
         )
         new_graph_version = await on_graph_activate(new_graph_version, user_id=user_id)
         await graph_db.set_graph_active_version(
@@ -915,8 +913,8 @@ async def set_graph_active_version(
     )
 
     # Keep the library agent up to date with the new active version
-    await library_db.update_library_agent_version_and_settings(
-        user_id, new_active_graph
+    await library_db.update_agent_version_in_library(
+        user_id, new_active_graph.id, new_active_graph.version
     )
 
     if current_active_graph and current_active_graph.version != new_active_version:

autogpt_platform/backend/backend/api/features/v1_test.py

@@ -515,7 +515,6 @@ async def test_upload_file_success(test_user_id: str):
         result = await upload_file(
             file=upload_file_mock,
             user_id=test_user_id,
-            provider="gcs",
             expiration_hours=24,
         )
 
@@ -533,7 +532,6 @@ async def test_upload_file_success(test_user_id: str):
         mock_handler.store_file.assert_called_once_with(
             content=file_content,
             filename="test.txt",
-            provider="gcs",
             expiration_hours=24,
             user_id=test_user_id,
         )

autogpt_platform/backend/backend/api/rest_api.py

@@ -5,16 +5,12 @@ from enum import Enum
 from typing import Any, Optional
 
 import fastapi
-import fastapi.responses
-import pydantic
 import starlette.middleware.cors
 import uvicorn
 from autogpt_libs.auth import add_auth_responses_to_openapi
 from autogpt_libs.auth import verify_settings as verify_auth_settings
-from fastapi.exceptions import RequestValidationError
 from fastapi.middleware.gzip import GZipMiddleware
 from fastapi.routing import APIRoute
-from prisma.errors import PrismaError
 
 import backend.api.features.admin.credit_admin_routes
 import backend.api.features.admin.execution_analytics_routes
@@ -41,21 +37,12 @@ import backend.data.user
 import backend.integrations.webhooks.utils
 import backend.util.service
 import backend.util.settings
-from backend.api.features.library.exceptions import (
-    FolderAlreadyExistsError,
-    FolderValidationError,
-)
+from backend.api.utils.exceptions import add_exception_handlers
 from backend.blocks.llm import DEFAULT_LLM_MODEL
 from backend.data.model import Credentials
 from backend.integrations.providers import ProviderName
 from backend.monitoring.instrumentation import instrument_fastapi
-from backend.util import json
 from backend.util.cloud_storage import shutdown_cloud_storage_handler
-from backend.util.exceptions import (
-    MissingConfigError,
-    NotAuthorizedError,
-    NotFoundError,
-)
 from backend.util.feature_flag import initialize_launchdarkly, shutdown_launchdarkly
 from backend.util.service import UnhealthyServiceError
 from backend.util.workspace_storage import shutdown_workspace_storage
@@ -206,76 +193,7 @@ instrument_fastapi(
 )
 
 
-def handle_internal_http_error(status_code: int = 500, log_error: bool = True):
-    def handler(request: fastapi.Request, exc: Exception):
-        if log_error:
-            logger.exception(
-                "%s %s failed. Investigate and resolve the underlying issue: %s",
-                request.method,
-                request.url.path,
-                exc,
-                exc_info=exc,
-            )
-
-        hint = (
-            "Adjust the request and retry."
-            if status_code < 500
-            else "Check server logs and dependent services."
-        )
-        return fastapi.responses.JSONResponse(
-            content={
-                "message": f"Failed to process {request.method} {request.url.path}",
-                "detail": str(exc),
-                "hint": hint,
-            },
-            status_code=status_code,
-        )
-
-    return handler
-
-
-async def validation_error_handler(
-    request: fastapi.Request, exc: Exception
-) -> fastapi.responses.Response:
-    logger.error(
-        "Validation failed for %s %s: %s. Fix the request payload and try again.",
-        request.method,
-        request.url.path,
-        exc,
-    )
-    errors: list | str
-    if hasattr(exc, "errors"):
-        errors = exc.errors()  # type: ignore[call-arg]
-    else:
-        errors = str(exc)
-
-    response_content = {
-        "message": f"Invalid data for {request.method} {request.url.path}",
-        "detail": errors,
-        "hint": "Ensure the request matches the API schema.",
-    }
-
-    content_json = json.dumps(response_content)
-
-    return fastapi.responses.Response(
-        content=content_json,
-        status_code=422,
-        media_type="application/json",
-    )
-
-
-app.add_exception_handler(PrismaError, handle_internal_http_error(500))
-app.add_exception_handler(
-    FolderAlreadyExistsError, handle_internal_http_error(409, False)
-)
-app.add_exception_handler(FolderValidationError, handle_internal_http_error(400, False))
-app.add_exception_handler(NotFoundError, handle_internal_http_error(404, False))
-app.add_exception_handler(NotAuthorizedError, handle_internal_http_error(403, False))
-app.add_exception_handler(RequestValidationError, validation_error_handler)
-app.add_exception_handler(pydantic.ValidationError, validation_error_handler)
-app.add_exception_handler(MissingConfigError, handle_internal_http_error(503))
-app.add_exception_handler(ValueError, handle_internal_http_error(400))
-app.add_exception_handler(Exception, handle_internal_http_error(500))
+add_exception_handlers(app)
 
 app.include_router(backend.api.features.v1.v1_router, tags=["v1"], prefix="/api")
 app.include_router(

autogpt_platform/backend/backend/api/utils/exceptions.py

@@ -0,0 +1,119 @@
+"""
+Shared exception handlers for FastAPI applications.
+
+Provides a single `add_exception_handlers` function that registers a consistent
+set of exception-to-HTTP-status mappings on any FastAPI app instance. This
+ensures that all mounted sub-apps (v1, v2, main) handle errors uniformly.
+"""
+
+import json
+import logging
+
+import fastapi
+import fastapi.responses
+import pydantic
+from fastapi.exceptions import RequestValidationError
+from prisma.errors import PrismaError
+from prisma.errors import RecordNotFoundError as PrismaRecordNotFoundError
+from starlette import status
+
+from backend.api.features.library.exceptions import (
+    FolderAlreadyExistsError,
+    FolderValidationError,
+)
+from backend.util.exceptions import (
+    MissingConfigError,
+    NotAuthorizedError,
+    NotFoundError,
+    PreconditionFailed,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def add_exception_handlers(app: fastapi.FastAPI) -> None:
+    """
+    Register standard exception handlers on the given FastAPI app.
+
+    Mounted sub-apps do NOT inherit exception handlers from the parent app,
+    so each app instance must register its own handlers.
+    """
+    for exception, handler in {
+        # It's the client's problem: HTTP 4XX
+        NotFoundError: _handle_error(status.HTTP_404_NOT_FOUND, log_error=False),
+        NotAuthorizedError: _handle_error(status.HTTP_403_FORBIDDEN, log_error=False),
+        PreconditionFailed: _handle_error(status.HTTP_428_PRECONDITION_REQUIRED),
+        RequestValidationError: _handle_validation_error,
+        pydantic.ValidationError: _handle_validation_error,
+        PrismaRecordNotFoundError: _handle_error(status.HTTP_404_NOT_FOUND),
+        FolderAlreadyExistsError: _handle_error(
+            status.HTTP_409_CONFLICT, log_error=False
+        ),
+        FolderValidationError: _handle_error(
+            status.HTTP_400_BAD_REQUEST, log_error=False
+        ),
+        ValueError: _handle_error(status.HTTP_400_BAD_REQUEST),
+        # It's the backend's problem: HTTP 5XX
+        MissingConfigError: _handle_error(status.HTTP_503_SERVICE_UNAVAILABLE),
+        PrismaError: _handle_error(status.HTTP_500_INTERNAL_SERVER_ERROR),
+        Exception: _handle_error(status.HTTP_500_INTERNAL_SERVER_ERROR),
+    }.items():
+        app.add_exception_handler(exception, handler)
+
+
+def _handle_error(status_code: int = 500, log_error: bool = True):
+    def handler(request: fastapi.Request, exc: Exception):
+        if log_error:
+            logger.exception(
+                "%s %s failed. Investigate and resolve the underlying issue: %s",
+                request.method,
+                request.url.path,
+                exc,
+                exc_info=exc,
+            )
+
+        hint = (
+            "Adjust the request and retry."
+            if status_code < 500
+            else "Check server logs and dependent services."
+        )
+        return fastapi.responses.JSONResponse(
+            content={
+                "message": f"Failed to process {request.method} {request.url.path}",
+                "detail": str(exc),
+                "hint": hint,
+            },
+            status_code=status_code,
+        )
+
+    return handler
+
+
+async def _handle_validation_error(
+    request: fastapi.Request, exc: Exception
+) -> fastapi.responses.Response:
+    logger.error(
+        "Validation failed for %s %s: %s. Fix the request payload and try again.",
+        request.method,
+        request.url.path,
+        exc,
+    )
+    errors: list | str
+    if hasattr(exc, "errors"):
+        errors = exc.errors()  # type: ignore[call-arg]
+    else:
+        errors = str(exc)
+
+    response_content = {
+        "message": f"Invalid data for {request.method} {request.url.path}",
+        "detail": errors,
+        "hint": "Ensure the request matches the API schema.",
+    }
+
+    content_json = json.dumps(response_content)
+
+    return fastapi.responses.Response(
+        content=content_json,
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+        media_type="application/json",
+    )

autogpt_platform/backend/backend/blocks/_base.py

@@ -418,6 +418,8 @@ class BlockWebhookConfig(BlockManualWebhookConfig):
 
 
 class Block(ABC, Generic[BlockSchemaInputType, BlockSchemaOutputType]):
+    _optimized_description: ClassVar[str | None] = None
+
     def __init__(
         self,
         id: str = "",
@@ -470,6 +472,8 @@ class Block(ABC, Generic[BlockSchemaInputType, BlockSchemaOutputType]):
         self.block_type = block_type
         self.webhook_config = webhook_config
         self.is_sensitive_action = is_sensitive_action
+        # Read from ClassVar set by initialize_blocks()
+        self.optimized_description: str | None = type(self)._optimized_description
         self.execution_stats: "NodeExecutionStats" = NodeExecutionStats()
 
         if self.webhook_config:
@@ -620,6 +624,7 @@ class Block(ABC, Generic[BlockSchemaInputType, BlockSchemaOutputType]):
         graph_id: str,
         graph_version: int,
         execution_context: "ExecutionContext",
+        is_graph_execution: bool = True,
         **kwargs,
     ) -> tuple[bool, BlockInput]:
         """
@@ -648,6 +653,7 @@ class Block(ABC, Generic[BlockSchemaInputType, BlockSchemaOutputType]):
             graph_version=graph_version,
             block_name=self.name,
             editable=True,
+            is_graph_execution=is_graph_execution,
         )
 
         if decision is None:

autogpt_platform/backend/backend/blocks/basic.py

@@ -126,7 +126,7 @@ class PrintToConsoleBlock(Block):
             output_schema=PrintToConsoleBlock.Output,
             test_input={"text": "Hello, World!"},
             is_sensitive_action=True,
-            disabled=True,  # Disabled per Nick Tindle's request (OPEN-3000)
+            disabled=True,
             test_output=[
                 ("output", "Hello, World!"),
                 ("status", "printed"),

autogpt_platform/backend/backend/blocks/code_executor.py

@@ -142,7 +142,7 @@ class BaseE2BExecutorMixin:
                 start_timestamp = ts_result.stdout.strip() if ts_result.stdout else None
 
             # Execute the code
-            execution = await sandbox.run_code(
+            execution = await sandbox.run_code(  # type: ignore[attr-defined]
                 code,
                 language=language.value,
                 on_error=lambda e: sandbox.kill(),  # Kill the sandbox on error

autogpt_platform/backend/backend/blocks/email_block.py

@@ -96,6 +96,7 @@ class SendEmailBlock(Block):
             test_credentials=TEST_CREDENTIALS,
             test_output=[("status", "Email sent successfully")],
             test_mock={"send_email": lambda *args, **kwargs: "Email sent successfully"},
+            is_sensitive_action=True,
         )
 
     @staticmethod

autogpt_platform/backend/backend/blocks/github/_utils.py

@@ -0,0 +1,3 @@
+def github_repo_path(repo_url: str) -> str:
+    """Extract 'owner/repo' from a GitHub repository URL."""
+    return repo_url.replace("https://github.com/", "")

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

@@ -0,0 +1,374 @@
+import asyncio
+from enum import StrEnum
+from urllib.parse import quote
+
+from typing_extensions import TypedDict
+
+from backend.blocks._base import (
+    Block,
+    BlockCategory,
+    BlockOutput,
+    BlockSchemaInput,
+    BlockSchemaOutput,
+)
+from backend.data.model import SchemaField
+
+from ._api import get_api
+from ._auth import (
+    TEST_CREDENTIALS,
+    TEST_CREDENTIALS_INPUT,
+    GithubCredentials,
+    GithubCredentialsField,
+    GithubCredentialsInput,
+)
+from ._utils import github_repo_path
+
+
+class GithubListCommitsBlock(Block):
+    class Input(BlockSchemaInput):
+        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
+        repo_url: str = SchemaField(
+            description="URL of the GitHub repository",
+            placeholder="https://github.com/owner/repo",
+        )
+        branch: str = SchemaField(
+            description="Branch name to list commits from",
+            default="main",
+        )
+        per_page: int = SchemaField(
+            description="Number of commits to return (max 100)",
+            default=30,
+            ge=1,
+            le=100,
+        )
+        page: int = SchemaField(
+            description="Page number for pagination",
+            default=1,
+            ge=1,
+        )
+
+    class Output(BlockSchemaOutput):
+        class CommitItem(TypedDict):
+            sha: str
+            message: str
+            author: str
+            date: str
+            url: str
+
+        commit: CommitItem = SchemaField(
+            title="Commit", description="A commit with its details"
+        )
+        commits: list[CommitItem] = SchemaField(
+            description="List of commits with their details"
+        )
+        error: str = SchemaField(description="Error message if listing commits failed")
+
+    def __init__(self):
+        super().__init__(
+            id="8b13f579-d8b6-4dc2-a140-f770428805de",
+            description="This block lists commits on a branch in a GitHub repository.",
+            categories={BlockCategory.DEVELOPER_TOOLS},
+            input_schema=GithubListCommitsBlock.Input,
+            output_schema=GithubListCommitsBlock.Output,
+            test_input={
+                "repo_url": "https://github.com/owner/repo",
+                "branch": "main",
+                "per_page": 30,
+                "page": 1,
+                "credentials": TEST_CREDENTIALS_INPUT,
+            },
+            test_credentials=TEST_CREDENTIALS,
+            test_output=[
+                (
+                    "commits",
+                    [
+                        {
+                            "sha": "abc123",
+                            "message": "Initial commit",
+                            "author": "octocat",
+                            "date": "2024-01-01T00:00:00Z",
+                            "url": "https://github.com/owner/repo/commit/abc123",
+                        }
+                    ],
+                ),
+                (
+                    "commit",
+                    {
+                        "sha": "abc123",
+                        "message": "Initial commit",
+                        "author": "octocat",
+                        "date": "2024-01-01T00:00:00Z",
+                        "url": "https://github.com/owner/repo/commit/abc123",
+                    },
+                ),
+            ],
+            test_mock={
+                "list_commits": lambda *args, **kwargs: [
+                    {
+                        "sha": "abc123",
+                        "message": "Initial commit",
+                        "author": "octocat",
+                        "date": "2024-01-01T00:00:00Z",
+                        "url": "https://github.com/owner/repo/commit/abc123",
+                    }
+                ]
+            },
+        )
+
+    @staticmethod
+    async def list_commits(
+        credentials: GithubCredentials,
+        repo_url: str,
+        branch: str,
+        per_page: int,
+        page: int,
+    ) -> list[Output.CommitItem]:
+        api = get_api(credentials)
+        commits_url = repo_url + "/commits"
+        params = {"sha": branch, "per_page": str(per_page), "page": str(page)}
+        response = await api.get(commits_url, params=params)
+        data = response.json()
+        repo_path = github_repo_path(repo_url)
+        return [
+            GithubListCommitsBlock.Output.CommitItem(
+                sha=c["sha"],
+                message=c["commit"]["message"],
+                author=(c["commit"].get("author") or {}).get("name", "Unknown"),
+                date=(c["commit"].get("author") or {}).get("date", ""),
+                url=f"https://github.com/{repo_path}/commit/{c['sha']}",
+            )
+            for c in data
+        ]
+
+    async def run(
+        self,
+        input_data: Input,
+        *,
+        credentials: GithubCredentials,
+        **kwargs,
+    ) -> BlockOutput:
+        try:
+            commits = await self.list_commits(
+                credentials,
+                input_data.repo_url,
+                input_data.branch,
+                input_data.per_page,
+                input_data.page,
+            )
+            yield "commits", commits
+            for commit in commits:
+                yield "commit", commit
+        except Exception as e:
+            yield "error", str(e)
+
+
+class FileOperation(StrEnum):
+    """File operations for GithubMultiFileCommitBlock.
+
+    UPSERT creates or overwrites a file (the Git Trees API does not distinguish
+    between creation and update — the blob is placed at the given path regardless
+    of whether a file already exists there).
+
+    DELETE removes a file from the tree.
+    """
+
+    UPSERT = "upsert"
+    DELETE = "delete"
+
+
+class FileOperationInput(TypedDict):
+    path: str
+    content: str
+    operation: FileOperation
+
+
+class GithubMultiFileCommitBlock(Block):
+    class Input(BlockSchemaInput):
+        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
+        repo_url: str = SchemaField(
+            description="URL of the GitHub repository",
+            placeholder="https://github.com/owner/repo",
+        )
+        branch: str = SchemaField(
+            description="Branch to commit to",
+            placeholder="feature-branch",
+        )
+        commit_message: str = SchemaField(
+            description="Commit message",
+            placeholder="Add new feature",
+        )
+        files: list[FileOperationInput] = SchemaField(
+            description=(
+                "List of file operations. Each item has: "
+                "'path' (file path), 'content' (file content, ignored for delete), "
+                "'operation' (upsert/delete)"
+            ),
+        )
+
+    class Output(BlockSchemaOutput):
+        sha: str = SchemaField(description="SHA of the new commit")
+        url: str = SchemaField(description="URL of the new commit")
+        error: str = SchemaField(description="Error message if the commit failed")
+
+    def __init__(self):
+        super().__init__(
+            id="389eee51-a95e-4230-9bed-92167a327802",
+            description=(
+                "This block creates a single commit with multiple file "
+                "upsert/delete operations using the Git Trees API."
+            ),
+            categories={BlockCategory.DEVELOPER_TOOLS},
+            input_schema=GithubMultiFileCommitBlock.Input,
+            output_schema=GithubMultiFileCommitBlock.Output,
+            test_input={
+                "repo_url": "https://github.com/owner/repo",
+                "branch": "feature",
+                "commit_message": "Add files",
+                "files": [
+                    {
+                        "path": "src/new.py",
+                        "content": "print('hello')",
+                        "operation": "upsert",
+                    },
+                    {
+                        "path": "src/old.py",
+                        "content": "",
+                        "operation": "delete",
+                    },
+                ],
+                "credentials": TEST_CREDENTIALS_INPUT,
+            },
+            test_credentials=TEST_CREDENTIALS,
+            test_output=[
+                ("sha", "newcommitsha"),
+                ("url", "https://github.com/owner/repo/commit/newcommitsha"),
+            ],
+            test_mock={
+                "multi_file_commit": lambda *args, **kwargs: (
+                    "newcommitsha",
+                    "https://github.com/owner/repo/commit/newcommitsha",
+                )
+            },
+        )
+
+    @staticmethod
+    async def multi_file_commit(
+        credentials: GithubCredentials,
+        repo_url: str,
+        branch: str,
+        commit_message: str,
+        files: list[FileOperationInput],
+    ) -> tuple[str, str]:
+        api = get_api(credentials)
+        safe_branch = quote(branch, safe="")
+
+        # 1. Get the latest commit SHA for the branch
+        ref_url = repo_url + f"/git/refs/heads/{safe_branch}"
+        response = await api.get(ref_url)
+        ref_data = response.json()
+        latest_commit_sha = ref_data["object"]["sha"]
+
+        # 2. Get the tree SHA of the latest commit
+        commit_url = repo_url + f"/git/commits/{latest_commit_sha}"
+        response = await api.get(commit_url)
+        commit_data = response.json()
+        base_tree_sha = commit_data["tree"]["sha"]
+
+        # 3. Build tree entries for each file operation (blobs created concurrently)
+        async def _create_blob(content: str) -> str:
+            blob_url = repo_url + "/git/blobs"
+            blob_response = await api.post(
+                blob_url,
+                json={"content": content, "encoding": "utf-8"},
+            )
+            return blob_response.json()["sha"]
+
+        tree_entries: list[dict] = []
+        upsert_files = []
+        for file_op in files:
+            path = file_op["path"]
+            operation = FileOperation(file_op.get("operation", "upsert"))
+
+            if operation == FileOperation.DELETE:
+                tree_entries.append(
+                    {
+                        "path": path,
+                        "mode": "100644",
+                        "type": "blob",
+                        "sha": None,  # null SHA = delete
+                    }
+                )
+            else:
+                upsert_files.append((path, file_op.get("content", "")))
+
+        # Create all blobs concurrently
+        if upsert_files:
+            blob_shas = await asyncio.gather(
+                *[_create_blob(content) for _, content in upsert_files]
+            )
+            for (path, _), blob_sha in zip(upsert_files, blob_shas):
+                tree_entries.append(
+                    {
+                        "path": path,
+                        "mode": "100644",
+                        "type": "blob",
+                        "sha": blob_sha,
+                    }
+                )
+
+        # 4. Create a new tree
+        tree_url = repo_url + "/git/trees"
+        tree_response = await api.post(
+            tree_url,
+            json={"base_tree": base_tree_sha, "tree": tree_entries},
+        )
+        new_tree_sha = tree_response.json()["sha"]
+
+        # 5. Create a new commit
+        new_commit_url = repo_url + "/git/commits"
+        commit_response = await api.post(
+            new_commit_url,
+            json={
+                "message": commit_message,
+                "tree": new_tree_sha,
+                "parents": [latest_commit_sha],
+            },
+        )
+        new_commit_sha = commit_response.json()["sha"]
+
+        # 6. Update the branch reference
+        try:
+            await api.patch(
+                ref_url,
+                json={"sha": new_commit_sha},
+            )
+        except Exception as e:
+            raise RuntimeError(
+                f"Commit {new_commit_sha} was created but failed to update "
+                f"ref heads/{branch}: {e}. "
+                f"You can recover by manually updating the branch to {new_commit_sha}."
+            ) from e
+
+        repo_path = github_repo_path(repo_url)
+        commit_web_url = f"https://github.com/{repo_path}/commit/{new_commit_sha}"
+        return new_commit_sha, commit_web_url
+
+    async def run(
+        self,
+        input_data: Input,
+        *,
+        credentials: GithubCredentials,
+        **kwargs,
+    ) -> BlockOutput:
+        try:
+            sha, url = await self.multi_file_commit(
+                credentials,
+                input_data.repo_url,
+                input_data.branch,
+                input_data.commit_message,
+                input_data.files,
+            )
+            yield "sha", sha
+            yield "url", url
+        except Exception as e:
+            yield "error", str(e)

autogpt_platform/backend/backend/blocks/github/pull_requests.py

@@ -1,4 +1,5 @@
 import re
+from typing import Literal
 
 from typing_extensions import TypedDict
 
@@ -20,6 +21,8 @@ from ._auth import (
     GithubCredentialsInput,
 )
 
+MergeMethod = Literal["merge", "squash", "rebase"]
+
 
 class GithubListPullRequestsBlock(Block):
     class Input(BlockSchemaInput):
@@ -558,12 +561,109 @@ class GithubListPRReviewersBlock(Block):
             yield "reviewer", reviewer
 
 
+class GithubMergePullRequestBlock(Block):
+    class Input(BlockSchemaInput):
+        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
+        pr_url: str = SchemaField(
+            description="URL of the GitHub pull request",
+            placeholder="https://github.com/owner/repo/pull/1",
+        )
+        merge_method: MergeMethod = SchemaField(
+            description="Merge method to use: merge, squash, or rebase",
+            default="merge",
+        )
+        commit_title: str = SchemaField(
+            description="Title for the merge commit (optional, used for merge and squash)",
+            default="",
+        )
+        commit_message: str = SchemaField(
+            description="Message for the merge commit (optional, used for merge and squash)",
+            default="",
+        )
+
+    class Output(BlockSchemaOutput):
+        sha: str = SchemaField(description="SHA of the merge commit")
+        merged: bool = SchemaField(description="Whether the PR was merged")
+        message: str = SchemaField(description="Merge status message")
+        error: str = SchemaField(description="Error message if the merge failed")
+
+    def __init__(self):
+        super().__init__(
+            id="77456c22-33d8-4fd4-9eef-50b46a35bb48",
+            description="This block merges a pull request using merge, squash, or rebase.",
+            categories={BlockCategory.DEVELOPER_TOOLS},
+            input_schema=GithubMergePullRequestBlock.Input,
+            output_schema=GithubMergePullRequestBlock.Output,
+            test_input={
+                "pr_url": "https://github.com/owner/repo/pull/1",
+                "merge_method": "squash",
+                "commit_title": "",
+                "commit_message": "",
+                "credentials": TEST_CREDENTIALS_INPUT,
+            },
+            test_credentials=TEST_CREDENTIALS,
+            test_output=[
+                ("sha", "abc123"),
+                ("merged", True),
+                ("message", "Pull Request successfully merged"),
+            ],
+            test_mock={
+                "merge_pr": lambda *args, **kwargs: (
+                    "abc123",
+                    True,
+                    "Pull Request successfully merged",
+                )
+            },
+            is_sensitive_action=True,
+        )
+
+    @staticmethod
+    async def merge_pr(
+        credentials: GithubCredentials,
+        pr_url: str,
+        merge_method: MergeMethod,
+        commit_title: str,
+        commit_message: str,
+    ) -> tuple[str, bool, str]:
+        api = get_api(credentials)
+        merge_url = prepare_pr_api_url(pr_url=pr_url, path="merge")
+        data: dict[str, str] = {"merge_method": merge_method}
+        if commit_title:
+            data["commit_title"] = commit_title
+        if commit_message:
+            data["commit_message"] = commit_message
+        response = await api.put(merge_url, json=data)
+        result = response.json()
+        return result["sha"], result["merged"], result["message"]
+
+    async def run(
+        self,
+        input_data: Input,
+        *,
+        credentials: GithubCredentials,
+        **kwargs,
+    ) -> BlockOutput:
+        try:
+            sha, merged, message = await self.merge_pr(
+                credentials,
+                input_data.pr_url,
+                input_data.merge_method,
+                input_data.commit_title,
+                input_data.commit_message,
+            )
+            yield "sha", sha
+            yield "merged", merged
+            yield "message", message
+        except Exception as e:
+            yield "error", str(e)
+
+
 def prepare_pr_api_url(pr_url: str, path: str) -> str:
     # Pattern to capture the base repository URL and the pull request number
-    pattern = r"^(?:https?://)?([^/]+/[^/]+/[^/]+)/pull/(\d+)"
+    pattern = r"^(?:(https?)://)?([^/]+/[^/]+/[^/]+)/pull/(\d+)"
     match = re.match(pattern, pr_url)
     if not match:
         return pr_url
 
-    base_url, pr_number = match.groups()
-    return f"{base_url}/pulls/{pr_number}/{path}"
+    scheme, base_url, pr_number = match.groups()
+    return f"{scheme or 'https'}://{base_url}/pulls/{pr_number}/{path}"

autogpt_platform/backend/backend/blocks/github/repo.py

@@ -1,5 +1,3 @@
-import base64
-
 from typing_extensions import TypedDict
 
 from backend.blocks._base import (
@@ -19,6 +17,7 @@ from ._auth import (
     GithubCredentialsField,
     GithubCredentialsInput,
 )
+from ._utils import github_repo_path
 
 
 class GithubListTagsBlock(Block):
@@ -89,7 +88,7 @@ class GithubListTagsBlock(Block):
         tags_url = repo_url + "/tags"
         response = await api.get(tags_url)
         data = response.json()
-        repo_path = repo_url.replace("https://github.com/", "")
+        repo_path = github_repo_path(repo_url)
         tags: list[GithubListTagsBlock.Output.TagItem] = [
             {
                 "name": tag["name"],
@@ -115,101 +114,6 @@ class GithubListTagsBlock(Block):
             yield "tag", tag
 
 
-class GithubListBranchesBlock(Block):
-    class Input(BlockSchemaInput):
-        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
-        repo_url: str = SchemaField(
-            description="URL of the GitHub repository",
-            placeholder="https://github.com/owner/repo",
-        )
-
-    class Output(BlockSchemaOutput):
-        class BranchItem(TypedDict):
-            name: str
-            url: str
-
-        branch: BranchItem = SchemaField(
-            title="Branch",
-            description="Branches with their name and file tree browser URL",
-        )
-        branches: list[BranchItem] = SchemaField(
-            description="List of branches with their name and file tree browser URL"
-        )
-
-    def __init__(self):
-        super().__init__(
-            id="74243e49-2bec-4916-8bf4-db43d44aead5",
-            description="This block lists all branches for a specified GitHub repository.",
-            categories={BlockCategory.DEVELOPER_TOOLS},
-            input_schema=GithubListBranchesBlock.Input,
-            output_schema=GithubListBranchesBlock.Output,
-            test_input={
-                "repo_url": "https://github.com/owner/repo",
-                "credentials": TEST_CREDENTIALS_INPUT,
-            },
-            test_credentials=TEST_CREDENTIALS,
-            test_output=[
-                (
-                    "branches",
-                    [
-                        {
-                            "name": "main",
-                            "url": "https://github.com/owner/repo/tree/main",
-                        }
-                    ],
-                ),
-                (
-                    "branch",
-                    {
-                        "name": "main",
-                        "url": "https://github.com/owner/repo/tree/main",
-                    },
-                ),
-            ],
-            test_mock={
-                "list_branches": lambda *args, **kwargs: [
-                    {
-                        "name": "main",
-                        "url": "https://github.com/owner/repo/tree/main",
-                    }
-                ]
-            },
-        )
-
-    @staticmethod
-    async def list_branches(
-        credentials: GithubCredentials, repo_url: str
-    ) -> list[Output.BranchItem]:
-        api = get_api(credentials)
-        branches_url = repo_url + "/branches"
-        response = await api.get(branches_url)
-        data = response.json()
-        repo_path = repo_url.replace("https://github.com/", "")
-        branches: list[GithubListBranchesBlock.Output.BranchItem] = [
-            {
-                "name": branch["name"],
-                "url": f"https://github.com/{repo_path}/tree/{branch['name']}",
-            }
-            for branch in data
-        ]
-        return branches
-
-    async def run(
-        self,
-        input_data: Input,
-        *,
-        credentials: GithubCredentials,
-        **kwargs,
-    ) -> BlockOutput:
-        branches = await self.list_branches(
-            credentials,
-            input_data.repo_url,
-        )
-        yield "branches", branches
-        for branch in branches:
-            yield "branch", branch
-
-
 class GithubListDiscussionsBlock(Block):
     class Input(BlockSchemaInput):
         credentials: GithubCredentialsInput = GithubCredentialsField("repo")
@@ -283,7 +187,7 @@ class GithubListDiscussionsBlock(Block):
     ) -> list[Output.DiscussionItem]:
         api = get_api(credentials)
         # GitHub GraphQL API endpoint is different; we'll use api.post with custom URL
-        repo_path = repo_url.replace("https://github.com/", "")
+        repo_path = github_repo_path(repo_url)
         owner, repo = repo_path.split("/")
         query = """
         query($owner: String!, $repo: String!, $num: Int!) {
@@ -416,564 +320,6 @@ class GithubListReleasesBlock(Block):
             yield "release", release
 
 
-class GithubReadFileBlock(Block):
-    class Input(BlockSchemaInput):
-        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
-        repo_url: str = SchemaField(
-            description="URL of the GitHub repository",
-            placeholder="https://github.com/owner/repo",
-        )
-        file_path: str = SchemaField(
-            description="Path to the file in the repository",
-            placeholder="path/to/file",
-        )
-        branch: str = SchemaField(
-            description="Branch to read from",
-            placeholder="branch_name",
-            default="master",
-        )
-
-    class Output(BlockSchemaOutput):
-        text_content: str = SchemaField(
-            description="Content of the file (decoded as UTF-8 text)"
-        )
-        raw_content: str = SchemaField(
-            description="Raw base64-encoded content of the file"
-        )
-        size: int = SchemaField(description="The size of the file (in bytes)")
-
-    def __init__(self):
-        super().__init__(
-            id="87ce6c27-5752-4bbc-8e26-6da40a3dcfd3",
-            description="This block reads the content of a specified file from a GitHub repository.",
-            categories={BlockCategory.DEVELOPER_TOOLS},
-            input_schema=GithubReadFileBlock.Input,
-            output_schema=GithubReadFileBlock.Output,
-            test_input={
-                "repo_url": "https://github.com/owner/repo",
-                "file_path": "path/to/file",
-                "branch": "master",
-                "credentials": TEST_CREDENTIALS_INPUT,
-            },
-            test_credentials=TEST_CREDENTIALS,
-            test_output=[
-                ("raw_content", "RmlsZSBjb250ZW50"),
-                ("text_content", "File content"),
-                ("size", 13),
-            ],
-            test_mock={"read_file": lambda *args, **kwargs: ("RmlsZSBjb250ZW50", 13)},
-        )
-
-    @staticmethod
-    async def read_file(
-        credentials: GithubCredentials, repo_url: str, file_path: str, branch: str
-    ) -> tuple[str, int]:
-        api = get_api(credentials)
-        content_url = repo_url + f"/contents/{file_path}?ref={branch}"
-        response = await api.get(content_url)
-        data = response.json()
-
-        if isinstance(data, list):
-            # Multiple entries of different types exist at this path
-            if not (file := next((f for f in data if f["type"] == "file"), None)):
-                raise TypeError("Not a file")
-            data = file
-
-        if data["type"] != "file":
-            raise TypeError("Not a file")
-
-        return data["content"], data["size"]
-
-    async def run(
-        self,
-        input_data: Input,
-        *,
-        credentials: GithubCredentials,
-        **kwargs,
-    ) -> BlockOutput:
-        content, size = await self.read_file(
-            credentials,
-            input_data.repo_url,
-            input_data.file_path,
-            input_data.branch,
-        )
-        yield "raw_content", content
-        yield "text_content", base64.b64decode(content).decode("utf-8")
-        yield "size", size
-
-
-class GithubReadFolderBlock(Block):
-    class Input(BlockSchemaInput):
-        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
-        repo_url: str = SchemaField(
-            description="URL of the GitHub repository",
-            placeholder="https://github.com/owner/repo",
-        )
-        folder_path: str = SchemaField(
-            description="Path to the folder in the repository",
-            placeholder="path/to/folder",
-        )
-        branch: str = SchemaField(
-            description="Branch name to read from (defaults to master)",
-            placeholder="branch_name",
-            default="master",
-        )
-
-    class Output(BlockSchemaOutput):
-        class DirEntry(TypedDict):
-            name: str
-            path: str
-
-        class FileEntry(TypedDict):
-            name: str
-            path: str
-            size: int
-
-        file: FileEntry = SchemaField(description="Files in the folder")
-        dir: DirEntry = SchemaField(description="Directories in the folder")
-        error: str = SchemaField(
-            description="Error message if reading the folder failed"
-        )
-
-    def __init__(self):
-        super().__init__(
-            id="1355f863-2db3-4d75-9fba-f91e8a8ca400",
-            description="This block reads the content of a specified folder from a GitHub repository.",
-            categories={BlockCategory.DEVELOPER_TOOLS},
-            input_schema=GithubReadFolderBlock.Input,
-            output_schema=GithubReadFolderBlock.Output,
-            test_input={
-                "repo_url": "https://github.com/owner/repo",
-                "folder_path": "path/to/folder",
-                "branch": "master",
-                "credentials": TEST_CREDENTIALS_INPUT,
-            },
-            test_credentials=TEST_CREDENTIALS,
-            test_output=[
-                (
-                    "file",
-                    {
-                        "name": "file1.txt",
-                        "path": "path/to/folder/file1.txt",
-                        "size": 1337,
-                    },
-                ),
-                ("dir", {"name": "dir2", "path": "path/to/folder/dir2"}),
-            ],
-            test_mock={
-                "read_folder": lambda *args, **kwargs: (
-                    [
-                        {
-                            "name": "file1.txt",
-                            "path": "path/to/folder/file1.txt",
-                            "size": 1337,
-                        }
-                    ],
-                    [{"name": "dir2", "path": "path/to/folder/dir2"}],
-                )
-            },
-        )
-
-    @staticmethod
-    async def read_folder(
-        credentials: GithubCredentials, repo_url: str, folder_path: str, branch: str
-    ) -> tuple[list[Output.FileEntry], list[Output.DirEntry]]:
-        api = get_api(credentials)
-        contents_url = repo_url + f"/contents/{folder_path}?ref={branch}"
-        response = await api.get(contents_url)
-        data = response.json()
-
-        if not isinstance(data, list):
-            raise TypeError("Not a folder")
-
-        files: list[GithubReadFolderBlock.Output.FileEntry] = [
-            GithubReadFolderBlock.Output.FileEntry(
-                name=entry["name"],
-                path=entry["path"],
-                size=entry["size"],
-            )
-            for entry in data
-            if entry["type"] == "file"
-        ]
-
-        dirs: list[GithubReadFolderBlock.Output.DirEntry] = [
-            GithubReadFolderBlock.Output.DirEntry(
-                name=entry["name"],
-                path=entry["path"],
-            )
-            for entry in data
-            if entry["type"] == "dir"
-        ]
-
-        return files, dirs
-
-    async def run(
-        self,
-        input_data: Input,
-        *,
-        credentials: GithubCredentials,
-        **kwargs,
-    ) -> BlockOutput:
-        files, dirs = await self.read_folder(
-            credentials,
-            input_data.repo_url,
-            input_data.folder_path.lstrip("/"),
-            input_data.branch,
-        )
-        for file in files:
-            yield "file", file
-        for dir in dirs:
-            yield "dir", dir
-
-
-class GithubMakeBranchBlock(Block):
-    class Input(BlockSchemaInput):
-        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
-        repo_url: str = SchemaField(
-            description="URL of the GitHub repository",
-            placeholder="https://github.com/owner/repo",
-        )
-        new_branch: str = SchemaField(
-            description="Name of the new branch",
-            placeholder="new_branch_name",
-        )
-        source_branch: str = SchemaField(
-            description="Name of the source branch",
-            placeholder="source_branch_name",
-        )
-
-    class Output(BlockSchemaOutput):
-        status: str = SchemaField(description="Status of the branch creation operation")
-        error: str = SchemaField(
-            description="Error message if the branch creation failed"
-        )
-
-    def __init__(self):
-        super().__init__(
-            id="944cc076-95e7-4d1b-b6b6-b15d8ee5448d",
-            description="This block creates a new branch from a specified source branch.",
-            categories={BlockCategory.DEVELOPER_TOOLS},
-            input_schema=GithubMakeBranchBlock.Input,
-            output_schema=GithubMakeBranchBlock.Output,
-            test_input={
-                "repo_url": "https://github.com/owner/repo",
-                "new_branch": "new_branch_name",
-                "source_branch": "source_branch_name",
-                "credentials": TEST_CREDENTIALS_INPUT,
-            },
-            test_credentials=TEST_CREDENTIALS,
-            test_output=[("status", "Branch created successfully")],
-            test_mock={
-                "create_branch": lambda *args, **kwargs: "Branch created successfully"
-            },
-        )
-
-    @staticmethod
-    async def create_branch(
-        credentials: GithubCredentials,
-        repo_url: str,
-        new_branch: str,
-        source_branch: str,
-    ) -> str:
-        api = get_api(credentials)
-        ref_url = repo_url + f"/git/refs/heads/{source_branch}"
-        response = await api.get(ref_url)
-        data = response.json()
-        sha = data["object"]["sha"]
-
-        # Create the new branch
-        new_ref_url = repo_url + "/git/refs"
-        data = {
-            "ref": f"refs/heads/{new_branch}",
-            "sha": sha,
-        }
-        response = await api.post(new_ref_url, json=data)
-        return "Branch created successfully"
-
-    async def run(
-        self,
-        input_data: Input,
-        *,
-        credentials: GithubCredentials,
-        **kwargs,
-    ) -> BlockOutput:
-        status = await self.create_branch(
-            credentials,
-            input_data.repo_url,
-            input_data.new_branch,
-            input_data.source_branch,
-        )
-        yield "status", status
-
-
-class GithubDeleteBranchBlock(Block):
-    class Input(BlockSchemaInput):
-        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
-        repo_url: str = SchemaField(
-            description="URL of the GitHub repository",
-            placeholder="https://github.com/owner/repo",
-        )
-        branch: str = SchemaField(
-            description="Name of the branch to delete",
-            placeholder="branch_name",
-        )
-
-    class Output(BlockSchemaOutput):
-        status: str = SchemaField(description="Status of the branch deletion operation")
-        error: str = SchemaField(
-            description="Error message if the branch deletion failed"
-        )
-
-    def __init__(self):
-        super().__init__(
-            id="0d4130f7-e0ab-4d55-adc3-0a40225e80f4",
-            description="This block deletes a specified branch.",
-            categories={BlockCategory.DEVELOPER_TOOLS},
-            input_schema=GithubDeleteBranchBlock.Input,
-            output_schema=GithubDeleteBranchBlock.Output,
-            test_input={
-                "repo_url": "https://github.com/owner/repo",
-                "branch": "branch_name",
-                "credentials": TEST_CREDENTIALS_INPUT,
-            },
-            test_credentials=TEST_CREDENTIALS,
-            test_output=[("status", "Branch deleted successfully")],
-            test_mock={
-                "delete_branch": lambda *args, **kwargs: "Branch deleted successfully"
-            },
-        )
-
-    @staticmethod
-    async def delete_branch(
-        credentials: GithubCredentials, repo_url: str, branch: str
-    ) -> str:
-        api = get_api(credentials)
-        ref_url = repo_url + f"/git/refs/heads/{branch}"
-        await api.delete(ref_url)
-        return "Branch deleted successfully"
-
-    async def run(
-        self,
-        input_data: Input,
-        *,
-        credentials: GithubCredentials,
-        **kwargs,
-    ) -> BlockOutput:
-        status = await self.delete_branch(
-            credentials,
-            input_data.repo_url,
-            input_data.branch,
-        )
-        yield "status", status
-
-
-class GithubCreateFileBlock(Block):
-    class Input(BlockSchemaInput):
-        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
-        repo_url: str = SchemaField(
-            description="URL of the GitHub repository",
-            placeholder="https://github.com/owner/repo",
-        )
-        file_path: str = SchemaField(
-            description="Path where the file should be created",
-            placeholder="path/to/file.txt",
-        )
-        content: str = SchemaField(
-            description="Content to write to the file",
-            placeholder="File content here",
-        )
-        branch: str = SchemaField(
-            description="Branch where the file should be created",
-            default="main",
-        )
-        commit_message: str = SchemaField(
-            description="Message for the commit",
-            default="Create new file",
-        )
-
-    class Output(BlockSchemaOutput):
-        url: str = SchemaField(description="URL of the created file")
-        sha: str = SchemaField(description="SHA of the commit")
-        error: str = SchemaField(
-            description="Error message if the file creation failed"
-        )
-
-    def __init__(self):
-        super().__init__(
-            id="8fd132ac-b917-428a-8159-d62893e8a3fe",
-            description="This block creates a new file in a GitHub repository.",
-            categories={BlockCategory.DEVELOPER_TOOLS},
-            input_schema=GithubCreateFileBlock.Input,
-            output_schema=GithubCreateFileBlock.Output,
-            test_input={
-                "repo_url": "https://github.com/owner/repo",
-                "file_path": "test/file.txt",
-                "content": "Test content",
-                "branch": "main",
-                "commit_message": "Create test file",
-                "credentials": TEST_CREDENTIALS_INPUT,
-            },
-            test_credentials=TEST_CREDENTIALS,
-            test_output=[
-                ("url", "https://github.com/owner/repo/blob/main/test/file.txt"),
-                ("sha", "abc123"),
-            ],
-            test_mock={
-                "create_file": lambda *args, **kwargs: (
-                    "https://github.com/owner/repo/blob/main/test/file.txt",
-                    "abc123",
-                )
-            },
-        )
-
-    @staticmethod
-    async def create_file(
-        credentials: GithubCredentials,
-        repo_url: str,
-        file_path: str,
-        content: str,
-        branch: str,
-        commit_message: str,
-    ) -> tuple[str, str]:
-        api = get_api(credentials)
-        contents_url = repo_url + f"/contents/{file_path}"
-        content_base64 = base64.b64encode(content.encode()).decode()
-        data = {
-            "message": commit_message,
-            "content": content_base64,
-            "branch": branch,
-        }
-        response = await api.put(contents_url, json=data)
-        data = response.json()
-        return data["content"]["html_url"], data["commit"]["sha"]
-
-    async def run(
-        self,
-        input_data: Input,
-        *,
-        credentials: GithubCredentials,
-        **kwargs,
-    ) -> BlockOutput:
-        try:
-            url, sha = await self.create_file(
-                credentials,
-                input_data.repo_url,
-                input_data.file_path,
-                input_data.content,
-                input_data.branch,
-                input_data.commit_message,
-            )
-            yield "url", url
-            yield "sha", sha
-        except Exception as e:
-            yield "error", str(e)
-
-
-class GithubUpdateFileBlock(Block):
-    class Input(BlockSchemaInput):
-        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
-        repo_url: str = SchemaField(
-            description="URL of the GitHub repository",
-            placeholder="https://github.com/owner/repo",
-        )
-        file_path: str = SchemaField(
-            description="Path to the file to update",
-            placeholder="path/to/file.txt",
-        )
-        content: str = SchemaField(
-            description="New content for the file",
-            placeholder="Updated content here",
-        )
-        branch: str = SchemaField(
-            description="Branch containing the file",
-            default="main",
-        )
-        commit_message: str = SchemaField(
-            description="Message for the commit",
-            default="Update file",
-        )
-
-    class Output(BlockSchemaOutput):
-        url: str = SchemaField(description="URL of the updated file")
-        sha: str = SchemaField(description="SHA of the commit")
-
-    def __init__(self):
-        super().__init__(
-            id="30be12a4-57cb-4aa4-baf5-fcc68d136076",
-            description="This block updates an existing file in a GitHub repository.",
-            categories={BlockCategory.DEVELOPER_TOOLS},
-            input_schema=GithubUpdateFileBlock.Input,
-            output_schema=GithubUpdateFileBlock.Output,
-            test_input={
-                "repo_url": "https://github.com/owner/repo",
-                "file_path": "test/file.txt",
-                "content": "Updated content",
-                "branch": "main",
-                "commit_message": "Update test file",
-                "credentials": TEST_CREDENTIALS_INPUT,
-            },
-            test_credentials=TEST_CREDENTIALS,
-            test_output=[
-                ("url", "https://github.com/owner/repo/blob/main/test/file.txt"),
-                ("sha", "def456"),
-            ],
-            test_mock={
-                "update_file": lambda *args, **kwargs: (
-                    "https://github.com/owner/repo/blob/main/test/file.txt",
-                    "def456",
-                )
-            },
-        )
-
-    @staticmethod
-    async def update_file(
-        credentials: GithubCredentials,
-        repo_url: str,
-        file_path: str,
-        content: str,
-        branch: str,
-        commit_message: str,
-    ) -> tuple[str, str]:
-        api = get_api(credentials)
-        contents_url = repo_url + f"/contents/{file_path}"
-        params = {"ref": branch}
-        response = await api.get(contents_url, params=params)
-        data = response.json()
-
-        # Convert new content to base64
-        content_base64 = base64.b64encode(content.encode()).decode()
-        data = {
-            "message": commit_message,
-            "content": content_base64,
-            "sha": data["sha"],
-            "branch": branch,
-        }
-        response = await api.put(contents_url, json=data)
-        data = response.json()
-        return data["content"]["html_url"], data["commit"]["sha"]
-
-    async def run(
-        self,
-        input_data: Input,
-        *,
-        credentials: GithubCredentials,
-        **kwargs,
-    ) -> BlockOutput:
-        try:
-            url, sha = await self.update_file(
-                credentials,
-                input_data.repo_url,
-                input_data.file_path,
-                input_data.content,
-                input_data.branch,
-                input_data.commit_message,
-            )
-            yield "url", url
-            yield "sha", sha
-        except Exception as e:
-            yield "error", str(e)
-
-
 class GithubCreateRepositoryBlock(Block):
     class Input(BlockSchemaInput):
         credentials: GithubCredentialsInput = GithubCredentialsField("repo")
@@ -1103,7 +449,7 @@ class GithubListStargazersBlock(Block):
 
     def __init__(self):
         super().__init__(
-            id="a4b9c2d1-e5f6-4g7h-8i9j-0k1l2m3n4o5p",  # Generated unique UUID
+            id="e96d01ec-b55e-4a99-8ce8-c8776dce850b",  # Generated unique UUID
             description="This block lists all users who have starred a specified GitHub repository.",
             categories={BlockCategory.DEVELOPER_TOOLS},
             input_schema=GithubListStargazersBlock.Input,
@@ -1172,3 +518,230 @@ class GithubListStargazersBlock(Block):
         yield "stargazers", stargazers
         for stargazer in stargazers:
             yield "stargazer", stargazer
+
+
+class GithubGetRepositoryInfoBlock(Block):
+    class Input(BlockSchemaInput):
+        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
+        repo_url: str = SchemaField(
+            description="URL of the GitHub repository",
+            placeholder="https://github.com/owner/repo",
+        )
+
+    class Output(BlockSchemaOutput):
+        name: str = SchemaField(description="Repository name")
+        full_name: str = SchemaField(description="Full repository name (owner/repo)")
+        description: str = SchemaField(description="Repository description")
+        default_branch: str = SchemaField(description="Default branch name (e.g. main)")
+        private: bool = SchemaField(description="Whether the repository is private")
+        html_url: str = SchemaField(description="Web URL of the repository")
+        clone_url: str = SchemaField(description="Git clone URL")
+        stars: int = SchemaField(description="Number of stars")
+        forks: int = SchemaField(description="Number of forks")
+        open_issues: int = SchemaField(description="Number of open issues")
+        error: str = SchemaField(
+            description="Error message if fetching repo info failed"
+        )
+
+    def __init__(self):
+        super().__init__(
+            id="59d4f241-968a-4040-95da-348ac5c5ce27",
+            description="This block retrieves metadata about a GitHub repository.",
+            categories={BlockCategory.DEVELOPER_TOOLS},
+            input_schema=GithubGetRepositoryInfoBlock.Input,
+            output_schema=GithubGetRepositoryInfoBlock.Output,
+            test_input={
+                "repo_url": "https://github.com/owner/repo",
+                "credentials": TEST_CREDENTIALS_INPUT,
+            },
+            test_credentials=TEST_CREDENTIALS,
+            test_output=[
+                ("name", "repo"),
+                ("full_name", "owner/repo"),
+                ("description", "A test repo"),
+                ("default_branch", "main"),
+                ("private", False),
+                ("html_url", "https://github.com/owner/repo"),
+                ("clone_url", "https://github.com/owner/repo.git"),
+                ("stars", 42),
+                ("forks", 5),
+                ("open_issues", 3),
+            ],
+            test_mock={
+                "get_repo_info": lambda *args, **kwargs: {
+                    "name": "repo",
+                    "full_name": "owner/repo",
+                    "description": "A test repo",
+                    "default_branch": "main",
+                    "private": False,
+                    "html_url": "https://github.com/owner/repo",
+                    "clone_url": "https://github.com/owner/repo.git",
+                    "stargazers_count": 42,
+                    "forks_count": 5,
+                    "open_issues_count": 3,
+                }
+            },
+        )
+
+    @staticmethod
+    async def get_repo_info(credentials: GithubCredentials, repo_url: str) -> dict:
+        api = get_api(credentials)
+        response = await api.get(repo_url)
+        return response.json()
+
+    async def run(
+        self,
+        input_data: Input,
+        *,
+        credentials: GithubCredentials,
+        **kwargs,
+    ) -> BlockOutput:
+        try:
+            data = await self.get_repo_info(credentials, input_data.repo_url)
+            yield "name", data["name"]
+            yield "full_name", data["full_name"]
+            yield "description", data.get("description", "") or ""
+            yield "default_branch", data["default_branch"]
+            yield "private", data["private"]
+            yield "html_url", data["html_url"]
+            yield "clone_url", data["clone_url"]
+            yield "stars", data["stargazers_count"]
+            yield "forks", data["forks_count"]
+            yield "open_issues", data["open_issues_count"]
+        except Exception as e:
+            yield "error", str(e)
+
+
+class GithubForkRepositoryBlock(Block):
+    class Input(BlockSchemaInput):
+        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
+        repo_url: str = SchemaField(
+            description="URL of the GitHub repository to fork",
+            placeholder="https://github.com/owner/repo",
+        )
+        organization: str = SchemaField(
+            description="Organization to fork into (leave empty to fork to your account)",
+            default="",
+        )
+
+    class Output(BlockSchemaOutput):
+        url: str = SchemaField(description="URL of the forked repository")
+        clone_url: str = SchemaField(description="Git clone URL of the fork")
+        full_name: str = SchemaField(description="Full name of the fork (owner/repo)")
+        error: str = SchemaField(description="Error message if the fork failed")
+
+    def __init__(self):
+        super().__init__(
+            id="a439f2f4-835f-4dae-ba7b-0205ffa70be6",
+            description="This block forks a GitHub repository to your account or an organization.",
+            categories={BlockCategory.DEVELOPER_TOOLS},
+            input_schema=GithubForkRepositoryBlock.Input,
+            output_schema=GithubForkRepositoryBlock.Output,
+            test_input={
+                "repo_url": "https://github.com/owner/repo",
+                "organization": "",
+                "credentials": TEST_CREDENTIALS_INPUT,
+            },
+            test_credentials=TEST_CREDENTIALS,
+            test_output=[
+                ("url", "https://github.com/myuser/repo"),
+                ("clone_url", "https://github.com/myuser/repo.git"),
+                ("full_name", "myuser/repo"),
+            ],
+            test_mock={
+                "fork_repo": lambda *args, **kwargs: (
+                    "https://github.com/myuser/repo",
+                    "https://github.com/myuser/repo.git",
+                    "myuser/repo",
+                )
+            },
+        )
+
+    @staticmethod
+    async def fork_repo(
+        credentials: GithubCredentials,
+        repo_url: str,
+        organization: str,
+    ) -> tuple[str, str, str]:
+        api = get_api(credentials)
+        forks_url = repo_url + "/forks"
+        data: dict[str, str] = {}
+        if organization:
+            data["organization"] = organization
+        response = await api.post(forks_url, json=data)
+        result = response.json()
+        return result["html_url"], result["clone_url"], result["full_name"]
+
+    async def run(
+        self,
+        input_data: Input,
+        *,
+        credentials: GithubCredentials,
+        **kwargs,
+    ) -> BlockOutput:
+        try:
+            url, clone_url, full_name = await self.fork_repo(
+                credentials,
+                input_data.repo_url,
+                input_data.organization,
+            )
+            yield "url", url
+            yield "clone_url", clone_url
+            yield "full_name", full_name
+        except Exception as e:
+            yield "error", str(e)
+
+
+class GithubStarRepositoryBlock(Block):
+    class Input(BlockSchemaInput):
+        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
+        repo_url: str = SchemaField(
+            description="URL of the GitHub repository to star",
+            placeholder="https://github.com/owner/repo",
+        )
+
+    class Output(BlockSchemaOutput):
+        status: str = SchemaField(description="Status of the star operation")
+        error: str = SchemaField(description="Error message if starring failed")
+
+    def __init__(self):
+        super().__init__(
+            id="bd700764-53e3-44dd-a969-d1854088458f",
+            description="This block stars a GitHub repository.",
+            categories={BlockCategory.DEVELOPER_TOOLS},
+            input_schema=GithubStarRepositoryBlock.Input,
+            output_schema=GithubStarRepositoryBlock.Output,
+            test_input={
+                "repo_url": "https://github.com/owner/repo",
+                "credentials": TEST_CREDENTIALS_INPUT,
+            },
+            test_credentials=TEST_CREDENTIALS,
+            test_output=[("status", "Repository starred successfully")],
+            test_mock={
+                "star_repo": lambda *args, **kwargs: "Repository starred successfully"
+            },
+        )
+
+    @staticmethod
+    async def star_repo(credentials: GithubCredentials, repo_url: str) -> str:
+        api = get_api(credentials, convert_urls=False)
+        repo_path = github_repo_path(repo_url)
+        owner, repo = repo_path.split("/")
+        await api.put(
+            f"https://api.github.com/user/starred/{owner}/{repo}",
+            headers={"Content-Length": "0"},
+        )
+        return "Repository starred successfully"
+
+    async def run(
+        self,
+        input_data: Input,
+        *,
+        credentials: GithubCredentials,
+        **kwargs,
+    ) -> BlockOutput:
+        try:
+            status = await self.star_repo(credentials, input_data.repo_url)
+            yield "status", status
+        except Exception as e:
+            yield "error", str(e)

autogpt_platform/backend/backend/blocks/github/repo_branches.py

@@ -0,0 +1,452 @@
+from urllib.parse import quote
+
+from typing_extensions import TypedDict
+
+from backend.blocks._base import (
+    Block,
+    BlockCategory,
+    BlockOutput,
+    BlockSchemaInput,
+    BlockSchemaOutput,
+)
+from backend.data.model import SchemaField
+
+from ._api import get_api
+from ._auth import (
+    TEST_CREDENTIALS,
+    TEST_CREDENTIALS_INPUT,
+    GithubCredentials,
+    GithubCredentialsField,
+    GithubCredentialsInput,
+)
+from ._utils import github_repo_path
+
+
+class GithubListBranchesBlock(Block):
+    class Input(BlockSchemaInput):
+        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
+        repo_url: str = SchemaField(
+            description="URL of the GitHub repository",
+            placeholder="https://github.com/owner/repo",
+        )
+        per_page: int = SchemaField(
+            description="Number of branches to return per page (max 100)",
+            default=30,
+            ge=1,
+            le=100,
+        )
+        page: int = SchemaField(
+            description="Page number for pagination",
+            default=1,
+            ge=1,
+        )
+
+    class Output(BlockSchemaOutput):
+        class BranchItem(TypedDict):
+            name: str
+            url: str
+
+        branch: BranchItem = SchemaField(
+            title="Branch",
+            description="Branches with their name and file tree browser URL",
+        )
+        branches: list[BranchItem] = SchemaField(
+            description="List of branches with their name and file tree browser URL"
+        )
+        error: str = SchemaField(description="Error message if listing branches failed")
+
+    def __init__(self):
+        super().__init__(
+            id="74243e49-2bec-4916-8bf4-db43d44aead5",
+            description="This block lists all branches for a specified GitHub repository.",
+            categories={BlockCategory.DEVELOPER_TOOLS},
+            input_schema=GithubListBranchesBlock.Input,
+            output_schema=GithubListBranchesBlock.Output,
+            test_input={
+                "repo_url": "https://github.com/owner/repo",
+                "per_page": 30,
+                "page": 1,
+                "credentials": TEST_CREDENTIALS_INPUT,
+            },
+            test_credentials=TEST_CREDENTIALS,
+            test_output=[
+                (
+                    "branches",
+                    [
+                        {
+                            "name": "main",
+                            "url": "https://github.com/owner/repo/tree/main",
+                        }
+                    ],
+                ),
+                (
+                    "branch",
+                    {
+                        "name": "main",
+                        "url": "https://github.com/owner/repo/tree/main",
+                    },
+                ),
+            ],
+            test_mock={
+                "list_branches": lambda *args, **kwargs: [
+                    {
+                        "name": "main",
+                        "url": "https://github.com/owner/repo/tree/main",
+                    }
+                ]
+            },
+        )
+
+    @staticmethod
+    async def list_branches(
+        credentials: GithubCredentials, repo_url: str, per_page: int, page: int
+    ) -> list[Output.BranchItem]:
+        api = get_api(credentials)
+        branches_url = repo_url + "/branches"
+        response = await api.get(
+            branches_url, params={"per_page": str(per_page), "page": str(page)}
+        )
+        data = response.json()
+        repo_path = github_repo_path(repo_url)
+        branches: list[GithubListBranchesBlock.Output.BranchItem] = [
+            {
+                "name": branch["name"],
+                "url": f"https://github.com/{repo_path}/tree/{branch['name']}",
+            }
+            for branch in data
+        ]
+        return branches
+
+    async def run(
+        self,
+        input_data: Input,
+        *,
+        credentials: GithubCredentials,
+        **kwargs,
+    ) -> BlockOutput:
+        try:
+            branches = await self.list_branches(
+                credentials,
+                input_data.repo_url,
+                input_data.per_page,
+                input_data.page,
+            )
+            yield "branches", branches
+            for branch in branches:
+                yield "branch", branch
+        except Exception as e:
+            yield "error", str(e)
+
+
+class GithubMakeBranchBlock(Block):
+    class Input(BlockSchemaInput):
+        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
+        repo_url: str = SchemaField(
+            description="URL of the GitHub repository",
+            placeholder="https://github.com/owner/repo",
+        )
+        new_branch: str = SchemaField(
+            description="Name of the new branch",
+            placeholder="new_branch_name",
+        )
+        source_branch: str = SchemaField(
+            description="Name of the source branch",
+            placeholder="source_branch_name",
+        )
+
+    class Output(BlockSchemaOutput):
+        status: str = SchemaField(description="Status of the branch creation operation")
+        error: str = SchemaField(
+            description="Error message if the branch creation failed"
+        )
+
+    def __init__(self):
+        super().__init__(
+            id="944cc076-95e7-4d1b-b6b6-b15d8ee5448d",
+            description="This block creates a new branch from a specified source branch.",
+            categories={BlockCategory.DEVELOPER_TOOLS},
+            input_schema=GithubMakeBranchBlock.Input,
+            output_schema=GithubMakeBranchBlock.Output,
+            test_input={
+                "repo_url": "https://github.com/owner/repo",
+                "new_branch": "new_branch_name",
+                "source_branch": "source_branch_name",
+                "credentials": TEST_CREDENTIALS_INPUT,
+            },
+            test_credentials=TEST_CREDENTIALS,
+            test_output=[("status", "Branch created successfully")],
+            test_mock={
+                "create_branch": lambda *args, **kwargs: "Branch created successfully"
+            },
+        )
+
+    @staticmethod
+    async def create_branch(
+        credentials: GithubCredentials,
+        repo_url: str,
+        new_branch: str,
+        source_branch: str,
+    ) -> str:
+        api = get_api(credentials)
+        ref_url = repo_url + f"/git/refs/heads/{quote(source_branch, safe='')}"
+        response = await api.get(ref_url)
+        data = response.json()
+        sha = data["object"]["sha"]
+
+        # Create the new branch
+        new_ref_url = repo_url + "/git/refs"
+        data = {
+            "ref": f"refs/heads/{new_branch}",
+            "sha": sha,
+        }
+        response = await api.post(new_ref_url, json=data)
+        return "Branch created successfully"
+
+    async def run(
+        self,
+        input_data: Input,
+        *,
+        credentials: GithubCredentials,
+        **kwargs,
+    ) -> BlockOutput:
+        try:
+            status = await self.create_branch(
+                credentials,
+                input_data.repo_url,
+                input_data.new_branch,
+                input_data.source_branch,
+            )
+            yield "status", status
+        except Exception as e:
+            yield "error", str(e)
+
+
+class GithubDeleteBranchBlock(Block):
+    class Input(BlockSchemaInput):
+        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
+        repo_url: str = SchemaField(
+            description="URL of the GitHub repository",
+            placeholder="https://github.com/owner/repo",
+        )
+        branch: str = SchemaField(
+            description="Name of the branch to delete",
+            placeholder="branch_name",
+        )
+
+    class Output(BlockSchemaOutput):
+        status: str = SchemaField(description="Status of the branch deletion operation")
+        error: str = SchemaField(
+            description="Error message if the branch deletion failed"
+        )
+
+    def __init__(self):
+        super().__init__(
+            id="0d4130f7-e0ab-4d55-adc3-0a40225e80f4",
+            description="This block deletes a specified branch.",
+            categories={BlockCategory.DEVELOPER_TOOLS},
+            input_schema=GithubDeleteBranchBlock.Input,
+            output_schema=GithubDeleteBranchBlock.Output,
+            test_input={
+                "repo_url": "https://github.com/owner/repo",
+                "branch": "branch_name",
+                "credentials": TEST_CREDENTIALS_INPUT,
+            },
+            test_credentials=TEST_CREDENTIALS,
+            test_output=[("status", "Branch deleted successfully")],
+            test_mock={
+                "delete_branch": lambda *args, **kwargs: "Branch deleted successfully"
+            },
+            is_sensitive_action=True,
+        )
+
+    @staticmethod
+    async def delete_branch(
+        credentials: GithubCredentials, repo_url: str, branch: str
+    ) -> str:
+        api = get_api(credentials)
+        ref_url = repo_url + f"/git/refs/heads/{quote(branch, safe='')}"
+        await api.delete(ref_url)
+        return "Branch deleted successfully"
+
+    async def run(
+        self,
+        input_data: Input,
+        *,
+        credentials: GithubCredentials,
+        **kwargs,
+    ) -> BlockOutput:
+        try:
+            status = await self.delete_branch(
+                credentials,
+                input_data.repo_url,
+                input_data.branch,
+            )
+            yield "status", status
+        except Exception as e:
+            yield "error", str(e)
+
+
+class GithubCompareBranchesBlock(Block):
+    class Input(BlockSchemaInput):
+        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
+        repo_url: str = SchemaField(
+            description="URL of the GitHub repository",
+            placeholder="https://github.com/owner/repo",
+        )
+        base: str = SchemaField(
+            description="Base branch or commit SHA",
+            placeholder="main",
+        )
+        head: str = SchemaField(
+            description="Head branch or commit SHA to compare against base",
+            placeholder="feature-branch",
+        )
+
+    class Output(BlockSchemaOutput):
+        class FileChange(TypedDict):
+            filename: str
+            status: str
+            additions: int
+            deletions: int
+            patch: str
+
+        status: str = SchemaField(
+            description="Comparison status: ahead, behind, diverged, or identical"
+        )
+        ahead_by: int = SchemaField(
+            description="Number of commits head is ahead of base"
+        )
+        behind_by: int = SchemaField(
+            description="Number of commits head is behind base"
+        )
+        total_commits: int = SchemaField(
+            description="Total number of commits in the comparison"
+        )
+        diff: str = SchemaField(description="Unified diff of all file changes")
+        file: FileChange = SchemaField(
+            title="Changed File", description="A changed file with its diff"
+        )
+        files: list[FileChange] = SchemaField(
+            description="List of changed files with their diffs"
+        )
+        error: str = SchemaField(description="Error message if comparison failed")
+
+    def __init__(self):
+        super().__init__(
+            id="2e4faa8c-6086-4546-ba77-172d1d560186",
+            description="This block compares two branches or commits in a GitHub repository.",
+            categories={BlockCategory.DEVELOPER_TOOLS},
+            input_schema=GithubCompareBranchesBlock.Input,
+            output_schema=GithubCompareBranchesBlock.Output,
+            test_input={
+                "repo_url": "https://github.com/owner/repo",
+                "base": "main",
+                "head": "feature",
+                "credentials": TEST_CREDENTIALS_INPUT,
+            },
+            test_credentials=TEST_CREDENTIALS,
+            test_output=[
+                ("status", "ahead"),
+                ("ahead_by", 2),
+                ("behind_by", 0),
+                ("total_commits", 2),
+                ("diff", "+++ b/file.py\n+new line"),
+                (
+                    "files",
+                    [
+                        {
+                            "filename": "file.py",
+                            "status": "modified",
+                            "additions": 1,
+                            "deletions": 0,
+                            "patch": "+new line",
+                        }
+                    ],
+                ),
+                (
+                    "file",
+                    {
+                        "filename": "file.py",
+                        "status": "modified",
+                        "additions": 1,
+                        "deletions": 0,
+                        "patch": "+new line",
+                    },
+                ),
+            ],
+            test_mock={
+                "compare_branches": lambda *args, **kwargs: {
+                    "status": "ahead",
+                    "ahead_by": 2,
+                    "behind_by": 0,
+                    "total_commits": 2,
+                    "files": [
+                        {
+                            "filename": "file.py",
+                            "status": "modified",
+                            "additions": 1,
+                            "deletions": 0,
+                            "patch": "+new line",
+                        }
+                    ],
+                }
+            },
+        )
+
+    @staticmethod
+    async def compare_branches(
+        credentials: GithubCredentials,
+        repo_url: str,
+        base: str,
+        head: str,
+    ) -> dict:
+        api = get_api(credentials)
+        safe_base = quote(base, safe="")
+        safe_head = quote(head, safe="")
+        compare_url = repo_url + f"/compare/{safe_base}...{safe_head}"
+        response = await api.get(compare_url)
+        return response.json()
+
+    async def run(
+        self,
+        input_data: Input,
+        *,
+        credentials: GithubCredentials,
+        **kwargs,
+    ) -> BlockOutput:
+        try:
+            data = await self.compare_branches(
+                credentials,
+                input_data.repo_url,
+                input_data.base,
+                input_data.head,
+            )
+            yield "status", data["status"]
+            yield "ahead_by", data["ahead_by"]
+            yield "behind_by", data["behind_by"]
+            yield "total_commits", data["total_commits"]
+
+            files: list[GithubCompareBranchesBlock.Output.FileChange] = [
+                GithubCompareBranchesBlock.Output.FileChange(
+                    filename=f["filename"],
+                    status=f["status"],
+                    additions=f["additions"],
+                    deletions=f["deletions"],
+                    patch=f.get("patch", ""),
+                )
+                for f in data.get("files", [])
+            ]
+
+            # Build unified diff
+            diff_parts = []
+            for f in data.get("files", []):
+                patch = f.get("patch", "")
+                if patch:
+                    diff_parts.append(f"+++ b/{f['filename']}\n{patch}")
+            yield "diff", "\n".join(diff_parts)
+
+            yield "files", files
+            for file in files:
+                yield "file", file
+        except Exception as e:
+            yield "error", str(e)

autogpt_platform/backend/backend/blocks/github/repo_files.py

@@ -0,0 +1,720 @@
+import base64
+from urllib.parse import quote
+
+from typing_extensions import TypedDict
+
+from backend.blocks._base import (
+    Block,
+    BlockCategory,
+    BlockOutput,
+    BlockSchemaInput,
+    BlockSchemaOutput,
+)
+from backend.data.model import SchemaField
+
+from ._api import get_api
+from ._auth import (
+    TEST_CREDENTIALS,
+    TEST_CREDENTIALS_INPUT,
+    GithubCredentials,
+    GithubCredentialsField,
+    GithubCredentialsInput,
+)
+
+
+class GithubReadFileBlock(Block):
+    class Input(BlockSchemaInput):
+        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
+        repo_url: str = SchemaField(
+            description="URL of the GitHub repository",
+            placeholder="https://github.com/owner/repo",
+        )
+        file_path: str = SchemaField(
+            description="Path to the file in the repository",
+            placeholder="path/to/file",
+        )
+        branch: str = SchemaField(
+            description="Branch to read from",
+            placeholder="branch_name",
+            default="main",
+        )
+
+    class Output(BlockSchemaOutput):
+        text_content: str = SchemaField(
+            description="Content of the file (decoded as UTF-8 text)"
+        )
+        raw_content: str = SchemaField(
+            description="Raw base64-encoded content of the file"
+        )
+        size: int = SchemaField(description="The size of the file (in bytes)")
+        error: str = SchemaField(description="Error message if reading the file failed")
+
+    def __init__(self):
+        super().__init__(
+            id="87ce6c27-5752-4bbc-8e26-6da40a3dcfd3",
+            description="This block reads the content of a specified file from a GitHub repository.",
+            categories={BlockCategory.DEVELOPER_TOOLS},
+            input_schema=GithubReadFileBlock.Input,
+            output_schema=GithubReadFileBlock.Output,
+            test_input={
+                "repo_url": "https://github.com/owner/repo",
+                "file_path": "path/to/file",
+                "branch": "main",
+                "credentials": TEST_CREDENTIALS_INPUT,
+            },
+            test_credentials=TEST_CREDENTIALS,
+            test_output=[
+                ("raw_content", "RmlsZSBjb250ZW50"),
+                ("text_content", "File content"),
+                ("size", 13),
+            ],
+            test_mock={"read_file": lambda *args, **kwargs: ("RmlsZSBjb250ZW50", 13)},
+        )
+
+    @staticmethod
+    async def read_file(
+        credentials: GithubCredentials, repo_url: str, file_path: str, branch: str
+    ) -> tuple[str, int]:
+        api = get_api(credentials)
+        content_url = (
+            repo_url
+            + f"/contents/{quote(file_path, safe='')}?ref={quote(branch, safe='')}"
+        )
+        response = await api.get(content_url)
+        data = response.json()
+
+        if isinstance(data, list):
+            # Multiple entries of different types exist at this path
+            if not (file := next((f for f in data if f["type"] == "file"), None)):
+                raise TypeError("Not a file")
+            data = file
+
+        if data["type"] != "file":
+            raise TypeError("Not a file")
+
+        return data["content"], data["size"]
+
+    async def run(
+        self,
+        input_data: Input,
+        *,
+        credentials: GithubCredentials,
+        **kwargs,
+    ) -> BlockOutput:
+        try:
+            content, size = await self.read_file(
+                credentials,
+                input_data.repo_url,
+                input_data.file_path,
+                input_data.branch,
+            )
+            yield "raw_content", content
+            yield "text_content", base64.b64decode(content).decode("utf-8")
+            yield "size", size
+        except Exception as e:
+            yield "error", str(e)
+
+
+class GithubReadFolderBlock(Block):
+    class Input(BlockSchemaInput):
+        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
+        repo_url: str = SchemaField(
+            description="URL of the GitHub repository",
+            placeholder="https://github.com/owner/repo",
+        )
+        folder_path: str = SchemaField(
+            description="Path to the folder in the repository",
+            placeholder="path/to/folder",
+        )
+        branch: str = SchemaField(
+            description="Branch name to read from (defaults to main)",
+            placeholder="branch_name",
+            default="main",
+        )
+
+    class Output(BlockSchemaOutput):
+        class DirEntry(TypedDict):
+            name: str
+            path: str
+
+        class FileEntry(TypedDict):
+            name: str
+            path: str
+            size: int
+
+        file: FileEntry = SchemaField(description="Files in the folder")
+        dir: DirEntry = SchemaField(description="Directories in the folder")
+        error: str = SchemaField(
+            description="Error message if reading the folder failed"
+        )
+
+    def __init__(self):
+        super().__init__(
+            id="1355f863-2db3-4d75-9fba-f91e8a8ca400",
+            description="This block reads the content of a specified folder from a GitHub repository.",
+            categories={BlockCategory.DEVELOPER_TOOLS},
+            input_schema=GithubReadFolderBlock.Input,
+            output_schema=GithubReadFolderBlock.Output,
+            test_input={
+                "repo_url": "https://github.com/owner/repo",
+                "folder_path": "path/to/folder",
+                "branch": "main",
+                "credentials": TEST_CREDENTIALS_INPUT,
+            },
+            test_credentials=TEST_CREDENTIALS,
+            test_output=[
+                (
+                    "file",
+                    {
+                        "name": "file1.txt",
+                        "path": "path/to/folder/file1.txt",
+                        "size": 1337,
+                    },
+                ),
+                ("dir", {"name": "dir2", "path": "path/to/folder/dir2"}),
+            ],
+            test_mock={
+                "read_folder": lambda *args, **kwargs: (
+                    [
+                        {
+                            "name": "file1.txt",
+                            "path": "path/to/folder/file1.txt",
+                            "size": 1337,
+                        }
+                    ],
+                    [{"name": "dir2", "path": "path/to/folder/dir2"}],
+                )
+            },
+        )
+
+    @staticmethod
+    async def read_folder(
+        credentials: GithubCredentials, repo_url: str, folder_path: str, branch: str
+    ) -> tuple[list[Output.FileEntry], list[Output.DirEntry]]:
+        api = get_api(credentials)
+        contents_url = (
+            repo_url
+            + f"/contents/{quote(folder_path, safe='/')}?ref={quote(branch, safe='')}"
+        )
+        response = await api.get(contents_url)
+        data = response.json()
+
+        if not isinstance(data, list):
+            raise TypeError("Not a folder")
+
+        files: list[GithubReadFolderBlock.Output.FileEntry] = [
+            GithubReadFolderBlock.Output.FileEntry(
+                name=entry["name"],
+                path=entry["path"],
+                size=entry["size"],
+            )
+            for entry in data
+            if entry["type"] == "file"
+        ]
+
+        dirs: list[GithubReadFolderBlock.Output.DirEntry] = [
+            GithubReadFolderBlock.Output.DirEntry(
+                name=entry["name"],
+                path=entry["path"],
+            )
+            for entry in data
+            if entry["type"] == "dir"
+        ]
+
+        return files, dirs
+
+    async def run(
+        self,
+        input_data: Input,
+        *,
+        credentials: GithubCredentials,
+        **kwargs,
+    ) -> BlockOutput:
+        try:
+            files, dirs = await self.read_folder(
+                credentials,
+                input_data.repo_url,
+                input_data.folder_path.lstrip("/"),
+                input_data.branch,
+            )
+            for file in files:
+                yield "file", file
+            for dir in dirs:
+                yield "dir", dir
+        except Exception as e:
+            yield "error", str(e)
+
+
+class GithubCreateFileBlock(Block):
+    class Input(BlockSchemaInput):
+        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
+        repo_url: str = SchemaField(
+            description="URL of the GitHub repository",
+            placeholder="https://github.com/owner/repo",
+        )
+        file_path: str = SchemaField(
+            description="Path where the file should be created",
+            placeholder="path/to/file.txt",
+        )
+        content: str = SchemaField(
+            description="Content to write to the file",
+            placeholder="File content here",
+        )
+        branch: str = SchemaField(
+            description="Branch where the file should be created",
+            default="main",
+        )
+        commit_message: str = SchemaField(
+            description="Message for the commit",
+            default="Create new file",
+        )
+
+    class Output(BlockSchemaOutput):
+        url: str = SchemaField(description="URL of the created file")
+        sha: str = SchemaField(description="SHA of the commit")
+        error: str = SchemaField(
+            description="Error message if the file creation failed"
+        )
+
+    def __init__(self):
+        super().__init__(
+            id="8fd132ac-b917-428a-8159-d62893e8a3fe",
+            description="This block creates a new file in a GitHub repository.",
+            categories={BlockCategory.DEVELOPER_TOOLS},
+            input_schema=GithubCreateFileBlock.Input,
+            output_schema=GithubCreateFileBlock.Output,
+            test_input={
+                "repo_url": "https://github.com/owner/repo",
+                "file_path": "test/file.txt",
+                "content": "Test content",
+                "branch": "main",
+                "commit_message": "Create test file",
+                "credentials": TEST_CREDENTIALS_INPUT,
+            },
+            test_credentials=TEST_CREDENTIALS,
+            test_output=[
+                ("url", "https://github.com/owner/repo/blob/main/test/file.txt"),
+                ("sha", "abc123"),
+            ],
+            test_mock={
+                "create_file": lambda *args, **kwargs: (
+                    "https://github.com/owner/repo/blob/main/test/file.txt",
+                    "abc123",
+                )
+            },
+        )
+
+    @staticmethod
+    async def create_file(
+        credentials: GithubCredentials,
+        repo_url: str,
+        file_path: str,
+        content: str,
+        branch: str,
+        commit_message: str,
+    ) -> tuple[str, str]:
+        api = get_api(credentials)
+        contents_url = repo_url + f"/contents/{quote(file_path, safe='/')}"
+        content_base64 = base64.b64encode(content.encode()).decode()
+        data = {
+            "message": commit_message,
+            "content": content_base64,
+            "branch": branch,
+        }
+        response = await api.put(contents_url, json=data)
+        data = response.json()
+        return data["content"]["html_url"], data["commit"]["sha"]
+
+    async def run(
+        self,
+        input_data: Input,
+        *,
+        credentials: GithubCredentials,
+        **kwargs,
+    ) -> BlockOutput:
+        try:
+            url, sha = await self.create_file(
+                credentials,
+                input_data.repo_url,
+                input_data.file_path,
+                input_data.content,
+                input_data.branch,
+                input_data.commit_message,
+            )
+            yield "url", url
+            yield "sha", sha
+        except Exception as e:
+            yield "error", str(e)
+
+
+class GithubUpdateFileBlock(Block):
+    class Input(BlockSchemaInput):
+        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
+        repo_url: str = SchemaField(
+            description="URL of the GitHub repository",
+            placeholder="https://github.com/owner/repo",
+        )
+        file_path: str = SchemaField(
+            description="Path to the file to update",
+            placeholder="path/to/file.txt",
+        )
+        content: str = SchemaField(
+            description="New content for the file",
+            placeholder="Updated content here",
+        )
+        branch: str = SchemaField(
+            description="Branch containing the file",
+            default="main",
+        )
+        commit_message: str = SchemaField(
+            description="Message for the commit",
+            default="Update file",
+        )
+
+    class Output(BlockSchemaOutput):
+        url: str = SchemaField(description="URL of the updated file")
+        sha: str = SchemaField(description="SHA of the commit")
+
+    def __init__(self):
+        super().__init__(
+            id="30be12a4-57cb-4aa4-baf5-fcc68d136076",
+            description="This block updates an existing file in a GitHub repository.",
+            categories={BlockCategory.DEVELOPER_TOOLS},
+            input_schema=GithubUpdateFileBlock.Input,
+            output_schema=GithubUpdateFileBlock.Output,
+            test_input={
+                "repo_url": "https://github.com/owner/repo",
+                "file_path": "test/file.txt",
+                "content": "Updated content",
+                "branch": "main",
+                "commit_message": "Update test file",
+                "credentials": TEST_CREDENTIALS_INPUT,
+            },
+            test_credentials=TEST_CREDENTIALS,
+            test_output=[
+                ("url", "https://github.com/owner/repo/blob/main/test/file.txt"),
+                ("sha", "def456"),
+            ],
+            test_mock={
+                "update_file": lambda *args, **kwargs: (
+                    "https://github.com/owner/repo/blob/main/test/file.txt",
+                    "def456",
+                )
+            },
+        )
+
+    @staticmethod
+    async def update_file(
+        credentials: GithubCredentials,
+        repo_url: str,
+        file_path: str,
+        content: str,
+        branch: str,
+        commit_message: str,
+    ) -> tuple[str, str]:
+        api = get_api(credentials)
+        contents_url = repo_url + f"/contents/{quote(file_path, safe='/')}"
+        params = {"ref": branch}
+        response = await api.get(contents_url, params=params)
+        data = response.json()
+
+        # Convert new content to base64
+        content_base64 = base64.b64encode(content.encode()).decode()
+        data = {
+            "message": commit_message,
+            "content": content_base64,
+            "sha": data["sha"],
+            "branch": branch,
+        }
+        response = await api.put(contents_url, json=data)
+        data = response.json()
+        return data["content"]["html_url"], data["commit"]["sha"]
+
+    async def run(
+        self,
+        input_data: Input,
+        *,
+        credentials: GithubCredentials,
+        **kwargs,
+    ) -> BlockOutput:
+        try:
+            url, sha = await self.update_file(
+                credentials,
+                input_data.repo_url,
+                input_data.file_path,
+                input_data.content,
+                input_data.branch,
+                input_data.commit_message,
+            )
+            yield "url", url
+            yield "sha", sha
+        except Exception as e:
+            yield "error", str(e)
+
+
+class GithubSearchCodeBlock(Block):
+    class Input(BlockSchemaInput):
+        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
+        query: str = SchemaField(
+            description="Search query (GitHub code search syntax)",
+            placeholder="className language:python",
+        )
+        repo: str = SchemaField(
+            description="Restrict search to a repository (owner/repo format, optional)",
+            default="",
+            placeholder="owner/repo",
+        )
+        per_page: int = SchemaField(
+            description="Number of results to return (max 100)",
+            default=30,
+            ge=1,
+            le=100,
+        )
+
+    class Output(BlockSchemaOutput):
+        class SearchResult(TypedDict):
+            name: str
+            path: str
+            repository: str
+            url: str
+            score: float
+
+        result: SearchResult = SchemaField(
+            title="Result", description="A code search result"
+        )
+        results: list[SearchResult] = SchemaField(
+            description="List of code search results"
+        )
+        total_count: int = SchemaField(description="Total number of matching results")
+        error: str = SchemaField(description="Error message if search failed")
+
+    def __init__(self):
+        super().__init__(
+            id="47f94891-a2b1-4f1c-b5f2-573c043f721e",
+            description="This block searches for code in GitHub repositories.",
+            categories={BlockCategory.DEVELOPER_TOOLS},
+            input_schema=GithubSearchCodeBlock.Input,
+            output_schema=GithubSearchCodeBlock.Output,
+            test_input={
+                "query": "addClass",
+                "repo": "owner/repo",
+                "per_page": 30,
+                "credentials": TEST_CREDENTIALS_INPUT,
+            },
+            test_credentials=TEST_CREDENTIALS,
+            test_output=[
+                ("total_count", 1),
+                (
+                    "results",
+                    [
+                        {
+                            "name": "file.py",
+                            "path": "src/file.py",
+                            "repository": "owner/repo",
+                            "url": "https://github.com/owner/repo/blob/main/src/file.py",
+                            "score": 1.0,
+                        }
+                    ],
+                ),
+                (
+                    "result",
+                    {
+                        "name": "file.py",
+                        "path": "src/file.py",
+                        "repository": "owner/repo",
+                        "url": "https://github.com/owner/repo/blob/main/src/file.py",
+                        "score": 1.0,
+                    },
+                ),
+            ],
+            test_mock={
+                "search_code": lambda *args, **kwargs: (
+                    1,
+                    [
+                        {
+                            "name": "file.py",
+                            "path": "src/file.py",
+                            "repository": "owner/repo",
+                            "url": "https://github.com/owner/repo/blob/main/src/file.py",
+                            "score": 1.0,
+                        }
+                    ],
+                )
+            },
+        )
+
+    @staticmethod
+    async def search_code(
+        credentials: GithubCredentials,
+        query: str,
+        repo: str,
+        per_page: int,
+    ) -> tuple[int, list[Output.SearchResult]]:
+        api = get_api(credentials, convert_urls=False)
+        full_query = f"{query} repo:{repo}" if repo else query
+        params = {"q": full_query, "per_page": str(per_page)}
+        response = await api.get("https://api.github.com/search/code", params=params)
+        data = response.json()
+        results: list[GithubSearchCodeBlock.Output.SearchResult] = [
+            GithubSearchCodeBlock.Output.SearchResult(
+                name=item["name"],
+                path=item["path"],
+                repository=item["repository"]["full_name"],
+                url=item["html_url"],
+                score=item["score"],
+            )
+            for item in data["items"]
+        ]
+        return data["total_count"], results
+
+    async def run(
+        self,
+        input_data: Input,
+        *,
+        credentials: GithubCredentials,
+        **kwargs,
+    ) -> BlockOutput:
+        try:
+            total_count, results = await self.search_code(
+                credentials,
+                input_data.query,
+                input_data.repo,
+                input_data.per_page,
+            )
+            yield "total_count", total_count
+            yield "results", results
+            for result in results:
+                yield "result", result
+        except Exception as e:
+            yield "error", str(e)
+
+
+class GithubGetRepositoryTreeBlock(Block):
+    class Input(BlockSchemaInput):
+        credentials: GithubCredentialsInput = GithubCredentialsField("repo")
+        repo_url: str = SchemaField(
+            description="URL of the GitHub repository",
+            placeholder="https://github.com/owner/repo",
+        )
+        branch: str = SchemaField(
+            description="Branch name to get the tree from",
+            default="main",
+        )
+        recursive: bool = SchemaField(
+            description="Whether to recursively list the entire tree",
+            default=True,
+        )
+
+    class Output(BlockSchemaOutput):
+        class TreeEntry(TypedDict):
+            path: str
+            type: str
+            size: int
+            sha: str
+
+        entry: TreeEntry = SchemaField(
+            title="Tree Entry", description="A file or directory in the tree"
+        )
+        entries: list[TreeEntry] = SchemaField(
+            description="List of all files and directories in the tree"
+        )
+        truncated: bool = SchemaField(
+            description="Whether the tree was truncated due to size"
+        )
+        error: str = SchemaField(description="Error message if getting tree failed")
+
+    def __init__(self):
+        super().__init__(
+            id="89c5c0ec-172e-4001-a32c-bdfe4d0c9e81",
+            description="This block lists the entire file tree of a GitHub repository recursively.",
+            categories={BlockCategory.DEVELOPER_TOOLS},
+            input_schema=GithubGetRepositoryTreeBlock.Input,
+            output_schema=GithubGetRepositoryTreeBlock.Output,
+            test_input={
+                "repo_url": "https://github.com/owner/repo",
+                "branch": "main",
+                "recursive": True,
+                "credentials": TEST_CREDENTIALS_INPUT,
+            },
+            test_credentials=TEST_CREDENTIALS,
+            test_output=[
+                ("truncated", False),
+                (
+                    "entries",
+                    [
+                        {
+                            "path": "src/main.py",
+                            "type": "blob",
+                            "size": 1234,
+                            "sha": "abc123",
+                        }
+                    ],
+                ),
+                (
+                    "entry",
+                    {
+                        "path": "src/main.py",
+                        "type": "blob",
+                        "size": 1234,
+                        "sha": "abc123",
+                    },
+                ),
+            ],
+            test_mock={
+                "get_tree": lambda *args, **kwargs: (
+                    False,
+                    [
+                        {
+                            "path": "src/main.py",
+                            "type": "blob",
+                            "size": 1234,
+                            "sha": "abc123",
+                        }
+                    ],
+                )
+            },
+        )
+
+    @staticmethod
+    async def get_tree(
+        credentials: GithubCredentials,
+        repo_url: str,
+        branch: str,
+        recursive: bool,
+    ) -> tuple[bool, list[Output.TreeEntry]]:
+        api = get_api(credentials)
+        tree_url = repo_url + f"/git/trees/{quote(branch, safe='')}"
+        params = {"recursive": "1"} if recursive else {}
+        response = await api.get(tree_url, params=params)
+        data = response.json()
+        entries: list[GithubGetRepositoryTreeBlock.Output.TreeEntry] = [
+            GithubGetRepositoryTreeBlock.Output.TreeEntry(
+                path=item["path"],
+                type=item["type"],
+                size=item.get("size", 0),
+                sha=item["sha"],
+            )
+            for item in data["tree"]
+        ]
+        return data.get("truncated", False), entries
+
+    async def run(
+        self,
+        input_data: Input,
+        *,
+        credentials: GithubCredentials,
+        **kwargs,
+    ) -> BlockOutput:
+        try:
+            truncated, entries = await self.get_tree(
+                credentials,
+                input_data.repo_url,
+                input_data.branch,
+                input_data.recursive,
+            )
+            yield "truncated", truncated
+            yield "entries", entries
+            for entry in entries:
+                yield "entry", entry
+        except Exception as e:
+            yield "error", str(e)

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

@@ -0,0 +1,120 @@
+import inspect
+
+import pytest
+
+from backend.blocks.github._auth import TEST_CREDENTIALS, TEST_CREDENTIALS_INPUT
+from backend.blocks.github.commits import FileOperation, GithubMultiFileCommitBlock
+from backend.blocks.github.pull_requests import (
+    GithubMergePullRequestBlock,
+    prepare_pr_api_url,
+)
+from backend.util.exceptions import BlockExecutionError
+
+# ── prepare_pr_api_url tests ──
+
+
+class TestPreparePrApiUrl:
+    def test_https_scheme_preserved(self):
+        result = prepare_pr_api_url("https://github.com/owner/repo/pull/42", "merge")
+        assert result == "https://github.com/owner/repo/pulls/42/merge"
+
+    def test_http_scheme_preserved(self):
+        result = prepare_pr_api_url("http://github.com/owner/repo/pull/1", "files")
+        assert result == "http://github.com/owner/repo/pulls/1/files"
+
+    def test_no_scheme_defaults_to_https(self):
+        result = prepare_pr_api_url("github.com/owner/repo/pull/5", "merge")
+        assert result == "https://github.com/owner/repo/pulls/5/merge"
+
+    def test_reviewers_path(self):
+        result = prepare_pr_api_url(
+            "https://github.com/owner/repo/pull/99", "requested_reviewers"
+        )
+        assert result == "https://github.com/owner/repo/pulls/99/requested_reviewers"
+
+    def test_invalid_url_returned_as_is(self):
+        url = "https://example.com/not-a-pr"
+        assert prepare_pr_api_url(url, "merge") == url
+
+    def test_empty_string(self):
+        assert prepare_pr_api_url("", "merge") == ""
+
+
+# ── Error-path block tests ──
+# When a block's run() yields ("error", msg), _execute() converts it to a
+# BlockExecutionError. We call block.execute() directly (not execute_block_test,
+# which returns early on empty test_output).
+
+
+def _mock_block(block, mocks: dict):
+    """Apply mocks to a block's static methods, wrapping sync mocks as async."""
+    for name, mock_fn in mocks.items():
+        original = getattr(block, name)
+        if inspect.iscoroutinefunction(original):
+
+            async def async_mock(*args, _fn=mock_fn, **kwargs):
+                return _fn(*args, **kwargs)
+
+            setattr(block, name, async_mock)
+        else:
+            setattr(block, name, mock_fn)
+
+
+def _raise(exc: Exception):
+    """Helper that returns a callable which raises the given exception."""
+
+    def _raiser(*args, **kwargs):
+        raise exc
+
+    return _raiser
+
+
+@pytest.mark.asyncio
+async def test_merge_pr_error_path():
+    block = GithubMergePullRequestBlock()
+    _mock_block(block, {"merge_pr": _raise(RuntimeError("PR not mergeable"))})
+    input_data = {
+        "pr_url": "https://github.com/owner/repo/pull/1",
+        "merge_method": "squash",
+        "commit_title": "",
+        "commit_message": "",
+        "credentials": TEST_CREDENTIALS_INPUT,
+    }
+    with pytest.raises(BlockExecutionError, match="PR not mergeable"):
+        async for _ in block.execute(input_data, credentials=TEST_CREDENTIALS):
+            pass
+
+
+@pytest.mark.asyncio
+async def test_multi_file_commit_error_path():
+    block = GithubMultiFileCommitBlock()
+    _mock_block(block, {"multi_file_commit": _raise(RuntimeError("ref update failed"))})
+    input_data = {
+        "repo_url": "https://github.com/owner/repo",
+        "branch": "feature",
+        "commit_message": "test",
+        "files": [{"path": "a.py", "content": "x", "operation": "upsert"}],
+        "credentials": TEST_CREDENTIALS_INPUT,
+    }
+    with pytest.raises(BlockExecutionError, match="ref update failed"):
+        async for _ in block.execute(input_data, credentials=TEST_CREDENTIALS):
+            pass
+
+
+# ── FileOperation enum tests ──
+
+
+class TestFileOperation:
+    def test_upsert_value(self):
+        assert FileOperation.UPSERT == "upsert"
+
+    def test_delete_value(self):
+        assert FileOperation.DELETE == "delete"
+
+    def test_invalid_value_raises(self):
+        with pytest.raises(ValueError):
+            FileOperation("create")
+
+    def test_invalid_value_raises_typo(self):
+        with pytest.raises(ValueError):
+            FileOperation("upser")

autogpt_platform/backend/backend/blocks/google/gmail.py

@@ -241,8 +241,8 @@ class GmailBase(Block, ABC):
                     h.ignore_links = False
                     h.ignore_images = True
                     return h.handle(html_content)
-                except ImportError:
-                    # Fallback: return raw HTML if html2text is not available
+                except Exception:
+                    # Keep extraction resilient if html2text is unavailable or fails.
                     return html_content
 
         # Handle content stored as attachment

autogpt_platform/backend/backend/blocks/helpers/review.py

@@ -67,6 +67,7 @@ class HITLReviewHelper:
         graph_version: int,
         block_name: str = "Block",
         editable: bool = False,
+        is_graph_execution: bool = True,
     ) -> Optional[ReviewResult]:
         """
         Handle a review request for a block that requires human review.
@@ -143,10 +144,11 @@ class HITLReviewHelper:
             logger.info(
                 f"Block {block_name} pausing execution for node {node_exec_id} - awaiting human review"
             )
-            await HITLReviewHelper.update_node_execution_status(
-                exec_id=node_exec_id,
-                status=ExecutionStatus.REVIEW,
-            )
+            if is_graph_execution:
+                await HITLReviewHelper.update_node_execution_status(
+                    exec_id=node_exec_id,
+                    status=ExecutionStatus.REVIEW,
+                )
             return None  # Signal that execution should pause
 
         # Mark review as processed if not already done
@@ -168,6 +170,7 @@ class HITLReviewHelper:
         graph_version: int,
         block_name: str = "Block",
         editable: bool = False,
+        is_graph_execution: bool = True,
     ) -> Optional[ReviewDecision]:
         """
         Handle a review request and return the decision in a single call.
@@ -197,6 +200,7 @@ class HITLReviewHelper:
             graph_version=graph_version,
             block_name=block_name,
             editable=editable,
+            is_graph_execution=is_graph_execution,
         )
 
         if review_result is None:

autogpt_platform/backend/backend/blocks/jina/search.py

@@ -17,7 +17,7 @@ from backend.blocks.jina._auth import (
 from backend.blocks.search import GetRequest
 from backend.data.model import SchemaField
 from backend.util.exceptions import BlockExecutionError
-from backend.util.request import HTTPClientError, HTTPServerError, validate_url
+from backend.util.request import HTTPClientError, HTTPServerError, validate_url_host
 
 
 class SearchTheWebBlock(Block, GetRequest):
@@ -112,7 +112,7 @@ class ExtractWebsiteContentBlock(Block, GetRequest):
     ) -> BlockOutput:
         if input_data.raw_content:
             try:
-                parsed_url, _, _ = await validate_url(input_data.url, [])
+                parsed_url, _, _ = await validate_url_host(input_data.url)
                 url = parsed_url.geturl()
             except ValueError as e:
                 yield "error", f"Invalid URL: {e}"

autogpt_platform/backend/backend/blocks/llm.py

@@ -31,10 +31,14 @@ from backend.data.model import (
 )
 from backend.integrations.providers import ProviderName
 from backend.util import json
+from backend.util.clients import OPENROUTER_BASE_URL
 from backend.util.logging import TruncatedLogger
 from backend.util.prompt import compress_context, estimate_token_count
+from backend.util.request import validate_url_host
+from backend.util.settings import Settings
 from backend.util.text import TextFormatter
 
+settings = Settings()
 logger = TruncatedLogger(logging.getLogger(__name__), "[LLM-Block]")
 fmt = TextFormatter(autoescape=False)
 
@@ -136,13 +140,20 @@ class LlmModel(str, Enum, metaclass=LlmModelMeta):
     # OpenRouter models
     OPENAI_GPT_OSS_120B = "openai/gpt-oss-120b"
     OPENAI_GPT_OSS_20B = "openai/gpt-oss-20b"
-    GEMINI_2_5_PRO = "google/gemini-2.5-pro-preview-03-25"
-    GEMINI_3_PRO_PREVIEW = "google/gemini-3-pro-preview"
+    GEMINI_2_5_PRO_PREVIEW = "google/gemini-2.5-pro-preview-03-25"
+    GEMINI_2_5_PRO = "google/gemini-2.5-pro"
+    GEMINI_3_1_PRO_PREVIEW = "google/gemini-3.1-pro-preview"
+    GEMINI_3_FLASH_PREVIEW = "google/gemini-3-flash-preview"
     GEMINI_2_5_FLASH = "google/gemini-2.5-flash"
     GEMINI_2_0_FLASH = "google/gemini-2.0-flash-001"
+    GEMINI_3_1_FLASH_LITE_PREVIEW = "google/gemini-3.1-flash-lite-preview"
     GEMINI_2_5_FLASH_LITE_PREVIEW = "google/gemini-2.5-flash-lite-preview-06-17"
     GEMINI_2_0_FLASH_LITE = "google/gemini-2.0-flash-lite-001"
     MISTRAL_NEMO = "mistralai/mistral-nemo"
+    MISTRAL_LARGE_3 = "mistralai/mistral-large-2512"
+    MISTRAL_MEDIUM_3_1 = "mistralai/mistral-medium-3.1"
+    MISTRAL_SMALL_3_2 = "mistralai/mistral-small-3.2-24b-instruct"
+    CODESTRAL = "mistralai/codestral-2508"
     COHERE_COMMAND_R_08_2024 = "cohere/command-r-08-2024"
     COHERE_COMMAND_R_PLUS_08_2024 = "cohere/command-r-plus-08-2024"
     DEEPSEEK_CHAT = "deepseek/deepseek-chat"  # Actually: DeepSeek V3
@@ -336,17 +347,41 @@ MODEL_METADATA = {
         "ollama", 32768, None, "Dolphin Mistral Latest", "Ollama", "Mistral AI", 1
     ),
     # https://openrouter.ai/models
-    LlmModel.GEMINI_2_5_PRO: ModelMetadata(
+    LlmModel.GEMINI_2_5_PRO_PREVIEW: ModelMetadata(
         "open_router",
-        1050000,
-        8192,
+        1048576,
+        65536,
         "Gemini 2.5 Pro Preview 03.25",
         "OpenRouter",
         "Google",
         2,
     ),
-    LlmModel.GEMINI_3_PRO_PREVIEW: ModelMetadata(
-        "open_router", 1048576, 65535, "Gemini 3 Pro Preview", "OpenRouter", "Google", 2
+    LlmModel.GEMINI_2_5_PRO: ModelMetadata(
+        "open_router",
+        1048576,
+        65536,
+        "Gemini 2.5 Pro",
+        "OpenRouter",
+        "Google",
+        2,
+    ),
+    LlmModel.GEMINI_3_1_PRO_PREVIEW: ModelMetadata(
+        "open_router",
+        1048576,
+        65536,
+        "Gemini 3.1 Pro Preview",
+        "OpenRouter",
+        "Google",
+        2,
+    ),
+    LlmModel.GEMINI_3_FLASH_PREVIEW: ModelMetadata(
+        "open_router",
+        1048576,
+        65536,
+        "Gemini 3 Flash Preview",
+        "OpenRouter",
+        "Google",
+        1,
     ),
     LlmModel.GEMINI_2_5_FLASH: ModelMetadata(
         "open_router", 1048576, 65535, "Gemini 2.5 Flash", "OpenRouter", "Google", 1
@@ -354,6 +389,15 @@ MODEL_METADATA = {
     LlmModel.GEMINI_2_0_FLASH: ModelMetadata(
         "open_router", 1048576, 8192, "Gemini 2.0 Flash 001", "OpenRouter", "Google", 1
     ),
+    LlmModel.GEMINI_3_1_FLASH_LITE_PREVIEW: ModelMetadata(
+        "open_router",
+        1048576,
+        65536,
+        "Gemini 3.1 Flash Lite Preview",
+        "OpenRouter",
+        "Google",
+        1,
+    ),
     LlmModel.GEMINI_2_5_FLASH_LITE_PREVIEW: ModelMetadata(
         "open_router",
         1048576,
@@ -375,6 +419,42 @@ MODEL_METADATA = {
     LlmModel.MISTRAL_NEMO: ModelMetadata(
         "open_router", 128000, 4096, "Mistral Nemo", "OpenRouter", "Mistral AI", 1
     ),
+    LlmModel.MISTRAL_LARGE_3: ModelMetadata(
+        "open_router",
+        262144,
+        None,
+        "Mistral Large 3 2512",
+        "OpenRouter",
+        "Mistral AI",
+        2,
+    ),
+    LlmModel.MISTRAL_MEDIUM_3_1: ModelMetadata(
+        "open_router",
+        131072,
+        None,
+        "Mistral Medium 3.1",
+        "OpenRouter",
+        "Mistral AI",
+        2,
+    ),
+    LlmModel.MISTRAL_SMALL_3_2: ModelMetadata(
+        "open_router",
+        131072,
+        131072,
+        "Mistral Small 3.2 24B",
+        "OpenRouter",
+        "Mistral AI",
+        1,
+    ),
+    LlmModel.CODESTRAL: ModelMetadata(
+        "open_router",
+        256000,
+        None,
+        "Codestral 2508",
+        "OpenRouter",
+        "Mistral AI",
+        1,
+    ),
     LlmModel.COHERE_COMMAND_R_08_2024: ModelMetadata(
         "open_router", 128000, 4096, "Command R 08.2024", "OpenRouter", "Cohere", 1
     ),
@@ -804,6 +884,11 @@ async def llm_call(
         if tools:
             raise ValueError("Ollama does not support tools.")
 
+        # Validate user-provided Ollama host to prevent SSRF etc.
+        await validate_url_host(
+            ollama_host, trusted_hostnames=[settings.config.ollama_host]
+        )
+
         client = ollama.AsyncClient(host=ollama_host)
         sys_messages = [p["content"] for p in prompt if p["role"] == "system"]
         usr_messages = [p["content"] for p in prompt if p["role"] != "system"]
@@ -825,7 +910,7 @@ async def llm_call(
     elif provider == "open_router":
         tools_param = tools if tools else openai.NOT_GIVEN
         client = openai.AsyncOpenAI(
-            base_url="https://openrouter.ai/api/v1",
+            base_url=OPENROUTER_BASE_URL,
             api_key=credentials.api_key.get_secret_value(),
         )
 

autogpt_platform/backend/backend/blocks/mcp/test_helpers.py

@@ -43,7 +43,12 @@ def test_server_host_standard_url():
 
 def test_server_host_strips_credentials():
     """hostname must not expose user:pass."""
-    assert server_host("https://user:secret@mcp.example.com/mcp") == "mcp.example.com"
+    assert (
+        server_host(
+            "https://user:secret@mcp.example.com/mcp"  # pragma: allowlist secret
+        )
+        == "mcp.example.com"
+    )
 
 
 def test_server_host_with_port():

autogpt_platform/backend/backend/blocks/perplexity.py

@@ -21,6 +21,7 @@ from backend.data.model import (
     SchemaField,
 )
 from backend.integrations.providers import ProviderName
+from backend.util.clients import OPENROUTER_BASE_URL
 from backend.util.logging import TruncatedLogger
 
 logger = TruncatedLogger(logging.getLogger(__name__), "[Perplexity-Block]")
@@ -136,7 +137,7 @@ class PerplexityBlock(Block):
     ) -> dict[str, Any]:
         """Call Perplexity via OpenRouter and extract annotations."""
         client = openai.AsyncOpenAI(
-            base_url="https://openrouter.ai/api/v1",
+            base_url=OPENROUTER_BASE_URL,
             api_key=credentials.api_key.get_secret_value(),
         )
 

autogpt_platform/backend/backend/blocks/reddit.py

@@ -2232,6 +2232,7 @@ class DeleteRedditPostBlock(Block):
                 ("post_id", "abc123"),
             ],
             test_mock={"delete_post": lambda creds, post_id: True},
+            is_sensitive_action=True,
         )
 
     @staticmethod
@@ -2290,6 +2291,7 @@ class DeleteRedditCommentBlock(Block):
                 ("comment_id", "xyz789"),
             ],
             test_mock={"delete_comment": lambda creds, comment_id: True},
+            is_sensitive_action=True,
         )
 
     @staticmethod

autogpt_platform/backend/backend/blocks/slant3d/order.py

@@ -72,6 +72,7 @@ class Slant3DCreateOrderBlock(Slant3DBlockBase):
                 "_make_request": lambda *args, **kwargs: {"orderId": "314144241"},
                 "_convert_to_color": lambda *args, **kwargs: "black",
             },
+            is_sensitive_action=True,
         )
 
     async def run(

autogpt_platform/backend/backend/blocks/system/store_operations.py

@@ -1,8 +1,8 @@
 import logging
-from typing import Literal
 
 from pydantic import BaseModel
 
+from backend.api.features.store.db import StoreAgentsSortOptions
 from backend.blocks._base import (
     Block,
     BlockCategory,
@@ -176,8 +176,8 @@ class SearchStoreAgentsBlock(Block):
         category: str | None = SchemaField(
             description="Filter by category", default=None
         )
-        sort_by: Literal["rating", "runs", "name", "updated_at"] = SchemaField(
-            description="How to sort the results", default="rating"
+        sort_by: StoreAgentsSortOptions = SchemaField(
+            description="How to sort the results", default=StoreAgentsSortOptions.RATING
         )
         limit: int = SchemaField(
             description="Maximum number of results to return", default=10, ge=1, le=100
@@ -278,7 +278,7 @@ class SearchStoreAgentsBlock(Block):
         self,
         query: str | None = None,
         category: str | None = None,
-        sort_by: Literal["rating", "runs", "name", "updated_at"] = "rating",
+        sort_by: StoreAgentsSortOptions = StoreAgentsSortOptions.RATING,
         limit: int = 10,
     ) -> SearchAgentsResponse:
         """

autogpt_platform/backend/backend/blocks/test/test_store_operations.py

@@ -2,6 +2,7 @@ from unittest.mock import MagicMock
 
 import pytest
 
+from backend.api.features.store.db import StoreAgentsSortOptions
 from backend.blocks.system.library_operations import (
     AddToLibraryFromStoreBlock,
     LibraryAgent,
@@ -121,7 +122,10 @@ async def test_search_store_agents_block(mocker):
     )
 
     input_data = block.Input(
-        query="test", category="productivity", sort_by="rating", limit=10
+        query="test",
+        category="productivity",
+        sort_by=StoreAgentsSortOptions.RATING,  # type: ignore[reportArgumentType]
+        limit=10,
     )
 
     outputs = {}

autogpt_platform/backend/backend/check_db.py

@@ -160,7 +160,6 @@ async def add_test_data(db):
                 data={
                     "slug": f"test-agent-{graph.id[:8]}",
                     "agentGraphId": graph.id,
-                    "agentGraphVersion": graph.version,
                     "hasApprovedVersion": True,
                     "owningUserId": graph.userId,
                 }

autogpt_platform/backend/backend/cli/generate_openapi_json.py

@@ -6,9 +6,9 @@ This script imports the FastAPI app from backend.api.rest_api and outputs
 the OpenAPI specification as JSON to stdout or a specified file.
 
 Usage:
-  `poetry run python generate_openapi_json.py`
-  `poetry run python generate_openapi_json.py --output openapi.json`
-  `poetry run python generate_openapi_json.py --indent 4 --output openapi.json`
+  `poetry run export-api-schema`
+  `poetry run export-api-schema --output openapi.json`
+  `poetry run export-api-schema --api v2 --output openapi.json`
 """
 
 import json
@@ -17,8 +17,16 @@ from pathlib import Path
 
 import click
 
+API_CHOICES = ["internal", "v1", "v2"]
+
 
 @click.command()
+@click.option(
+    "--api",
+    type=click.Choice(API_CHOICES),
+    default="internal",
+    help="Which API schema to export (default: internal)",
+)
 @click.option(
     "--output",
     type=click.Path(dir_okay=False, path_type=Path),
@@ -26,13 +34,12 @@ import click
 )
 @click.option(
     "--pretty",
-    type=click.BOOL,
-    default=False,
+    is_flag=True,
     help="Pretty-print JSON output (indented 2 spaces)",
 )
-def main(output: Path, pretty: bool):
+def main(api: str, output: Path, pretty: bool):
     """Generate and output the OpenAPI JSON specification."""
-    openapi_schema = get_openapi_schema()
+    openapi_schema = get_openapi_schema(api)
 
     json_output = json.dumps(
         openapi_schema, indent=2 if pretty else None, ensure_ascii=False
@@ -46,11 +53,22 @@ def main(output: Path, pretty: bool):
         print(json_output)
 
 
-def get_openapi_schema():
-    """Get the OpenAPI schema from the FastAPI app"""
-    from backend.api.rest_api import app
+def get_openapi_schema(api: str = "internal"):
+    """Get the OpenAPI schema from the specified FastAPI app."""
+    if api == "internal":
+        from backend.api.rest_api import app
 
-    return app.openapi()
+        return app.openapi()
+    elif api == "v1":
+        from backend.api.external.v1.app import v1_app
+
+        return v1_app.openapi()
+    elif api == "v2":
+        from backend.api.external.v2.app import v2_app
+
+        return v2_app.openapi()
+    else:
+        raise click.BadParameter(f"Unknown API: {api}. Choose from {API_CHOICES}")
 
 
 if __name__ == "__main__":

autogpt_platform/backend/backend/copilot/baseline/service.py

@@ -22,6 +22,7 @@ from backend.copilot.model import (
     update_session_title,
     upsert_chat_session,
 )
+from backend.copilot.prompting import get_baseline_supplement
 from backend.copilot.response_model import (
     StreamBaseResponse,
     StreamError,
@@ -176,14 +177,17 @@ async def stream_chat_completion_baseline(
     # changes from concurrent chats updating business understanding.
     is_first_turn = len(session.messages) <= 1
     if is_first_turn:
-        system_prompt, _ = await _build_system_prompt(
+        base_system_prompt, _ = await _build_system_prompt(
             user_id, has_conversation_history=False
         )
     else:
-        system_prompt, _ = await _build_system_prompt(
+        base_system_prompt, _ = await _build_system_prompt(
             user_id=None, has_conversation_history=True
         )
 
+    # Append tool documentation and technical notes
+    system_prompt = base_system_prompt + get_baseline_supplement()
+
     # Compress context if approaching the model's token limit
     messages_for_context = await _compress_session_messages(session.messages)
 

autogpt_platform/backend/backend/copilot/config.py

@@ -1,10 +1,13 @@
 """Configuration management for chat system."""
 
 import os
+from typing import Literal
 
 from pydantic import Field, field_validator
 from pydantic_settings import BaseSettings
 
+from backend.util.clients import OPENROUTER_BASE_URL
+
 
 class ChatConfig(BaseSettings):
     """Configuration for the chat system."""
@@ -19,7 +22,7 @@ class ChatConfig(BaseSettings):
     )
     api_key: str | None = Field(default=None, description="OpenAI API key")
     base_url: str | None = Field(
-        default="https://openrouter.ai/api/v1",
+        default=OPENROUTER_BASE_URL,
         description="Base URL for API (e.g., for OpenRouter)",
     )
 
@@ -112,9 +115,37 @@ class ChatConfig(BaseSettings):
         description="E2B sandbox template to use for copilot sessions.",
     )
     e2b_sandbox_timeout: int = Field(
-        default=43200,  # 12 hours — same as session_ttl
-        description="E2B sandbox keepalive timeout in seconds.",
+        default=10800,  # 3 hours — wall-clock timeout, not idle; explicit pause is primary
+        description="E2B sandbox running-time timeout (seconds). "
+        "E2B timeout is wall-clock (not idle). Explicit per-turn pause is the primary "
+        "mechanism; this is the safety net.",
     )
+    e2b_sandbox_on_timeout: Literal["kill", "pause"] = Field(
+        default="pause",
+        description="E2B lifecycle action on timeout: 'pause' (default, free) or 'kill'.",
+    )
+
+    @property
+    def e2b_active(self) -> bool:
+        """True when E2B is enabled and the API key is present.
+
+        Single source of truth for "should we use E2B right now?".
+        Prefer this over combining ``use_e2b_sandbox`` and ``e2b_api_key``
+        separately at call sites.
+        """
+        return self.use_e2b_sandbox and bool(self.e2b_api_key)
+
+    @property
+    def active_e2b_api_key(self) -> str | None:
+        """Return the E2B API key when E2B is enabled and configured, else None.
+
+        Combines the ``use_e2b_sandbox`` flag check and key presence into one.
+        Use in callers::
+
+            if api_key := config.active_e2b_api_key:
+                # E2B is active; api_key is narrowed to str
+        """
+        return self.e2b_api_key if self.e2b_active else None
 
     @field_validator("use_e2b_sandbox", mode="before")
     @classmethod
@@ -164,7 +195,7 @@ class ChatConfig(BaseSettings):
             if not v:
                 v = os.getenv("OPENAI_BASE_URL")
             if not v:
-                v = "https://openrouter.ai/api/v1"
+                v = OPENROUTER_BASE_URL
         return v
 
     @field_validator("use_claude_agent_sdk", mode="before")

autogpt_platform/backend/backend/copilot/config_test.py

@@ -0,0 +1,38 @@
+"""Unit tests for ChatConfig."""
+
+import pytest
+
+from .config import ChatConfig
+
+# Env vars that the ChatConfig validators read — must be cleared so they don't
+# override the explicit constructor values we pass in each test.
+_E2B_ENV_VARS = (
+    "CHAT_USE_E2B_SANDBOX",
+    "CHAT_E2B_API_KEY",
+    "E2B_API_KEY",
+)
+
+
+@pytest.fixture(autouse=True)
+def _clean_e2b_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    for var in _E2B_ENV_VARS:
+        monkeypatch.delenv(var, raising=False)
+
+
+class TestE2BActive:
+    """Tests for the e2b_active property — single source of truth for E2B usage."""
+
+    def test_both_enabled_and_key_present_returns_true(self):
+        """e2b_active is True when use_e2b_sandbox=True and e2b_api_key is set."""
+        cfg = ChatConfig(use_e2b_sandbox=True, e2b_api_key="test-key")
+        assert cfg.e2b_active is True
+
+    def test_enabled_but_missing_key_returns_false(self):
+        """e2b_active is False when use_e2b_sandbox=True but e2b_api_key is absent."""
+        cfg = ChatConfig(use_e2b_sandbox=True, e2b_api_key=None)
+        assert cfg.e2b_active is False
+
+    def test_disabled_returns_false(self):
+        """e2b_active is False when use_e2b_sandbox=False regardless of key."""
+        cfg = ChatConfig(use_e2b_sandbox=False, e2b_api_key="test-key")
+        assert cfg.e2b_active is False

autogpt_platform/backend/backend/copilot/constants.py

@@ -6,6 +6,32 @@
 COPILOT_ERROR_PREFIX = "[__COPILOT_ERROR_f7a1__]"  # Renders as ErrorCard
 COPILOT_SYSTEM_PREFIX = "[__COPILOT_SYSTEM_e3b0__]"  # Renders as system info message
 
+# Prefix for all synthetic IDs generated by CoPilot block execution.
+# Used to distinguish CoPilot-generated records from real graph execution records
+# in PendingHumanReview and other tables.
+COPILOT_SYNTHETIC_ID_PREFIX = "copilot-"
+
+# Sub-prefixes for session-scoped and node-scoped synthetic IDs.
+COPILOT_SESSION_PREFIX = f"{COPILOT_SYNTHETIC_ID_PREFIX}session-"
+COPILOT_NODE_PREFIX = f"{COPILOT_SYNTHETIC_ID_PREFIX}node-"
+
+# Separator used in synthetic node_exec_id to encode node_id.
+# Format: "{node_id}:{random_hex}" — extract node_id via rsplit(":", 1)[0]
+COPILOT_NODE_EXEC_ID_SEPARATOR = ":"
+
 # Compaction notice messages shown to users.
 COMPACTION_DONE_MSG = "Earlier messages were summarized to fit within context limits."
 COMPACTION_TOOL_NAME = "context_compaction"
+
+
+def is_copilot_synthetic_id(id_value: str) -> bool:
+    """Check if an ID is a CoPilot synthetic ID (not from a real graph execution)."""
+    return id_value.startswith(COPILOT_SYNTHETIC_ID_PREFIX)
+
+
+def parse_node_id_from_exec_id(node_exec_id: str) -> str:
+    """Extract node_id from a synthetic node_exec_id.
+
+    Format: "{node_id}:{random_hex}" → returns "{node_id}".
+    """
+    return node_exec_id.rsplit(COPILOT_NODE_EXEC_ID_SEPARATOR, 1)[0]

autogpt_platform/backend/backend/copilot/context.py

@@ -0,0 +1,115 @@
+"""Shared execution context for copilot SDK tool handlers.
+
+All context variables and their accessors live here so that
+``tool_adapter``, ``file_ref``, and ``e2b_file_tools`` can import them
+without creating circular dependencies.
+"""
+
+import os
+import re
+from contextvars import ContextVar
+from typing import TYPE_CHECKING
+
+from backend.copilot.model import ChatSession
+
+if TYPE_CHECKING:
+    from e2b import AsyncSandbox
+
+# Allowed base directory for the Read tool.
+_SDK_PROJECTS_DIR = os.path.realpath(os.path.expanduser("~/.claude/projects"))
+
+# Encoded project-directory name for the current session (e.g.
+# "-private-tmp-copilot-<uuid>").  Set by set_execution_context() so path
+# validation can scope tool-results reads to the current session.
+_current_project_dir: ContextVar[str] = ContextVar("_current_project_dir", default="")
+
+_current_user_id: ContextVar[str | None] = ContextVar("current_user_id", default=None)
+_current_session: ContextVar[ChatSession | None] = ContextVar(
+    "current_session", default=None
+)
+_current_sandbox: ContextVar["AsyncSandbox | None"] = ContextVar(
+    "_current_sandbox", default=None
+)
+_current_sdk_cwd: ContextVar[str] = ContextVar("_current_sdk_cwd", default="")
+
+
+def _encode_cwd_for_cli(cwd: str) -> str:
+    """Encode a working directory path the same way the Claude CLI does."""
+    return re.sub(r"[^a-zA-Z0-9]", "-", os.path.realpath(cwd))
+
+
+def set_execution_context(
+    user_id: str | None,
+    session: ChatSession,
+    sandbox: "AsyncSandbox | None" = None,
+    sdk_cwd: str | None = None,
+) -> None:
+    """Set per-turn context variables used by file-resolution tool handlers."""
+    _current_user_id.set(user_id)
+    _current_session.set(session)
+    _current_sandbox.set(sandbox)
+    _current_sdk_cwd.set(sdk_cwd or "")
+    _current_project_dir.set(_encode_cwd_for_cli(sdk_cwd) if sdk_cwd else "")
+
+
+def get_execution_context() -> tuple[str | None, ChatSession | None]:
+    """Return the current (user_id, session) pair for the active request."""
+    return _current_user_id.get(), _current_session.get()
+
+
+def get_current_sandbox() -> "AsyncSandbox | None":
+    """Return the E2B sandbox for the current session, or None if not active."""
+    return _current_sandbox.get()
+
+
+def get_sdk_cwd() -> str:
+    """Return the SDK working directory for the current session (empty string if unset)."""
+    return _current_sdk_cwd.get()
+
+
+E2B_WORKDIR = "/home/user"
+
+
+def resolve_sandbox_path(path: str) -> str:
+    """Normalise *path* to an absolute sandbox path under ``/home/user``.
+
+    Raises :class:`ValueError` if the resolved path escapes the sandbox.
+    """
+    candidate = path if os.path.isabs(path) else os.path.join(E2B_WORKDIR, path)
+    normalized = os.path.normpath(candidate)
+    if normalized != E2B_WORKDIR and not normalized.startswith(E2B_WORKDIR + "/"):
+        raise ValueError(f"Path must be within {E2B_WORKDIR}: {path}")
+    return normalized
+
+
+def is_allowed_local_path(path: str, sdk_cwd: str | None = None) -> bool:
+    """Return True if *path* is within an allowed host-filesystem location.
+
+    Allowed:
+    - Files under *sdk_cwd* (``/tmp/copilot-<session>/``)
+    - Files under ``~/.claude/projects/<encoded-cwd>/tool-results/`` (SDK tool-results)
+    """
+    if not path:
+        return False
+
+    if path.startswith("~"):
+        resolved = os.path.realpath(os.path.expanduser(path))
+    elif not os.path.isabs(path) and sdk_cwd:
+        resolved = os.path.realpath(os.path.join(sdk_cwd, path))
+    else:
+        resolved = os.path.realpath(path)
+
+    if sdk_cwd:
+        norm_cwd = os.path.realpath(sdk_cwd)
+        if resolved == norm_cwd or resolved.startswith(norm_cwd + os.sep):
+            return True
+
+    encoded = _current_project_dir.get("")
+    if encoded:
+        tool_results_dir = os.path.join(_SDK_PROJECTS_DIR, encoded, "tool-results")
+        if resolved == tool_results_dir or resolved.startswith(
+            tool_results_dir + os.sep
+        ):
+            return True
+
+    return False

autogpt_platform/backend/backend/copilot/context_test.py

@@ -0,0 +1,163 @@
+"""Tests for context.py — execution context variables and path helpers."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from unittest.mock import MagicMock
+
+import pytest
+
+from backend.copilot.context import (
+    _SDK_PROJECTS_DIR,
+    _current_project_dir,
+    get_current_sandbox,
+    get_execution_context,
+    get_sdk_cwd,
+    is_allowed_local_path,
+    resolve_sandbox_path,
+    set_execution_context,
+)
+
+
+def _make_session() -> MagicMock:
+    s = MagicMock()
+    s.session_id = "test-session"
+    return s
+
+
+# ---------------------------------------------------------------------------
+# Context variable getters
+# ---------------------------------------------------------------------------
+
+
+def test_get_execution_context_defaults():
+    """get_execution_context returns (None, session) when user_id is not set."""
+    set_execution_context(None, _make_session())
+    user_id, session = get_execution_context()
+    assert user_id is None
+    assert session is not None
+
+
+def test_set_and_get_execution_context():
+    """set_execution_context stores user_id and session."""
+    mock_session = _make_session()
+    set_execution_context("user-abc", mock_session)
+    user_id, session = get_execution_context()
+    assert user_id == "user-abc"
+    assert session is mock_session
+
+
+def test_get_current_sandbox_none_by_default():
+    """get_current_sandbox returns None when no sandbox is set."""
+    set_execution_context("u1", _make_session(), sandbox=None)
+    assert get_current_sandbox() is None
+
+
+def test_get_current_sandbox_returns_set_value():
+    """get_current_sandbox returns the sandbox set via set_execution_context."""
+    mock_sandbox = MagicMock()
+    set_execution_context("u1", _make_session(), sandbox=mock_sandbox)
+    assert get_current_sandbox() is mock_sandbox
+
+
+def test_get_sdk_cwd_empty_when_not_set():
+    """get_sdk_cwd returns empty string when sdk_cwd is not set."""
+    set_execution_context("u1", _make_session(), sdk_cwd=None)
+    assert get_sdk_cwd() == ""
+
+
+def test_get_sdk_cwd_returns_set_value():
+    """get_sdk_cwd returns the value set via set_execution_context."""
+    set_execution_context("u1", _make_session(), sdk_cwd="/tmp/copilot-test")
+    assert get_sdk_cwd() == "/tmp/copilot-test"
+
+
+# ---------------------------------------------------------------------------
+# is_allowed_local_path
+# ---------------------------------------------------------------------------
+
+
+def test_is_allowed_local_path_empty():
+    assert not is_allowed_local_path("")
+
+
+def test_is_allowed_local_path_inside_sdk_cwd():
+    with tempfile.TemporaryDirectory() as cwd:
+        path = os.path.join(cwd, "file.txt")
+        assert is_allowed_local_path(path, cwd)
+
+
+def test_is_allowed_local_path_sdk_cwd_itself():
+    with tempfile.TemporaryDirectory() as cwd:
+        assert is_allowed_local_path(cwd, cwd)
+
+
+def test_is_allowed_local_path_outside_sdk_cwd():
+    with tempfile.TemporaryDirectory() as cwd:
+        assert not is_allowed_local_path("/etc/passwd", cwd)
+
+
+def test_is_allowed_local_path_no_sdk_cwd_no_project_dir():
+    """Without sdk_cwd or project_dir, all paths are rejected."""
+    _current_project_dir.set("")
+    assert not is_allowed_local_path("/tmp/some-file.txt", sdk_cwd=None)
+
+
+def test_is_allowed_local_path_tool_results_dir():
+    """Files under the tool-results directory for the current project are allowed."""
+    encoded = "test-encoded-dir"
+    tool_results_dir = os.path.join(_SDK_PROJECTS_DIR, encoded, "tool-results")
+    path = os.path.join(tool_results_dir, "output.txt")
+
+    _current_project_dir.set(encoded)
+    try:
+        assert is_allowed_local_path(path, sdk_cwd=None)
+    finally:
+        _current_project_dir.set("")
+
+
+def test_is_allowed_local_path_sibling_of_tool_results_is_rejected():
+    """A path adjacent to tool-results/ but not inside it is rejected."""
+    encoded = "test-encoded-dir"
+    sibling_path = os.path.join(_SDK_PROJECTS_DIR, encoded, "other-dir", "file.txt")
+
+    _current_project_dir.set(encoded)
+    try:
+        assert not is_allowed_local_path(sibling_path, sdk_cwd=None)
+    finally:
+        _current_project_dir.set("")
+
+
+# ---------------------------------------------------------------------------
+# resolve_sandbox_path
+# ---------------------------------------------------------------------------
+
+
+def test_resolve_sandbox_path_absolute_valid():
+    assert (
+        resolve_sandbox_path("/home/user/project/main.py")
+        == "/home/user/project/main.py"
+    )
+
+
+def test_resolve_sandbox_path_relative():
+    assert resolve_sandbox_path("project/main.py") == "/home/user/project/main.py"
+
+
+def test_resolve_sandbox_path_workdir_itself():
+    assert resolve_sandbox_path("/home/user") == "/home/user"
+
+
+def test_resolve_sandbox_path_normalizes_dots():
+    assert resolve_sandbox_path("/home/user/a/../b") == "/home/user/b"
+
+
+def test_resolve_sandbox_path_escape_raises():
+    with pytest.raises(ValueError, match="/home/user"):
+        resolve_sandbox_path("/home/user/../../etc/passwd")
+
+
+def test_resolve_sandbox_path_absolute_outside_raises():
+    with pytest.raises(ValueError, match="/home/user"):
+        resolve_sandbox_path("/etc/passwd")

autogpt_platform/backend/backend/copilot/optimize_blocks.py

@@ -0,0 +1,138 @@
+"""Scheduler job to generate LLM-optimized block descriptions.
+
+Runs periodically to rewrite block descriptions into concise, actionable
+summaries that help the copilot LLM pick the right blocks during agent
+generation.
+"""
+
+import asyncio
+import logging
+
+from backend.blocks import get_blocks
+from backend.util.clients import get_database_manager_client, get_openai_client
+
+logger = logging.getLogger(__name__)
+
+SYSTEM_PROMPT = (
+    "You are a technical writer for an automation platform. "
+    "Rewrite the following block description to be concise (under 50 words), "
+    "informative, and actionable. Focus on what the block does and when to "
+    "use it. Output ONLY the rewritten description, nothing else. "
+    "Do not use markdown formatting."
+)
+
+# Rate-limit delay between sequential LLM calls (seconds)
+_RATE_LIMIT_DELAY = 0.5
+# Maximum tokens for optimized description generation
+_MAX_DESCRIPTION_TOKENS = 150
+# Model for generating optimized descriptions (fast, cheap)
+_MODEL = "gpt-4o-mini"
+
+
+async def _optimize_descriptions(blocks: list[dict[str, str]]) -> dict[str, str]:
+    """Call the shared OpenAI client to rewrite each block description."""
+    client = get_openai_client()
+    if client is None:
+        logger.error(
+            "No OpenAI client configured, skipping block description optimization"
+        )
+        return {}
+
+    results: dict[str, str] = {}
+    for block in blocks:
+        block_id = block["id"]
+        block_name = block["name"]
+        description = block["description"]
+
+        try:
+            response = await client.chat.completions.create(
+                model=_MODEL,
+                messages=[
+                    {"role": "system", "content": SYSTEM_PROMPT},
+                    {
+                        "role": "user",
+                        "content": f"Block name: {block_name}\nDescription: {description}",
+                    },
+                ],
+                max_tokens=_MAX_DESCRIPTION_TOKENS,
+            )
+            optimized = (response.choices[0].message.content or "").strip()
+            if optimized:
+                results[block_id] = optimized
+                logger.debug("Optimized description for %s", block_name)
+            else:
+                logger.warning("Empty response for block %s", block_name)
+        except Exception:
+            logger.warning(
+                "Failed to optimize description for %s", block_name, exc_info=True
+            )
+
+        await asyncio.sleep(_RATE_LIMIT_DELAY)
+
+    return results
+
+
+def optimize_block_descriptions() -> dict[str, int]:
+    """Generate optimized descriptions for blocks that don't have one yet.
+
+    Uses the shared OpenAI client to rewrite block descriptions into concise
+    summaries suitable for agent generation prompts.
+
+    Returns:
+        Dict with counts: processed, success, failed, skipped.
+    """
+    db_client = get_database_manager_client()
+
+    blocks = db_client.get_blocks_needing_optimization()
+    if not blocks:
+        logger.info("All blocks already have optimized descriptions")
+        return {"processed": 0, "success": 0, "failed": 0, "skipped": 0}
+
+    logger.info("Found %d blocks needing optimized descriptions", len(blocks))
+
+    non_empty = [b for b in blocks if b.get("description", "").strip()]
+    skipped = len(blocks) - len(non_empty)
+
+    new_descriptions = asyncio.run(_optimize_descriptions(non_empty))
+
+    stats = {
+        "processed": len(non_empty),
+        "success": len(new_descriptions),
+        "failed": len(non_empty) - len(new_descriptions),
+        "skipped": skipped,
+    }
+
+    logger.info(
+        "Block description optimization complete: "
+        "%d/%d succeeded, %d failed, %d skipped",
+        stats["success"],
+        stats["processed"],
+        stats["failed"],
+        stats["skipped"],
+    )
+
+    if new_descriptions:
+        for block_id, optimized in new_descriptions.items():
+            db_client.update_block_optimized_description(block_id, optimized)
+
+        # Update in-memory descriptions first so the cache rebuilds with fresh data.
+        try:
+            block_classes = get_blocks()
+            for block_id, optimized in new_descriptions.items():
+                if block_id in block_classes:
+                    block_classes[block_id]._optimized_description = optimized
+            logger.info(
+                "Updated %d in-memory block descriptions", len(new_descriptions)
+            )
+        except Exception:
+            logger.warning(
+                "Could not update in-memory block descriptions", exc_info=True
+            )
+
+        from backend.copilot.tools.agent_generator.blocks import (
+            reset_block_caches,  # local to avoid circular import
+        )
+
+        reset_block_caches()
+
+    return stats

autogpt_platform/backend/backend/copilot/optimize_blocks_test.py

@@ -0,0 +1,91 @@
+"""Unit tests for optimize_blocks._optimize_descriptions."""
+
+import asyncio
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from backend.copilot.optimize_blocks import _RATE_LIMIT_DELAY, _optimize_descriptions
+
+
+def _make_client_response(text: str) -> MagicMock:
+    """Build a minimal mock that looks like an OpenAI ChatCompletion response."""
+    choice = MagicMock()
+    choice.message.content = text
+    response = MagicMock()
+    response.choices = [choice]
+    return response
+
+
+def _run(coro):
+    return asyncio.get_event_loop().run_until_complete(coro)
+
+
+class TestOptimizeDescriptions:
+    """Tests for _optimize_descriptions async function."""
+
+    def test_returns_empty_when_no_client(self):
+        with patch(
+            "backend.copilot.optimize_blocks.get_openai_client", return_value=None
+        ):
+            result = _run(
+                _optimize_descriptions([{"id": "b1", "name": "B", "description": "d"}])
+            )
+        assert result == {}
+
+    def test_success_single_block(self):
+        client = MagicMock()
+        client.chat.completions.create = AsyncMock(
+            return_value=_make_client_response("Short desc.")
+        )
+        blocks = [{"id": "b1", "name": "MyBlock", "description": "A block."}]
+
+        with (
+            patch(
+                "backend.copilot.optimize_blocks.get_openai_client", return_value=client
+            ),
+            patch(
+                "backend.copilot.optimize_blocks.asyncio.sleep", new_callable=AsyncMock
+            ),
+        ):
+            result = _run(_optimize_descriptions(blocks))
+
+        assert result == {"b1": "Short desc."}
+        client.chat.completions.create.assert_called_once()
+
+    def test_skips_block_on_exception(self):
+        client = MagicMock()
+        client.chat.completions.create = AsyncMock(side_effect=Exception("API error"))
+        blocks = [{"id": "b1", "name": "MyBlock", "description": "A block."}]
+
+        with (
+            patch(
+                "backend.copilot.optimize_blocks.get_openai_client", return_value=client
+            ),
+            patch(
+                "backend.copilot.optimize_blocks.asyncio.sleep", new_callable=AsyncMock
+            ),
+        ):
+            result = _run(_optimize_descriptions(blocks))
+
+        assert result == {}
+
+    def test_sleeps_between_blocks(self):
+        client = MagicMock()
+        client.chat.completions.create = AsyncMock(
+            return_value=_make_client_response("desc")
+        )
+        blocks = [
+            {"id": "b1", "name": "B1", "description": "d1"},
+            {"id": "b2", "name": "B2", "description": "d2"},
+        ]
+        sleep_mock = AsyncMock()
+
+        with (
+            patch(
+                "backend.copilot.optimize_blocks.get_openai_client", return_value=client
+            ),
+            patch("backend.copilot.optimize_blocks.asyncio.sleep", sleep_mock),
+        ):
+            _run(_optimize_descriptions(blocks))
+
+        assert sleep_mock.call_count == 2
+        sleep_mock.assert_called_with(_RATE_LIMIT_DELAY)

autogpt_platform/backend/backend/copilot/prompting.py

@@ -0,0 +1,218 @@
+"""Centralized prompt building logic for CoPilot.
+
+This module contains all prompt construction functions and constants,
+handling the distinction between:
+- SDK mode vs Baseline mode (tool documentation needs)
+- Local mode vs E2B mode (storage/filesystem differences)
+"""
+
+from backend.copilot.tools import TOOL_REGISTRY
+
+# Shared technical notes that apply to both SDK and baseline modes
+_SHARED_TOOL_NOTES = """\
+
+### 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:
+
+- **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:
+```
+@@agptfile:workspace://abc123
+@@agptfile:workspace://abc123[10-50]
+@@agptfile:workspace:///reports/q1.md
+@@agptfile:/tmp/copilot-<session>/output.py[1-80]
+@@agptfile:/home/user/script.py
+```
+
+You can embed a reference inside any string argument, or use it as the entire
+value.  Multiple references in one argument are all expanded.
+
+
+### Sub-agent tasks
+- When using the Task tool, NEVER set `run_in_background` to true.
+  All tasks must run in the foreground.
+"""
+
+
+# Environment-specific supplement templates
+def _build_storage_supplement(
+    working_dir: str,
+    sandbox_type: str,
+    storage_system_1_name: str,
+    storage_system_1_characteristics: list[str],
+    storage_system_1_persistence: list[str],
+    file_move_name_1_to_2: str,
+    file_move_name_2_to_1: str,
+) -> str:
+    """Build storage/filesystem supplement for a specific environment.
+
+    Template function handles all formatting (bullets, indentation, markdown).
+    Callers provide clean data as lists of strings.
+
+    Args:
+        working_dir: Working directory path
+        sandbox_type: Description of bash_exec sandbox
+        storage_system_1_name: Name of primary storage (ephemeral or cloud)
+        storage_system_1_characteristics: List of characteristic descriptions
+        storage_system_1_persistence: List of persistence behavior descriptions
+        file_move_name_1_to_2: Direction label for primary→persistent
+        file_move_name_2_to_1: Direction label for persistent→primary
+    """
+    # Format lists as bullet points with proper indentation
+    characteristics = "\n".join(f"   - {c}" for c in storage_system_1_characteristics)
+    persistence = "\n".join(f"   - {p}" for p in storage_system_1_persistence)
+
+    return f"""
+
+## Tool notes
+
+### 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
+
+1. **{storage_system_1_name}** (`{working_dir}`):
+{characteristics}
+{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}"""
+
+
+# Pre-built supplements for common environments
+def _get_local_storage_supplement(cwd: str) -> str:
+    """Local ephemeral storage (files lost between turns)."""
+    return _build_storage_supplement(
+        working_dir=cwd,
+        sandbox_type="in a network-isolated sandbox",
+        storage_system_1_name="Ephemeral working directory",
+        storage_system_1_characteristics=[
+            "Shared by SDK Read/Write/Edit/Glob/Grep tools AND `bash_exec`",
+        ],
+        storage_system_1_persistence=[
+            "Files here are **lost between turns** — do NOT rely on them persisting",
+            "Use for temporary work: running scripts, processing data, etc.",
+        ],
+        file_move_name_1_to_2="Ephemeral → Persistent",
+        file_move_name_2_to_1="Persistent → Ephemeral",
+    )
+
+
+def _get_cloud_sandbox_supplement() -> str:
+    """Cloud persistent sandbox (files survive across turns in session)."""
+    return _build_storage_supplement(
+        working_dir="/home/user",
+        sandbox_type="in a cloud sandbox with full internet access",
+        storage_system_1_name="Cloud sandbox",
+        storage_system_1_characteristics=[
+            "Shared by all file tools AND `bash_exec` — same filesystem",
+            "Full Linux environment with internet access",
+        ],
+        storage_system_1_persistence=[
+            "Files **persist across turns** within the current session",
+            "Lost when the session expires (12 h inactivity)",
+        ],
+        file_move_name_1_to_2="Sandbox → Persistent",
+        file_move_name_2_to_1="Persistent → Sandbox",
+    )
+
+
+def _generate_tool_documentation() -> str:
+    """Auto-generate tool documentation from TOOL_REGISTRY.
+
+    NOTE: This is ONLY used in baseline mode (direct OpenAI API).
+    SDK mode doesn't need it since Claude gets tool schemas automatically.
+
+    This generates a complete list of available tools with their descriptions,
+    ensuring the documentation stays in sync with the actual tool implementations.
+    All workflow guidance is now embedded in individual tool descriptions.
+
+    Only documents tools that are available in the current environment
+    (checked via tool.is_available property).
+    """
+    docs = "\n## AVAILABLE TOOLS\n\n"
+
+    # Sort tools alphabetically for consistent output
+    # Filter by is_available to match get_available_tools() behavior
+    for name in sorted(TOOL_REGISTRY.keys()):
+        tool = TOOL_REGISTRY[name]
+        if not tool.is_available:
+            continue
+        schema = tool.as_openai_tool()
+        desc = schema["function"].get("description", "No description available")
+        # Format as bullet list with tool name in code style
+        docs += f"- **`{name}`**: {desc}\n"
+
+    return docs
+
+
+def get_sdk_supplement(use_e2b: bool, cwd: str = "") -> str:
+    """Get the supplement for SDK mode (Claude Agent SDK).
+
+    SDK mode does NOT include tool documentation because Claude automatically
+    receives tool schemas from the SDK. Only includes technical notes about
+    storage systems and execution environment.
+
+    Args:
+        use_e2b: Whether E2B cloud sandbox is being used
+        cwd: Current working directory (only used in local_storage mode)
+
+    Returns:
+        The supplement string to append to the system prompt
+    """
+    if use_e2b:
+        return _get_cloud_sandbox_supplement()
+    return _get_local_storage_supplement(cwd)
+
+
+def get_baseline_supplement() -> str:
+    """Get the supplement for baseline mode (direct OpenAI API).
+
+    Baseline mode INCLUDES auto-generated tool documentation because the
+    direct API doesn't automatically provide tool schemas to Claude.
+    Also includes shared technical notes (but NOT SDK-specific environment details).
+
+    Returns:
+        The supplement string to append to the system prompt
+    """
+    tool_docs = _generate_tool_documentation()
+    return tool_docs + _SHARED_TOOL_NOTES

autogpt_platform/backend/backend/copilot/sdk/agent_generation_guide.md

@@ -0,0 +1,155 @@
+## Agent Generation Guide
+
+You can create, edit, and customize agents directly. You ARE the brain —
+generate the agent JSON yourself using block schemas, then validate and save.
+
+### Workflow for Creating/Editing Agents
+
+1. **Discover blocks**: Call `find_block(query, include_schemas=true)` to
+   search for relevant blocks. This returns block IDs, names, descriptions,
+   and full input/output schemas.
+2. **Find library agents**: Call `find_library_agent` to discover reusable
+   agents that can be composed as sub-agents via `AgentExecutorBlock`.
+3. **Generate JSON**: Build the agent JSON using block schemas:
+   - Use block IDs from step 1 as `block_id` in nodes
+   - Wire outputs to inputs using links
+   - Set design-time config in `input_default`
+   - Use `AgentInputBlock` for values the user provides at runtime
+4. **Write to workspace**: Save the JSON to a workspace file so the user
+   can review it: `write_workspace_file(filename="agent.json", content=...)`
+5. **Validate**: Call `validate_agent_graph` with the agent JSON to check
+   for errors
+6. **Fix if needed**: Call `fix_agent_graph` to auto-fix common issues,
+   or fix manually based on the error descriptions. Iterate until valid.
+7. **Save**: Call `create_agent` (new) or `edit_agent` (existing) with
+   the final `agent_json`
+
+### Agent JSON Structure
+
+```json
+{
+  "id": "<UUID v4>",        // auto-generated if omitted
+  "version": 1,
+  "is_active": true,
+  "name": "Agent Name",
+  "description": "What the agent does",
+  "nodes": [
+    {
+      "id": "<UUID v4>",
+      "block_id": "<block UUID from find_block>",
+      "input_default": {
+        "field_name": "design-time value"
+      },
+      "metadata": {
+        "position": {"x": 0, "y": 0},
+        "customized_name": "Optional display name"
+      }
+    }
+  ],
+  "links": [
+    {
+      "id": "<UUID v4>",
+      "source_id": "<source node UUID>",
+      "source_name": "output_field_name",
+      "sink_id": "<sink node UUID>",
+      "sink_name": "input_field_name",
+      "is_static": false
+    }
+  ]
+}
+```
+
+### REQUIRED: AgentInputBlock and AgentOutputBlock
+
+Every agent MUST include at least one AgentInputBlock and one AgentOutputBlock.
+These define the agent's interface — what it accepts and what it produces.
+
+**AgentInputBlock** (ID: `c0a8e994-ebf1-4a9c-a4d8-89d09c86741b`):
+- Defines a user-facing input field on the agent
+- Required `input_default` fields: `name` (str), `value` (default: null)
+- Optional: `title`, `description`, `placeholder_values` (for dropdowns)
+- Output: `result` — the user-provided value at runtime
+- Create one AgentInputBlock per distinct input the agent needs
+
+**AgentOutputBlock** (ID: `363ae599-353e-4804-937e-b2ee3cef3da4`):
+- Defines a user-facing output displayed after the agent runs
+- Required `input_default` fields: `name` (str)
+- The `value` input should be linked from another block's output
+- Optional: `title`, `description`, `format` (Jinja2 template)
+- Create one AgentOutputBlock per distinct result to show the user
+
+Without these blocks, the agent has no interface and the user cannot provide
+inputs or see outputs. NEVER skip them.
+
+### Key Rules
+
+- **Name & description**: Include `name` and `description` in the agent JSON
+  when creating a new agent, or when editing and the agent's purpose changed.
+  Without these the agent gets a generic default name.
+- **Design-time vs runtime**: `input_default` = values known at build time.
+  For user-provided values, create an `AgentInputBlock` node and link its
+  output to the consuming block's input.
+- **Credentials**: Do NOT require credentials upfront. Users configure
+  credentials later in the platform UI after the agent is saved.
+- **Node spacing**: Position nodes with at least 800 X-units between them.
+- **Nested properties**: Use `parentField_#_childField` notation in link
+  sink_name/source_name to access nested object fields.
+- **is_static links**: Set `is_static: true` when the link carries a
+  design-time constant (matches a field in inputSchema with a default).
+- **ConditionBlock**: Needs a `StoreValueBlock` wired to its `value2` input.
+- **Prompt templates**: Use `{{variable}}` (double curly braces) for
+  literal braces in prompt strings — single `{` and `}` are for
+  template variables.
+- **AgentExecutorBlock**: When composing sub-agents, set `graph_id` and
+  `graph_version` in input_default, and wire inputs/outputs to match
+  the sub-agent's schema.
+
+### Using Sub-Agents (AgentExecutorBlock)
+
+To compose agents using other agents as sub-agents:
+1. Call `find_library_agent` to find the sub-agent — the response includes
+   `graph_id`, `graph_version`, `input_schema`, and `output_schema`
+2. Create an `AgentExecutorBlock` node (ID: `e189baac-8c20-45a1-94a7-55177ea42565`)
+3. Set `input_default`:
+   - `graph_id`: from the library agent's `graph_id`
+   - `graph_version`: from the library agent's `graph_version`
+   - `input_schema`: from the library agent's `input_schema` (JSON Schema)
+   - `output_schema`: from the library agent's `output_schema` (JSON Schema)
+   - `user_id`: leave as `""` (filled at runtime)
+   - `inputs`: `{}` (populated by links at runtime)
+4. Wire inputs: link to sink names matching the sub-agent's `input_schema`
+   property names (e.g., if input_schema has a `"url"` property, use
+   `"url"` as the sink_name)
+5. Wire outputs: link from source names matching the sub-agent's
+   `output_schema` property names
+6. Pass `library_agent_ids` to `create_agent`/`customize_agent` with
+   the library agent IDs used, so the fixer can validate schemas
+
+### Using MCP Tools (MCPToolBlock)
+
+To use an MCP (Model Context Protocol) tool as a node in the agent:
+1. The user must specify which MCP server URL and tool name they want
+2. Create an `MCPToolBlock` node (ID: `a0a4b1c2-d3e4-4f56-a7b8-c9d0e1f2a3b4`)
+3. Set `input_default`:
+   - `server_url`: the MCP server URL (e.g. `"https://mcp.example.com/sse"`)
+   - `selected_tool`: the tool name on that server
+   - `tool_input_schema`: JSON Schema for the tool's inputs
+   - `tool_arguments`: `{}` (populated by links or hardcoded values)
+4. The block requires MCP credentials — the user configures these in the
+   platform UI after the agent is saved
+5. Wire inputs using the tool argument field name directly as the sink_name
+   (e.g., `query`, NOT `tool_arguments_#_query`). The execution engine
+   automatically collects top-level fields matching tool_input_schema into
+   tool_arguments.
+6. Output: `result` (the tool's return value) and `error` (error message)
+
+### Example: Simple AI Text Processor
+
+A minimal agent with input, processing, and output:
+- Node 1: `AgentInputBlock` (ID: `c0a8e994-ebf1-4a9c-a4d8-89d09c86741b`,
+  input_default: {"name": "user_text", "title": "Text to process"},
+  output: "result")
+- Node 2: `AITextGeneratorBlock` (input: "prompt" linked from Node 1's "result")
+- Node 3: `AgentOutputBlock` (ID: `363ae599-353e-4804-937e-b2ee3cef3da4`,
+  input_default: {"name": "summary", "title": "Summary"},
+  input: "value" linked from Node 2's output)

autogpt_platform/backend/backend/copilot/sdk/e2b_file_tools.py

@@ -8,8 +8,6 @@ SDK-internal paths (``~/.claude/projects/…/tool-results/``) are handled
 by the separate ``Read`` MCP tool registered in ``tool_adapter.py``.
 """
 
-from __future__ import annotations
-
 import itertools
 import json
 import logging
@@ -17,36 +15,23 @@ import os
 import shlex
 from typing import Any, Callable
 
-from backend.copilot.tools.e2b_sandbox import E2B_WORKDIR
+from backend.copilot.context import (
+    E2B_WORKDIR,
+    get_current_sandbox,
+    get_sdk_cwd,
+    is_allowed_local_path,
+    resolve_sandbox_path,
+)
 
 logger = logging.getLogger(__name__)
 
 
-# Lazy imports to break circular dependency with tool_adapter.
-
-
-def _get_sandbox():  # type: ignore[return]
-    from .tool_adapter import get_current_sandbox  # noqa: E402
-
+def _get_sandbox():
     return get_current_sandbox()
 
 
 def _is_allowed_local(path: str) -> bool:
-    from .tool_adapter import is_allowed_local_path  # noqa: E402
-
-    return is_allowed_local_path(path)
-
-
-def _resolve_remote(path: str) -> str:
-    """Normalise *path* to an absolute sandbox path under ``/home/user``.
-
-    Raises :class:`ValueError` if the resolved path escapes the sandbox.
-    """
-    candidate = path if os.path.isabs(path) else os.path.join(E2B_WORKDIR, path)
-    normalized = os.path.normpath(candidate)
-    if normalized != E2B_WORKDIR and not normalized.startswith(E2B_WORKDIR + "/"):
-        raise ValueError(f"Path must be within {E2B_WORKDIR}: {path}")
-    return normalized
+    return is_allowed_local_path(path, get_sdk_cwd())
 
 
 def _mcp(text: str, *, error: bool = False) -> dict[str, Any]:
@@ -63,7 +48,7 @@ def _get_sandbox_and_path(
     if sandbox is None:
         return _mcp("No E2B sandbox available", error=True)
     try:
-        remote = _resolve_remote(file_path)
+        remote = resolve_sandbox_path(file_path)
     except ValueError as exc:
         return _mcp(str(exc), error=True)
     return sandbox, remote
@@ -73,6 +58,7 @@ def _get_sandbox_and_path(
 
 
 async def _handle_read_file(args: dict[str, Any]) -> dict[str, Any]:
+    """Read lines from a sandbox file, falling back to the local host for SDK-internal paths."""
     file_path: str = args.get("file_path", "")
     offset: int = max(0, int(args.get("offset", 0)))
     limit: int = max(1, int(args.get("limit", 2000)))
@@ -104,6 +90,7 @@ async def _handle_read_file(args: dict[str, Any]) -> dict[str, Any]:
 
 
 async def _handle_write_file(args: dict[str, Any]) -> dict[str, Any]:
+    """Write content to a sandbox file, creating parent directories as needed."""
     file_path: str = args.get("file_path", "")
     content: str = args.get("content", "")
 
@@ -127,6 +114,7 @@ async def _handle_write_file(args: dict[str, Any]) -> dict[str, Any]:
 
 
 async def _handle_edit_file(args: dict[str, Any]) -> dict[str, Any]:
+    """Replace a substring in a sandbox file, with optional replace-all support."""
     file_path: str = args.get("file_path", "")
     old_string: str = args.get("old_string", "")
     new_string: str = args.get("new_string", "")
@@ -172,6 +160,7 @@ async def _handle_edit_file(args: dict[str, Any]) -> dict[str, Any]:
 
 
 async def _handle_glob(args: dict[str, Any]) -> dict[str, Any]:
+    """Find files matching a name pattern inside the sandbox using ``find``."""
     pattern: str = args.get("pattern", "")
     path: str = args.get("path", "")
 
@@ -183,7 +172,7 @@ async def _handle_glob(args: dict[str, Any]) -> dict[str, Any]:
         return _mcp("No E2B sandbox available", error=True)
 
     try:
-        search_dir = _resolve_remote(path) if path else E2B_WORKDIR
+        search_dir = resolve_sandbox_path(path) if path else E2B_WORKDIR
     except ValueError as exc:
         return _mcp(str(exc), error=True)
 
@@ -198,6 +187,7 @@ async def _handle_glob(args: dict[str, Any]) -> dict[str, Any]:
 
 
 async def _handle_grep(args: dict[str, Any]) -> dict[str, Any]:
+    """Search file contents by regex inside the sandbox using ``grep -rn``."""
     pattern: str = args.get("pattern", "")
     path: str = args.get("path", "")
     include: str = args.get("include", "")
@@ -210,7 +200,7 @@ async def _handle_grep(args: dict[str, Any]) -> dict[str, Any]:
         return _mcp("No E2B sandbox available", error=True)
 
     try:
-        search_dir = _resolve_remote(path) if path else E2B_WORKDIR
+        search_dir = resolve_sandbox_path(path) if path else E2B_WORKDIR
     except ValueError as exc:
         return _mcp(str(exc), error=True)
 
@@ -238,7 +228,7 @@ def _read_local(file_path: str, offset: int, limit: int) -> dict[str, Any]:
         return _mcp(f"Path not allowed: {file_path}", error=True)
     expanded = os.path.realpath(os.path.expanduser(file_path))
     try:
-        with open(expanded) as fh:
+        with open(expanded, encoding="utf-8", errors="replace") as fh:
             selected = list(itertools.islice(fh, offset, offset + limit))
         numbered = "".join(
             f"{i + offset + 1:>6}\t{line}" for i, line in enumerate(selected)

autogpt_platform/backend/backend/copilot/sdk/e2b_file_tools_test.py

@@ -7,59 +7,60 @@ import os
 
 import pytest
 
-from .e2b_file_tools import _read_local, _resolve_remote
-from .tool_adapter import _current_project_dir
+from backend.copilot.context import _current_project_dir
+
+from .e2b_file_tools import _read_local, resolve_sandbox_path
 
 _SDK_PROJECTS_DIR = os.path.realpath(os.path.expanduser("~/.claude/projects"))
 
 
 # ---------------------------------------------------------------------------
-# _resolve_remote — sandbox path normalisation & boundary enforcement
+# resolve_sandbox_path — sandbox path normalisation & boundary enforcement
 # ---------------------------------------------------------------------------
 
 
-class TestResolveRemote:
+class TestResolveSandboxPath:
     def test_relative_path_resolved(self):
-        assert _resolve_remote("src/main.py") == "/home/user/src/main.py"
+        assert resolve_sandbox_path("src/main.py") == "/home/user/src/main.py"
 
     def test_absolute_within_sandbox(self):
-        assert _resolve_remote("/home/user/file.txt") == "/home/user/file.txt"
+        assert resolve_sandbox_path("/home/user/file.txt") == "/home/user/file.txt"
 
     def test_workdir_itself(self):
-        assert _resolve_remote("/home/user") == "/home/user"
+        assert resolve_sandbox_path("/home/user") == "/home/user"
 
     def test_relative_dotslash(self):
-        assert _resolve_remote("./README.md") == "/home/user/README.md"
+        assert resolve_sandbox_path("./README.md") == "/home/user/README.md"
 
     def test_traversal_blocked(self):
         with pytest.raises(ValueError, match="must be within /home/user"):
-            _resolve_remote("../../etc/passwd")
+            resolve_sandbox_path("../../etc/passwd")
 
     def test_absolute_traversal_blocked(self):
         with pytest.raises(ValueError, match="must be within /home/user"):
-            _resolve_remote("/home/user/../../etc/passwd")
+            resolve_sandbox_path("/home/user/../../etc/passwd")
 
     def test_absolute_outside_sandbox_blocked(self):
         with pytest.raises(ValueError, match="must be within /home/user"):
-            _resolve_remote("/etc/passwd")
+            resolve_sandbox_path("/etc/passwd")
 
     def test_root_blocked(self):
         with pytest.raises(ValueError, match="must be within /home/user"):
-            _resolve_remote("/")
+            resolve_sandbox_path("/")
 
     def test_home_other_user_blocked(self):
         with pytest.raises(ValueError, match="must be within /home/user"):
-            _resolve_remote("/home/other/file.txt")
+            resolve_sandbox_path("/home/other/file.txt")
 
     def test_deep_nested_allowed(self):
-        assert _resolve_remote("a/b/c/d/e.txt") == "/home/user/a/b/c/d/e.txt"
+        assert resolve_sandbox_path("a/b/c/d/e.txt") == "/home/user/a/b/c/d/e.txt"
 
     def test_trailing_slash_normalised(self):
-        assert _resolve_remote("src/") == "/home/user/src"
+        assert resolve_sandbox_path("src/") == "/home/user/src"
 
     def test_double_dots_within_sandbox_ok(self):
         """Path that resolves back within /home/user is allowed."""
-        assert _resolve_remote("a/b/../c.txt") == "/home/user/a/c.txt"
+        assert resolve_sandbox_path("a/b/../c.txt") == "/home/user/a/c.txt"
 
 
 # ---------------------------------------------------------------------------

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

@@ -0,0 +1,281 @@
+"""File reference protocol for tool call inputs.
+
+Allows the LLM to pass a file reference instead of embedding large content
+inline.  The processor expands ``@@agptfile:<uri>[<start>-<end>]`` tokens in tool
+arguments before the tool is executed.
+
+Protocol
+--------
+
+    @@agptfile:<uri>[<start>-<end>]
+
+``<uri>`` (required)
+    - ``workspace://<file_id>`` — workspace file by ID
+    - ``workspace://<file_id>#<mime>`` — same, MIME hint is ignored for reads
+    - ``workspace:///<path>`` — workspace file by virtual path
+    - ``/absolute/local/path`` — ephemeral or sdk_cwd file (validated by
+      :func:`~backend.copilot.sdk.tool_adapter.is_allowed_local_path`)
+    - Any absolute path that resolves inside the E2B sandbox
+      (``/home/user/...``) when a sandbox is active
+
+``[<start>-<end>]`` (optional)
+    Line range, 1-indexed inclusive.  Examples: ``[1-100]``, ``[50-200]``.
+    Omit to read the entire file.
+
+Examples
+--------
+    @@agptfile:workspace://abc123
+    @@agptfile:workspace://abc123[10-50]
+    @@agptfile:workspace:///reports/q1.md
+    @@agptfile:/tmp/copilot-<session>/output.py[1-80]
+    @@agptfile:/home/user/script.sh
+"""
+
+import itertools
+import logging
+import os
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from backend.copilot.context import (
+    get_current_sandbox,
+    get_sdk_cwd,
+    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
+
+
+class FileRefExpansionError(Exception):
+    """Raised when a ``@@agptfile:`` reference in tool call args fails to resolve.
+
+    Separating this from inline substitution lets callers (e.g. the MCP tool
+    wrapper) block tool execution and surface a helpful error to the model
+    rather than passing an ``[file-ref error: …]`` string as actual input.
+    """
+
+
+logger = logging.getLogger(__name__)
+
+FILE_REF_PREFIX = "@@agptfile:"
+
+# Matches:  @@agptfile:<uri>[start-end]?
+#   Group 1 – URI; must start with '/' (absolute path) or 'workspace://'
+#   Group 2 – start line (optional)
+#   Group 3 – end line (optional)
+_FILE_REF_RE = re.compile(
+    re.escape(FILE_REF_PREFIX) + r"((?:workspace://|/)[^\[\s]*)(?:\[(\d+)-(\d+)\])?"
+)
+
+# Maximum characters returned for a single file reference expansion.
+_MAX_EXPAND_CHARS = 200_000
+# Maximum total characters across all @@agptfile: expansions in one string.
+_MAX_TOTAL_EXPAND_CHARS = 1_000_000
+
+
+@dataclass
+class FileRef:
+    uri: str
+    start_line: int | None  # 1-indexed, inclusive
+    end_line: int | None  # 1-indexed, inclusive
+
+
+def parse_file_ref(text: str) -> FileRef | None:
+    """Return a :class:`FileRef` if *text* is a bare file reference token.
+
+    A "bare token" means the entire string matches the ``@@agptfile:...`` pattern
+    (after stripping whitespace).  Use :func:`expand_file_refs_in_string` to
+    expand references embedded in larger strings.
+    """
+    m = _FILE_REF_RE.fullmatch(text.strip())
+    if not m:
+        return None
+    start = int(m.group(2)) if m.group(2) else None
+    end = int(m.group(3)) if m.group(3) else None
+    if start is not None and start < 1:
+        return None
+    if end is not None and end < 1:
+        return None
+    if start is not None and end is not None and end < start:
+        return 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,
+    session: ChatSession,
+) -> bytes:
+    """Resolve *uri* to raw bytes using workspace, local, or E2B path logic.
+
+    Raises :class:`ValueError` if the URI cannot be resolved.
+    """
+    # Strip MIME fragment (e.g. workspace://id#mime) before dispatching.
+    plain = uri.split("#")[0] if uri.startswith("workspace://") else uri
+
+    if plain.startswith("workspace://"):
+        if not user_id:
+            raise ValueError("workspace:// file references require authentication")
+        manager = await get_manager(user_id, session.session_id)
+        ws = parse_workspace_uri(plain)
+        try:
+            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 Exception as exc:
+            raise ValueError(f"Failed to read {plain}: {exc}") from exc
+
+    if is_allowed_local_path(plain, get_sdk_cwd()):
+        resolved = os.path.realpath(os.path.expanduser(plain))
+        try:
+            with open(resolved, "rb") as fh:
+                return fh.read()
+        except FileNotFoundError:
+            raise ValueError(f"File not found: {plain}")
+        except Exception as exc:
+            raise ValueError(f"Failed to read {plain}: {exc}") from exc
+
+    sandbox = get_current_sandbox()
+    if sandbox is not None:
+        try:
+            remote = resolve_sandbox_path(plain)
+        except ValueError as exc:
+            raise ValueError(
+                f"Path is not allowed (not in workspace, sdk_cwd, or sandbox): {plain}"
+            ) from exc
+        try:
+            return bytes(await sandbox.files.read(remote, format="bytes"))
+        except Exception as exc:
+            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}"
+    )
+
+
+async def resolve_file_ref(
+    ref: FileRef,
+    user_id: str | None,
+    session: ChatSession,
+) -> str:
+    """Resolve a :class:`FileRef` to its text content."""
+    raw = await read_file_bytes(ref.uri, user_id, session)
+    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",
+    *,
+    raise_on_error: bool = False,
+) -> str:
+    """Expand all ``@@agptfile:...`` tokens in *text*, returning the substituted string.
+
+    Non-reference text is passed through unchanged.
+
+    If *raise_on_error* is ``False`` (default), expansion errors are surfaced
+    inline as ``[file-ref error: <message>]`` — useful for display/log contexts
+    where partial expansion is acceptable.
+
+    If *raise_on_error* is ``True``, any resolution failure raises
+    :class:`FileRefExpansionError` immediately so the caller can block the
+    operation and surface a clean error to the model.
+    """
+    if FILE_REF_PREFIX not in text:
+        return text
+
+    result: list[str] = []
+    last_end = 0
+    total_chars = 0
+    for m in _FILE_REF_RE.finditer(text):
+        result.append(text[last_end : m.start()])
+        start = int(m.group(2)) if m.group(2) else None
+        end = int(m.group(3)) if m.group(3) else None
+        if (start is not None and start < 1) or (end is not None and end < 1):
+            msg = f"line numbers must be >= 1: {m.group(0)}"
+            if raise_on_error:
+                raise FileRefExpansionError(msg)
+            result.append(f"[file-ref error: {msg}]")
+            last_end = m.end()
+            continue
+        if start is not None and end is not None and end < start:
+            msg = f"end line must be >= start line: {m.group(0)}"
+            if raise_on_error:
+                raise FileRefExpansionError(msg)
+            result.append(f"[file-ref error: {msg}]")
+            last_end = m.end()
+            continue
+        ref = FileRef(uri=m.group(1), start_line=start, end_line=end)
+        try:
+            content = await resolve_file_ref(ref, user_id, session)
+            if len(content) > _MAX_EXPAND_CHARS:
+                content = content[:_MAX_EXPAND_CHARS] + "\n... [truncated]"
+            remaining = _MAX_TOTAL_EXPAND_CHARS - total_chars
+            if remaining <= 0:
+                content = "[file-ref budget exhausted: total expansion limit reached]"
+            elif len(content) > remaining:
+                content = content[:remaining] + "\n... [total budget exhausted]"
+            total_chars += len(content)
+            result.append(content)
+        except ValueError as exc:
+            logger.warning("file-ref expansion failed for %r: %s", m.group(0), exc)
+            if raise_on_error:
+                raise FileRefExpansionError(str(exc)) from exc
+            result.append(f"[file-ref error: {exc}]")
+        last_end = m.end()
+
+    result.append(text[last_end:])
+    return "".join(result)
+
+
+async def expand_file_refs_in_args(
+    args: dict[str, Any],
+    user_id: str | 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.
+
+    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
+    response that lets the model correct the reference before retrying.
+    """
+    if not args:
+        return args
+
+    async def _expand(value: Any) -> Any:
+        if isinstance(value, str):
+            return await expand_file_refs_in_string(
+                value, user_id, session, raise_on_error=True
+            )
+        if isinstance(value, dict):
+            return {k: await _expand(v) for k, v in value.items()}
+        if isinstance(value, list):
+            return [await _expand(item) for item in value]
+        return value
+
+    return {k: await _expand(v) for k, v in args.items()}

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

@@ -0,0 +1,328 @@
+"""Integration tests for @@agptfile: reference expansion in tool calls.
+
+These tests verify the end-to-end behaviour of the file reference protocol:
+- Parsing @@agptfile: tokens from tool arguments
+- Resolving local-filesystem paths (sdk_cwd / ephemeral)
+- Expanding references inside the tool-call pipeline (_execute_tool_sync)
+- The extended Read tool handler (workspace:// pass-through via session context)
+
+No real LLM or database is required; workspace reads are stubbed where needed.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from backend.copilot.sdk.file_ref import (
+    FileRef,
+    expand_file_refs_in_args,
+    expand_file_refs_in_string,
+    read_file_bytes,
+    resolve_file_ref,
+)
+from backend.copilot.sdk.tool_adapter import _read_file_handler
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _make_session(session_id: str = "integ-sess") -> MagicMock:
+    s = MagicMock()
+    s.session_id = session_id
+    return s
+
+
+# ---------------------------------------------------------------------------
+# Local-file resolution (sdk_cwd)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_resolve_file_ref_local_path():
+    """resolve_file_ref reads a real local file when it's within sdk_cwd."""
+    with tempfile.TemporaryDirectory() as sdk_cwd:
+        # Write a test file inside sdk_cwd
+        test_file = os.path.join(sdk_cwd, "hello.txt")
+        with open(test_file, "w") as f:
+            f.write("line1\nline2\nline3\n")
+
+        session = _make_session()
+        with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd_var:
+            mock_cwd_var.get.return_value = sdk_cwd
+
+            ref = FileRef(uri=test_file, start_line=None, end_line=None)
+            content = await resolve_file_ref(ref, user_id="u1", session=session)
+
+        assert content == "line1\nline2\nline3\n"
+
+
+@pytest.mark.asyncio
+async def test_resolve_file_ref_local_path_with_line_range():
+    """resolve_file_ref respects line ranges for local files."""
+    with tempfile.TemporaryDirectory() as sdk_cwd:
+        test_file = os.path.join(sdk_cwd, "multi.txt")
+        lines = [f"line{i}\n" for i in range(1, 11)]  # line1 … line10
+        with open(test_file, "w") as f:
+            f.writelines(lines)
+
+        session = _make_session()
+        with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd_var:
+            mock_cwd_var.get.return_value = sdk_cwd
+
+            ref = FileRef(uri=test_file, start_line=3, end_line=5)
+            content = await resolve_file_ref(ref, user_id="u1", session=session)
+
+        assert content == "line3\nline4\nline5\n"
+
+
+@pytest.mark.asyncio
+async def test_resolve_file_ref_rejects_path_outside_sdk_cwd():
+    """resolve_file_ref raises ValueError for paths outside sdk_cwd."""
+    with tempfile.TemporaryDirectory() as sdk_cwd:
+        with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd_var, patch(
+            "backend.copilot.context._current_sandbox"
+        ) as mock_sandbox_var:
+            mock_cwd_var.get.return_value = sdk_cwd
+            mock_sandbox_var.get.return_value = None
+
+            ref = FileRef(uri="/etc/passwd", start_line=None, end_line=None)
+            with pytest.raises(ValueError, match="not allowed"):
+                await resolve_file_ref(ref, user_id="u1", session=_make_session())
+
+
+# ---------------------------------------------------------------------------
+# expand_file_refs_in_string — integration with real files
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_expand_string_with_real_file():
+    """expand_file_refs_in_string replaces @@agptfile: token with actual content."""
+    with tempfile.TemporaryDirectory() as sdk_cwd:
+        test_file = os.path.join(sdk_cwd, "data.txt")
+        with open(test_file, "w") as f:
+            f.write("hello world\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_string(
+                f"Content: @@agptfile:{test_file}",
+                user_id="u1",
+                session=_make_session(),
+            )
+
+        assert result == "Content: hello world\n"
+
+
+@pytest.mark.asyncio
+async def test_expand_string_missing_file_is_surfaced_inline():
+    """Missing file ref yields [file-ref error: …] inline rather than raising."""
+    with tempfile.TemporaryDirectory() as sdk_cwd:
+        missing = os.path.join(sdk_cwd, "does_not_exist.txt")
+
+        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_string(
+                f"@@agptfile:{missing}",
+                user_id="u1",
+                session=_make_session(),
+            )
+
+        assert "[file-ref error:" in result
+        assert "not found" in result.lower() or "not allowed" in result.lower()
+
+
+# ---------------------------------------------------------------------------
+# expand_file_refs_in_args — dict traversal with real files
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_expand_args_replaces_file_ref_in_nested_dict():
+    """Nested @@agptfile: references in args are fully expanded."""
+    with tempfile.TemporaryDirectory() as sdk_cwd:
+        file_a = os.path.join(sdk_cwd, "a.txt")
+        file_b = os.path.join(sdk_cwd, "b.txt")
+        with open(file_a, "w") as f:
+            f.write("AAA")
+        with open(file_b, "w") as f:
+            f.write("BBB")
+
+        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(
+                {
+                    "outer": {
+                        "content_a": f"@@agptfile:{file_a}",
+                        "content_b": f"start @@agptfile:{file_b} end",
+                    },
+                    "count": 42,
+                },
+                user_id="u1",
+                session=_make_session(),
+            )
+
+        assert result["outer"]["content_a"] == "AAA"
+        assert result["outer"]["content_b"] == "start BBB end"
+        assert result["count"] == 42
+
+
+# ---------------------------------------------------------------------------
+# _read_file_handler — extended to accept workspace:// and local paths
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_read_file_handler_local_file():
+    """_read_file_handler reads a local file when it's within sdk_cwd."""
+    with tempfile.TemporaryDirectory() as sdk_cwd:
+        test_file = os.path.join(sdk_cwd, "read_test.txt")
+        lines = [f"L{i}\n" for i in range(1, 6)]
+        with open(test_file, "w") as f:
+            f.writelines(lines)
+
+        with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd_var, patch(
+            "backend.copilot.context._current_project_dir"
+        ) as mock_proj_var, patch(
+            "backend.copilot.sdk.tool_adapter.get_execution_context",
+            return_value=("user-1", _make_session()),
+        ):
+            mock_cwd_var.get.return_value = sdk_cwd
+            mock_proj_var.get.return_value = ""
+
+            result = await _read_file_handler(
+                {"file_path": test_file, "offset": 0, "limit": 5}
+            )
+
+        assert not result["isError"]
+        text = result["content"][0]["text"]
+        assert "L1" in text
+        assert "L5" in text
+
+
+@pytest.mark.asyncio
+async def test_read_file_handler_workspace_uri():
+    """_read_file_handler handles workspace:// URIs via the workspace manager."""
+    mock_session = _make_session()
+    mock_manager = AsyncMock()
+    mock_manager.read_file_by_id.return_value = b"workspace file content\nline two\n"
+
+    with patch(
+        "backend.copilot.sdk.tool_adapter.get_execution_context",
+        return_value=("user-1", mock_session),
+    ), patch(
+        "backend.copilot.sdk.file_ref.get_manager",
+        new=AsyncMock(return_value=mock_manager),
+    ):
+        result = await _read_file_handler(
+            {"file_path": "workspace://file-id-abc", "offset": 0, "limit": 10}
+        )
+
+    assert not result["isError"], result["content"][0]["text"]
+    text = result["content"][0]["text"]
+    assert "workspace file content" in text
+    assert "line two" in text
+
+
+@pytest.mark.asyncio
+async def test_read_file_handler_workspace_uri_no_session():
+    """_read_file_handler returns error when workspace:// is used without session."""
+    with patch(
+        "backend.copilot.sdk.tool_adapter.get_execution_context",
+        return_value=(None, None),
+    ):
+        result = await _read_file_handler({"file_path": "workspace://some-id"})
+
+    assert result["isError"]
+    assert "session" in result["content"][0]["text"].lower()
+
+
+@pytest.mark.asyncio
+async def test_read_file_handler_access_denied():
+    """_read_file_handler rejects paths outside allowed locations."""
+    with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd, patch(
+        "backend.copilot.context._current_sandbox"
+    ) as mock_sandbox, patch(
+        "backend.copilot.sdk.tool_adapter.get_execution_context",
+        return_value=("user-1", _make_session()),
+    ):
+        mock_cwd.get.return_value = "/tmp/safe-dir"
+        mock_sandbox.get.return_value = None
+
+        result = await _read_file_handler({"file_path": "/etc/passwd"})
+
+    assert result["isError"]
+    assert "not allowed" in result["content"][0]["text"].lower()
+
+
+# ---------------------------------------------------------------------------
+# read_file_bytes — workspace:///path (virtual path) and E2B sandbox branch
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_read_file_bytes_workspace_virtual_path():
+    """workspace:///path resolves via manager.read_file (is_path=True path)."""
+    session = _make_session()
+    mock_manager = AsyncMock()
+    mock_manager.read_file.return_value = b"virtual path content"
+
+    with patch(
+        "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)
+
+    assert result == b"virtual path content"
+    mock_manager.read_file.assert_awaited_once_with("/reports/q1.md")
+
+
+@pytest.mark.asyncio
+async def test_read_file_bytes_e2b_sandbox_branch():
+    """read_file_bytes reads from the E2B sandbox when a sandbox is active."""
+    session = _make_session()
+    mock_sandbox = AsyncMock()
+    mock_sandbox.files.read.return_value = bytearray(b"sandbox content")
+
+    with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd, patch(
+        "backend.copilot.context._current_sandbox"
+    ) as mock_sandbox_var, patch(
+        "backend.copilot.context._current_project_dir"
+    ) as mock_proj:
+        mock_cwd.get.return_value = ""
+        mock_sandbox_var.get.return_value = mock_sandbox
+        mock_proj.get.return_value = ""
+
+        result = await read_file_bytes("/home/user/script.sh", None, session)
+
+    assert result == b"sandbox content"
+    mock_sandbox.files.read.assert_awaited_once_with(
+        "/home/user/script.sh", format="bytes"
+    )
+
+
+@pytest.mark.asyncio
+async def test_read_file_bytes_e2b_path_escapes_sandbox_raises():
+    """read_file_bytes raises ValueError for paths that escape the sandbox root."""
+    session = _make_session()
+    mock_sandbox = AsyncMock()
+
+    with patch("backend.copilot.context._current_sdk_cwd") as mock_cwd, patch(
+        "backend.copilot.context._current_sandbox"
+    ) as mock_sandbox_var, patch(
+        "backend.copilot.context._current_project_dir"
+    ) as mock_proj:
+        mock_cwd.get.return_value = ""
+        mock_sandbox_var.get.return_value = mock_sandbox
+        mock_proj.get.return_value = ""
+
+        with pytest.raises(ValueError, match="not allowed"):
+            await read_file_bytes("/etc/passwd", None, session)