refactor: address review feedback

- Move helpers after search_agents function
- Simplify list_all logic by setting query='' early
- Update find_library_agent description to 'Search for or list'

.branchlet.json

@@ -29,8 +29,7 @@
   "postCreateCmd": [
     "cd autogpt_platform/autogpt_libs && poetry install",
     "cd autogpt_platform/backend && poetry install && poetry run prisma generate",
-    "cd autogpt_platform/frontend && pnpm install",
-    "cd docs && pip install -r requirements.txt"
+    "cd autogpt_platform/frontend && pnpm install"
   ],
   "terminalCommand": "code .",
   "deleteBranchWithWorktree": false

.dockerignore

@@ -5,42 +5,13 @@
 !docs/
 
 # Platform - Libs
-!autogpt_platform/autogpt_libs/autogpt_libs/
-!autogpt_platform/autogpt_libs/pyproject.toml
-!autogpt_platform/autogpt_libs/poetry.lock
-!autogpt_platform/autogpt_libs/README.md
+!autogpt_platform/autogpt_libs/
 
 # Platform - Backend
-!autogpt_platform/backend/backend/
-!autogpt_platform/backend/test/e2e_test_data.py
-!autogpt_platform/backend/migrations/
-!autogpt_platform/backend/schema.prisma
-!autogpt_platform/backend/pyproject.toml
-!autogpt_platform/backend/poetry.lock
-!autogpt_platform/backend/README.md
-!autogpt_platform/backend/.env
-!autogpt_platform/backend/gen_prisma_types_stub.py
-
-# Platform - Market
-!autogpt_platform/market/market/
-!autogpt_platform/market/scripts.py
-!autogpt_platform/market/schema.prisma
-!autogpt_platform/market/pyproject.toml
-!autogpt_platform/market/poetry.lock
-!autogpt_platform/market/README.md
+!autogpt_platform/backend/
 
 # Platform - Frontend
-!autogpt_platform/frontend/src/
-!autogpt_platform/frontend/public/
-!autogpt_platform/frontend/scripts/
-!autogpt_platform/frontend/package.json
-!autogpt_platform/frontend/pnpm-lock.yaml
-!autogpt_platform/frontend/tsconfig.json
-!autogpt_platform/frontend/README.md
-## config
-!autogpt_platform/frontend/*.config.*
-!autogpt_platform/frontend/.env.*
-!autogpt_platform/frontend/.env
+!autogpt_platform/frontend/
 
 # Classic - AutoGPT
 !classic/original_autogpt/autogpt/
@@ -64,6 +35,38 @@
 # Classic - Frontend
 !classic/frontend/build/web/
 
-# Explicitly re-ignore some folders
-.*
-**/__pycache__
+# Explicitly re-ignore unwanted files from whitelisted directories
+# Note: These patterns MUST come after the whitelist rules to take effect
+
+# Hidden files and directories (but keep frontend .env files needed for build)
+**/.*
+!autogpt_platform/frontend/.env
+!autogpt_platform/frontend/.env.default
+!autogpt_platform/frontend/.env.production
+
+# Python artifacts
+**/__pycache__/
+**/*.pyc
+**/*.pyo
+**/.venv/
+**/.ruff_cache/
+**/.pytest_cache/
+**/.coverage
+**/htmlcov/
+
+# Node artifacts
+**/node_modules/
+**/.next/
+**/storybook-static/
+**/playwright-report/
+**/test-results/
+
+# Build artifacts
+**/dist/
+**/build/
+!autogpt_platform/frontend/src/**/build/
+**/target/
+
+# Logs and temp files
+**/*.log
+**/*.tmp

.github/copilot-instructions.md

@@ -160,7 +160,7 @@ pnpm storybook                      # Start component development server
 
 **Backend Entry Points:**
 
-- `backend/backend/server/server.py` - FastAPI application setup
+- `backend/backend/api/rest_api.py` - FastAPI application setup
 - `backend/backend/data/` - Database models and user management
 - `backend/blocks/` - Agent execution blocks and logic
 
@@ -219,7 +219,7 @@ Agents are built using a visual block-based system where each block performs a s
 
 ### API Development
 
-1. Update routes in `/backend/backend/server/routers/`
+1. Update routes in `/backend/backend/api/features/`
 2. Add/update Pydantic models in same directory
 3. Write tests alongside route files
 4. For `data/*.py` changes, validate user ID checks
@@ -285,7 +285,7 @@ Agents are built using a visual block-based system where each block performs a s
 
 ### Security Guidelines
 
-**Cache Protection Middleware** (`/backend/backend/server/middleware/security.py`):
+**Cache Protection Middleware** (`/backend/backend/api/middleware/security.py`):
 
 - Default: Disables caching for ALL endpoints with `Cache-Control: no-store, no-cache, must-revalidate, private`
 - Uses allow list approach for cacheable paths (static assets, health checks, public pages)

.github/workflows/classic-frontend-ci.yml

@@ -49,7 +49,7 @@ jobs:
 
       - name: Create PR ${{ env.BUILD_BRANCH }} -> ${{ github.ref_name }}
         if: github.event_name == 'push'
-        uses: peter-evans/create-pull-request@v7
+        uses: peter-evans/create-pull-request@v8
         with:
           add-paths: classic/frontend/build/web
           base: ${{ github.ref_name }}

.github/workflows/claude-ci-failure-auto-fix.yml

@@ -22,7 +22,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           ref: ${{ github.event.workflow_run.head_branch }}
           fetch-depth: 0
@@ -40,9 +40,51 @@ jobs:
           git checkout -b "$BRANCH_NAME"
           echo "branch_name=$BRANCH_NAME" >> $GITHUB_OUTPUT
 
+      # Backend Python/Poetry setup (so Claude can run linting/tests)
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up Python dependency cache
+        uses: actions/cache@v5
+        with:
+          path: ~/.cache/pypoetry
+          key: poetry-${{ runner.os }}-${{ hashFiles('autogpt_platform/backend/poetry.lock') }}
+
+      - name: Install Poetry
+        run: |
+          cd autogpt_platform/backend
+          HEAD_POETRY_VERSION=$(python3 ../../.github/workflows/scripts/get_package_version_from_lockfile.py poetry)
+          curl -sSL https://install.python-poetry.org | POETRY_VERSION=$HEAD_POETRY_VERSION python3 -
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Install Python dependencies
+        working-directory: autogpt_platform/backend
+        run: poetry install
+
+      - name: Generate Prisma Client
+        working-directory: autogpt_platform/backend
+        run: poetry run prisma generate && poetry run gen-prisma-stub
+
+      # Frontend Node.js/pnpm setup (so Claude can run linting/tests)
+      - name: Enable corepack
+        run: corepack enable
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+          cache: "pnpm"
+          cache-dependency-path: autogpt_platform/frontend/pnpm-lock.yaml
+
+      - name: Install JavaScript dependencies
+        working-directory: autogpt_platform/frontend
+        run: pnpm install --frozen-lockfile
+
       - name: Get CI failure details
         id: failure_details
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             const run = await github.rest.actions.getWorkflowRun({

.github/workflows/claude-dependabot.yml

@@ -30,7 +30,7 @@ jobs:
       actions: read # Required for CI access
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 1
 
@@ -41,7 +41,7 @@ jobs:
           python-version: "3.11"  # Use standard version matching CI
 
       - name: Set up Python dependency cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ~/.cache/pypoetry
           key: poetry-${{ runner.os }}-${{ hashFiles('autogpt_platform/backend/poetry.lock') }}
@@ -77,27 +77,15 @@ jobs:
         run: poetry run prisma generate && poetry run gen-prisma-stub
 
       # Frontend Node.js/pnpm setup (mirrors platform-frontend-ci.yml)
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "22"
-
       - name: Enable corepack
         run: corepack enable
 
-      - name: Set pnpm store directory
-        run: |
-          pnpm config set store-dir ~/.pnpm-store
-          echo "PNPM_HOME=$HOME/.pnpm-store" >> $GITHUB_ENV
-
-      - name: Cache frontend dependencies
-        uses: actions/cache@v4
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
         with:
-          path: ~/.pnpm-store
-          key: ${{ runner.os }}-pnpm-${{ hashFiles('autogpt_platform/frontend/pnpm-lock.yaml', 'autogpt_platform/frontend/package.json') }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-${{ hashFiles('autogpt_platform/frontend/pnpm-lock.yaml') }}
-            ${{ runner.os }}-pnpm-
+          node-version: "22"
+          cache: "pnpm"
+          cache-dependency-path: autogpt_platform/frontend/pnpm-lock.yaml
 
       - name: Install JavaScript dependencies
         working-directory: autogpt_platform/frontend
@@ -124,7 +112,7 @@ jobs:
       # Phase 1: Cache and load Docker images for faster setup
       - name: Set up Docker image cache
         id: docker-cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ~/docker-cache
           # Use a versioned key for cache invalidation when image list changes
@@ -309,6 +297,7 @@ jobs:
         uses: anthropics/claude-code-action@v1
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          allowed_bots: "dependabot[bot]"
           claude_args: |
             --allowedTools "Bash(npm:*),Bash(pnpm:*),Bash(poetry:*),Bash(git:*),Edit,Replace,NotebookEditCell,mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*), Bash(gh pr diff:*), Bash(gh pr view:*)"
           prompt: |

.github/workflows/claude.yml

@@ -40,7 +40,7 @@ jobs:
       actions: read # Required for CI access
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 1
 
@@ -57,7 +57,7 @@ jobs:
           python-version: "3.11"  # Use standard version matching CI
 
       - name: Set up Python dependency cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ~/.cache/pypoetry
           key: poetry-${{ runner.os }}-${{ hashFiles('autogpt_platform/backend/poetry.lock') }}
@@ -93,27 +93,15 @@ jobs:
         run: poetry run prisma generate && poetry run gen-prisma-stub
 
       # Frontend Node.js/pnpm setup (mirrors platform-frontend-ci.yml)
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "22"
-
       - name: Enable corepack
         run: corepack enable
 
-      - name: Set pnpm store directory
-        run: |
-          pnpm config set store-dir ~/.pnpm-store
-          echo "PNPM_HOME=$HOME/.pnpm-store" >> $GITHUB_ENV
-
-      - name: Cache frontend dependencies
-        uses: actions/cache@v4
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
         with:
-          path: ~/.pnpm-store
-          key: ${{ runner.os }}-pnpm-${{ hashFiles('autogpt_platform/frontend/pnpm-lock.yaml', 'autogpt_platform/frontend/package.json') }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-${{ hashFiles('autogpt_platform/frontend/pnpm-lock.yaml') }}
-            ${{ runner.os }}-pnpm-
+          node-version: "22"
+          cache: "pnpm"
+          cache-dependency-path: autogpt_platform/frontend/pnpm-lock.yaml
 
       - name: Install JavaScript dependencies
         working-directory: autogpt_platform/frontend
@@ -140,7 +128,7 @@ jobs:
       # Phase 1: Cache and load Docker images for faster setup
       - name: Set up Docker image cache
         id: docker-cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ~/docker-cache
           # Use a versioned key for cache invalidation when image list changes

.github/workflows/codeql.yml

@@ -58,11 +58,11 @@ jobs:
         # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v3
+      uses: github/codeql-action/init@v4
       with:
         languages: ${{ matrix.language }}
         build-mode: ${{ matrix.build-mode }}
@@ -93,6 +93,6 @@ jobs:
         exit 1
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v3
+      uses: github/codeql-action/analyze@v4
       with:
         category: "/language:${{matrix.language}}"

.github/workflows/copilot-setup-steps.yml

@@ -27,7 +27,7 @@ jobs:
     # If you do not check out your code, Copilot will do this for you.
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
           submodules: true
@@ -39,7 +39,7 @@ jobs:
           python-version: "3.11"  # Use standard version matching CI
 
       - name: Set up Python dependency cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ~/.cache/pypoetry
           key: poetry-${{ runner.os }}-${{ hashFiles('autogpt_platform/backend/poetry.lock') }}
@@ -76,7 +76,7 @@ jobs:
 
       # Frontend Node.js/pnpm setup (mirrors platform-frontend-ci.yml)
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: "22"
 
@@ -89,7 +89,7 @@ jobs:
           echo "PNPM_HOME=$HOME/.pnpm-store" >> $GITHUB_ENV
 
       - name: Cache frontend dependencies
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ~/.pnpm-store
           key: ${{ runner.os }}-pnpm-${{ hashFiles('autogpt_platform/frontend/pnpm-lock.yaml', 'autogpt_platform/frontend/package.json') }}
@@ -132,7 +132,7 @@ jobs:
       # Phase 1: Cache and load Docker images for faster setup
       - name: Set up Docker image cache
         id: docker-cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ~/docker-cache
           # Use a versioned key for cache invalidation when image list changes

.github/workflows/docs-block-sync.yml

@@ -23,7 +23,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 1
 
@@ -33,7 +33,7 @@ jobs:
           python-version: "3.11"
 
       - name: Set up Python dependency cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ~/.cache/pypoetry
           key: poetry-${{ runner.os }}-${{ hashFiles('autogpt_platform/backend/poetry.lock') }}

.github/workflows/docs-claude-review.yml

@@ -7,6 +7,10 @@ on:
       - "docs/integrations/**"
       - "autogpt_platform/backend/backend/blocks/**"
 
+concurrency:
+  group: claude-docs-review-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
 jobs:
   claude-review:
     # Only run for PRs from members/collaborators
@@ -23,7 +27,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -33,7 +37,7 @@ jobs:
           python-version: "3.11"
 
       - name: Set up Python dependency cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ~/.cache/pypoetry
           key: poetry-${{ runner.os }}-${{ hashFiles('autogpt_platform/backend/poetry.lock') }}
@@ -91,5 +95,35 @@ jobs:
             3. Read corresponding documentation files to verify accuracy
             4. Provide your feedback as a PR comment
 
+            ## IMPORTANT: Comment Marker
+            Start your PR comment with exactly this HTML comment marker on its own line:
+            <!-- CLAUDE_DOCS_REVIEW -->
+
+            This marker is used to identify and replace your comment on subsequent runs.
+
             Be constructive and specific. If everything looks good, say so!
             If there are issues, explain what's wrong and suggest how to fix it.
+
+      - name: Delete old Claude review comments
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Get all comment IDs with our marker, sorted by creation date (oldest first)
+          COMMENT_IDS=$(gh api \
+            repos/${{ github.repository }}/issues/${{ github.event.pull_request.number }}/comments \
+            --jq '[.[] | select(.body | contains("<!-- CLAUDE_DOCS_REVIEW -->"))] | sort_by(.created_at) | .[].id')
+
+          # Count comments
+          COMMENT_COUNT=$(echo "$COMMENT_IDS" | grep -c . || true)
+
+          if [ "$COMMENT_COUNT" -gt 1 ]; then
+            # Delete all but the last (newest) comment
+            echo "$COMMENT_IDS" | head -n -1 | while read -r COMMENT_ID; do
+              if [ -n "$COMMENT_ID" ]; then
+                echo "Deleting old review comment: $COMMENT_ID"
+                gh api -X DELETE repos/${{ github.repository }}/issues/comments/$COMMENT_ID
+              fi
+            done
+          else
+            echo "No old review comments to clean up"
+          fi

.github/workflows/docs-enhance.yml

@@ -28,7 +28,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 1
 
@@ -38,7 +38,7 @@ jobs:
           python-version: "3.11"
 
       - name: Set up Python dependency cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ~/.cache/pypoetry
           key: poetry-${{ runner.os }}-${{ hashFiles('autogpt_platform/backend/poetry.lock') }}

.github/workflows/platform-autogpt-deploy-dev.yaml

@@ -25,7 +25,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           ref: ${{ github.event.inputs.git_ref || github.ref_name }}
 
@@ -52,7 +52,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Trigger deploy workflow
-        uses: peter-evans/repository-dispatch@v3
+        uses: peter-evans/repository-dispatch@v4
         with:
           token: ${{ secrets.DEPLOY_TOKEN }}
           repository: Significant-Gravitas/AutoGPT_cloud_infrastructure

.github/workflows/platform-autogpt-deploy-prod.yml

@@ -17,7 +17,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           ref: ${{ github.ref_name || 'master' }}
 
@@ -45,7 +45,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Trigger deploy workflow
-        uses: peter-evans/repository-dispatch@v3
+        uses: peter-evans/repository-dispatch@v4
         with:
           token: ${{ secrets.DEPLOY_TOKEN }}
           repository: Significant-Gravitas/AutoGPT_cloud_infrastructure

.github/workflows/platform-backend-ci.yml

@@ -41,13 +41,18 @@ jobs:
         ports:
           - 6379:6379
       rabbitmq:
-        image: rabbitmq:3.12-management
+        image: rabbitmq:4.1.4
         ports:
           - 5672:5672
-          - 15672:15672
         env:
           RABBITMQ_DEFAULT_USER: ${{ env.RABBITMQ_DEFAULT_USER }}
           RABBITMQ_DEFAULT_PASS: ${{ env.RABBITMQ_DEFAULT_PASS }}
+        options: >-
+          --health-cmd "rabbitmq-diagnostics -q ping"
+          --health-interval 30s
+          --health-timeout 10s
+          --health-retries 5
+          --health-start-period 10s
       clamav:
         image: clamav/clamav-debian:latest
         ports:
@@ -68,7 +73,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
           submodules: true
@@ -88,7 +93,7 @@ jobs:
         run: echo "date=$(date +'%Y-%m-%d')" >> $GITHUB_OUTPUT
 
       - name: Set up Python dependency cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ~/.cache/pypoetry
           key: poetry-${{ runner.os }}-${{ hashFiles('autogpt_platform/backend/poetry.lock') }}

.github/workflows/platform-dev-deploy-event-dispatcher.yml

@@ -17,7 +17,7 @@ jobs:
       - name: Check comment permissions and deployment status
         id: check_status
         if: github.event_name == 'issue_comment' && github.event.issue.pull_request
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             const commentBody = context.payload.comment.body.trim();
@@ -55,7 +55,7 @@ jobs:
 
       - name: Post permission denied comment
         if: steps.check_status.outputs.permission_denied == 'true'
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             await github.rest.issues.createComment({
@@ -68,7 +68,7 @@ jobs:
       - name: Get PR details for deployment
         id: pr_details
         if: steps.check_status.outputs.should_deploy == 'true' || steps.check_status.outputs.should_undeploy == 'true'
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             const pr = await github.rest.pulls.get({
@@ -82,7 +82,7 @@ jobs:
           
       - name: Dispatch Deploy Event
         if: steps.check_status.outputs.should_deploy == 'true'
-        uses: peter-evans/repository-dispatch@v3
+        uses: peter-evans/repository-dispatch@v4
         with:
           token: ${{ secrets.DISPATCH_TOKEN }}
           repository: Significant-Gravitas/AutoGPT_cloud_infrastructure
@@ -98,7 +98,7 @@ jobs:
 
       - name: Post deploy success comment
         if: steps.check_status.outputs.should_deploy == 'true'
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             await github.rest.issues.createComment({
@@ -110,7 +110,7 @@ jobs:
 
       - name: Dispatch Undeploy Event (from comment)
         if: steps.check_status.outputs.should_undeploy == 'true'
-        uses: peter-evans/repository-dispatch@v3
+        uses: peter-evans/repository-dispatch@v4
         with:
           token: ${{ secrets.DISPATCH_TOKEN }}
           repository: Significant-Gravitas/AutoGPT_cloud_infrastructure
@@ -126,7 +126,7 @@ jobs:
 
       - name: Post undeploy success comment
         if: steps.check_status.outputs.should_undeploy == 'true'
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             await github.rest.issues.createComment({
@@ -139,7 +139,7 @@ jobs:
       - name: Check deployment status on PR close
         id: check_pr_close
         if: github.event_name == 'pull_request' && github.event.action == 'closed'
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             const comments = await github.rest.issues.listComments({
@@ -168,7 +168,7 @@ jobs:
           github.event_name == 'pull_request' &&
           github.event.action == 'closed' &&
           steps.check_pr_close.outputs.should_undeploy == 'true'
-        uses: peter-evans/repository-dispatch@v3
+        uses: peter-evans/repository-dispatch@v4
         with:
           token: ${{ secrets.DISPATCH_TOKEN }}
           repository: Significant-Gravitas/AutoGPT_cloud_infrastructure
@@ -187,7 +187,7 @@ jobs:
           github.event_name == 'pull_request' &&
           github.event.action == 'closed' &&
           steps.check_pr_close.outputs.should_undeploy == 'true'
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             await github.rest.issues.createComment({

.github/workflows/platform-frontend-ci.yml

@@ -6,10 +6,16 @@ on:
     paths:
       - ".github/workflows/platform-frontend-ci.yml"
       - "autogpt_platform/frontend/**"
+      - "autogpt_platform/backend/Dockerfile"
+      - "autogpt_platform/docker-compose.yml"
+      - "autogpt_platform/docker-compose.platform.yml"
   pull_request:
     paths:
       - ".github/workflows/platform-frontend-ci.yml"
       - "autogpt_platform/frontend/**"
+      - "autogpt_platform/backend/Dockerfile"
+      - "autogpt_platform/docker-compose.yml"
+      - "autogpt_platform/docker-compose.platform.yml"
   merge_group:
   workflow_dispatch:
 
@@ -26,34 +32,31 @@ jobs:
   setup:
     runs-on: ubuntu-latest
     outputs:
-      cache-key: ${{ steps.cache-key.outputs.key }}
+      components-changed: ${{ steps.filter.outputs.components }}
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
+      - name: Check for component changes
+        uses: dorny/paths-filter@v3
+        id: filter
         with:
-          node-version: "22.18.0"
+          filters: |
+            components:
+              - 'autogpt_platform/frontend/src/components/**'
 
       - name: Enable corepack
         run: corepack enable
 
-      - name: Generate cache key
-        id: cache-key
-        run: echo "key=${{ runner.os }}-pnpm-${{ hashFiles('autogpt_platform/frontend/pnpm-lock.yaml', 'autogpt_platform/frontend/package.json') }}" >> $GITHUB_OUTPUT
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
+      - name: Set up Node
+        uses: actions/setup-node@v6
         with:
-          path: ~/.pnpm-store
-          key: ${{ steps.cache-key.outputs.key }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-${{ hashFiles('autogpt_platform/frontend/pnpm-lock.yaml') }}
-            ${{ runner.os }}-pnpm-
+          node-version: "22.18.0"
+          cache: "pnpm"
+          cache-dependency-path: autogpt_platform/frontend/pnpm-lock.yaml
 
-      - name: Install dependencies
+      - name: Install dependencies to populate cache
         run: pnpm install --frozen-lockfile
 
   lint:
@@ -62,24 +65,17 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "22.18.0"
+        uses: actions/checkout@v6
 
       - name: Enable corepack
         run: corepack enable
 
-      - name: Restore dependencies cache
-        uses: actions/cache@v4
+      - name: Set up Node
+        uses: actions/setup-node@v6
         with:
-          path: ~/.pnpm-store
-          key: ${{ needs.setup.outputs.cache-key }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-${{ hashFiles('autogpt_platform/frontend/pnpm-lock.yaml') }}
-            ${{ runner.os }}-pnpm-
+          node-version: "22.18.0"
+          cache: "pnpm"
+          cache-dependency-path: autogpt_platform/frontend/pnpm-lock.yaml
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
@@ -90,31 +86,27 @@ jobs:
   chromatic:
     runs-on: ubuntu-latest
     needs: setup
-    # Only run on dev branch pushes or PRs targeting dev
-    if: github.ref == 'refs/heads/dev' || github.base_ref == 'dev'
+    # Disabled: to re-enable, remove 'false &&' from the condition below
+    if: >-
+      false
+      && (github.ref == 'refs/heads/dev' || github.base_ref == 'dev')
+      && needs.setup.outputs.components-changed == 'true'
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "22.18.0"
-
       - name: Enable corepack
         run: corepack enable
 
-      - name: Restore dependencies cache
-        uses: actions/cache@v4
+      - name: Set up Node
+        uses: actions/setup-node@v6
         with:
-          path: ~/.pnpm-store
-          key: ${{ needs.setup.outputs.cache-key }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-${{ hashFiles('autogpt_platform/frontend/pnpm-lock.yaml') }}
-            ${{ runner.os }}-pnpm-
+          node-version: "22.18.0"
+          cache: "pnpm"
+          cache-dependency-path: autogpt_platform/frontend/pnpm-lock.yaml
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
@@ -129,30 +121,20 @@ jobs:
           exitOnceUploaded: true
 
   e2e_test:
+    name: end-to-end tests
     runs-on: big-boi
-    needs: setup
-    strategy:
-      fail-fast: false
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           submodules: recursive
 
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "22.18.0"
-
-      - name: Enable corepack
-        run: corepack enable
-
-      - name: Copy default supabase .env
+      - name: Set up Platform - Copy default supabase .env
         run: |
           cp ../.env.default ../.env
 
-      - name: Copy backend .env and set OpenAI API key
+      - name: Set up Platform - Copy backend .env and set OpenAI API key
         run: |
           cp ../backend/.env.default ../backend/.env
           echo "OPENAI_INTERNAL_API_KEY=${{ secrets.OPENAI_API_KEY }}" >> ../backend/.env
@@ -160,77 +142,125 @@ jobs:
           # Used by E2E test data script to generate embeddings for approved store agents
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
 
-      - name: Set up Docker Buildx
+      - name: Set up Platform - Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
-
-      - name: Cache Docker layers
-        uses: actions/cache@v4
         with:
-          path: /tmp/.buildx-cache
-          key: ${{ runner.os }}-buildx-frontend-test-${{ hashFiles('autogpt_platform/docker-compose.yml', 'autogpt_platform/backend/Dockerfile', 'autogpt_platform/backend/pyproject.toml', 'autogpt_platform/backend/poetry.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-buildx-frontend-test-
+          driver: docker-container
+          driver-opts: network=host
 
-      - name: Run docker compose
+      - name: Set up Platform - Expose GHA cache to docker buildx CLI
+        uses: crazy-max/ghaction-github-runtime@v3
+
+      - name: Set up Platform - Build Docker images (with cache)
+        working-directory: autogpt_platform
         run: |
-          NEXT_PUBLIC_PW_TEST=true docker compose -f ../docker-compose.yml up -d
+          pip install pyyaml
+
+          # Resolve extends and generate a flat compose file that bake can understand
+          docker compose -f docker-compose.yml config > docker-compose.resolved.yml
+
+          # Add cache configuration to the resolved compose file
+          python ../.github/workflows/scripts/docker-ci-fix-compose-build-cache.py \
+            --source docker-compose.resolved.yml \
+            --cache-from "type=gha" \
+            --cache-to "type=gha,mode=max" \
+            --backend-hash "${{ hashFiles('autogpt_platform/backend/Dockerfile', 'autogpt_platform/backend/poetry.lock', 'autogpt_platform/backend/backend') }}" \
+            --frontend-hash "${{ hashFiles('autogpt_platform/frontend/Dockerfile', 'autogpt_platform/frontend/pnpm-lock.yaml', 'autogpt_platform/frontend/src') }}" \
+            --git-ref "${{ github.ref }}"
+
+          # Build with bake using the resolved compose file (now includes cache config)
+          docker buildx bake --allow=fs.read=.. -f docker-compose.resolved.yml --load
         env:
-          DOCKER_BUILDKIT: 1
-          BUILDX_CACHE_FROM: type=local,src=/tmp/.buildx-cache
-          BUILDX_CACHE_TO: type=local,dest=/tmp/.buildx-cache-new,mode=max
+          NEXT_PUBLIC_PW_TEST: true
 
-      - name: Move cache
-        run: |
-          rm -rf /tmp/.buildx-cache
-          if [ -d "/tmp/.buildx-cache-new" ]; then
-            mv /tmp/.buildx-cache-new /tmp/.buildx-cache
-          fi
+      - name: Set up tests - Cache E2E test data
+        id: e2e-data-cache
+        uses: actions/cache@v5
+        with:
+          path: /tmp/e2e_test_data.sql
+          key: e2e-test-data-${{ hashFiles('autogpt_platform/backend/test/e2e_test_data.py', 'autogpt_platform/backend/migrations/**', '.github/workflows/platform-frontend-ci.yml') }}
 
-      - name: Wait for services to be ready
+      - name: Set up Platform - Start Supabase DB + Auth
         run: |
+          docker compose -f ../docker-compose.resolved.yml up -d db auth --no-build
+          echo "Waiting for database to be ready..."
+          timeout 60 sh -c 'until docker compose -f ../docker-compose.resolved.yml exec -T db pg_isready -U postgres 2>/dev/null; do sleep 2; done'
+          echo "Waiting for auth service to be ready..."
+          timeout 60 sh -c 'until docker compose -f ../docker-compose.resolved.yml exec -T db psql -U postgres -d postgres -c "SELECT 1 FROM auth.users LIMIT 1" 2>/dev/null; do sleep 2; done' || echo "Auth schema check timeout, continuing..."
+
+      - name: Set up Platform - Run migrations
+        run: |
+          echo "Running migrations..."
+          docker compose -f ../docker-compose.resolved.yml run --rm migrate
+          echo "✅ Migrations completed"
+        env:
+          NEXT_PUBLIC_PW_TEST: true
+
+      - name: Set up tests - Load cached E2E test data
+        if: steps.e2e-data-cache.outputs.cache-hit == 'true'
+        run: |
+          echo "✅ Found cached E2E test data, restoring..."
+          {
+            echo "SET session_replication_role = 'replica';"
+            cat /tmp/e2e_test_data.sql
+            echo "SET session_replication_role = 'origin';"
+          } | docker compose -f ../docker-compose.resolved.yml exec -T db psql -U postgres -d postgres -b
+          # Refresh materialized views after restore
+          docker compose -f ../docker-compose.resolved.yml exec -T db \
+            psql -U postgres -d postgres -b -c "SET search_path TO platform; SELECT refresh_store_materialized_views();" || true
+
+          echo "✅ E2E test data restored from cache"
+
+      - name: Set up Platform - Start (all other services)
+        run: |
+          docker compose -f ../docker-compose.resolved.yml up -d --no-build
           echo "Waiting for rest_server to be ready..."
           timeout 60 sh -c 'until curl -f http://localhost:8006/health 2>/dev/null; do sleep 2; done' || echo "Rest server health check timeout, continuing..."
-          echo "Waiting for database to be ready..."
-          timeout 60 sh -c 'until docker compose -f ../docker-compose.yml exec -T db pg_isready -U postgres 2>/dev/null; do sleep 2; done' || echo "Database ready check timeout, continuing..."
+        env:
+          NEXT_PUBLIC_PW_TEST: true
 
-      - name: Create E2E test data
+      - name: Set up tests - Create E2E test data
+        if: steps.e2e-data-cache.outputs.cache-hit != 'true'
         run: |
           echo "Creating E2E test data..."
-          # First try to run the script from inside the container
-          if docker compose -f ../docker-compose.yml exec -T rest_server test -f /app/autogpt_platform/backend/test/e2e_test_data.py; then
-            echo "✅ Found e2e_test_data.py in container, running it..."
-            docker compose -f ../docker-compose.yml exec -T rest_server sh -c "cd /app/autogpt_platform && python backend/test/e2e_test_data.py" || {
-              echo "❌ E2E test data creation failed!"
-              docker compose -f ../docker-compose.yml logs --tail=50 rest_server
-              exit 1
-            }
-          else
-            echo "⚠️ e2e_test_data.py not found in container, copying and running..."
-            # Copy the script into the container and run it
-            docker cp ../backend/test/e2e_test_data.py $(docker compose -f ../docker-compose.yml ps -q rest_server):/tmp/e2e_test_data.py || {
-              echo "❌ Failed to copy script to container"
-              exit 1
-            }
-            docker compose -f ../docker-compose.yml exec -T rest_server sh -c "cd /app/autogpt_platform && python /tmp/e2e_test_data.py" || {
-              echo "❌ E2E test data creation failed!"
-              docker compose -f ../docker-compose.yml logs --tail=50 rest_server
-              exit 1
-            }
-          fi
+          docker cp ../backend/test/e2e_test_data.py $(docker compose -f ../docker-compose.resolved.yml ps -q rest_server):/tmp/e2e_test_data.py
+          docker compose -f ../docker-compose.resolved.yml exec -T rest_server sh -c "cd /app/autogpt_platform && python /tmp/e2e_test_data.py" || {
+            echo "❌ E2E test data creation failed!"
+            docker compose -f ../docker-compose.resolved.yml logs --tail=50 rest_server
+            exit 1
+          }
 
-      - name: Restore dependencies cache
-        uses: actions/cache@v4
+          # Dump auth.users + platform schema for cache (two separate dumps)
+          echo "Dumping database for cache..."
+          {
+            docker compose -f ../docker-compose.resolved.yml exec -T db \
+              pg_dump -U postgres --data-only --column-inserts \
+              --table='auth.users' postgres
+            docker compose -f ../docker-compose.resolved.yml exec -T db \
+              pg_dump -U postgres --data-only --column-inserts \
+              --schema=platform \
+              --exclude-table='platform._prisma_migrations' \
+              --exclude-table='platform.apscheduler_jobs' \
+              --exclude-table='platform.apscheduler_jobs_batched_notifications' \
+              postgres
+          } > /tmp/e2e_test_data.sql
+
+          echo "✅ Database dump created for caching ($(wc -l < /tmp/e2e_test_data.sql) lines)"
+
+      - name: Set up tests - Enable corepack
+        run: corepack enable
+
+      - name: Set up tests - Set up Node
+        uses: actions/setup-node@v6
         with:
-          path: ~/.pnpm-store
-          key: ${{ needs.setup.outputs.cache-key }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-${{ hashFiles('autogpt_platform/frontend/pnpm-lock.yaml') }}
-            ${{ runner.os }}-pnpm-
+          node-version: "22.18.0"
+          cache: "pnpm"
+          cache-dependency-path: autogpt_platform/frontend/pnpm-lock.yaml
 
-      - name: Install dependencies
+      - name: Set up tests - Install dependencies
         run: pnpm install --frozen-lockfile
 
-      - name: Install Browser 'chromium'
+      - name: Set up tests - Install browser 'chromium'
         run: pnpm playwright install --with-deps chromium
 
       - name: Run Playwright tests
@@ -257,7 +287,7 @@ jobs:
 
       - name: Print Final Docker Compose logs
         if: always()
-        run: docker compose -f ../docker-compose.yml logs
+        run: docker compose -f ../docker-compose.resolved.yml logs
 
   integration_test:
     runs-on: ubuntu-latest
@@ -265,26 +295,19 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           submodules: recursive
 
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "22.18.0"
-
       - name: Enable corepack
         run: corepack enable
 
-      - name: Restore dependencies cache
-        uses: actions/cache@v4
+      - name: Set up Node
+        uses: actions/setup-node@v6
         with:
-          path: ~/.pnpm-store
-          key: ${{ needs.setup.outputs.cache-key }}
-          restore-keys: |
-            ${{ runner.os }}-pnpm-${{ hashFiles('autogpt_platform/frontend/pnpm-lock.yaml') }}
-            ${{ runner.os }}-pnpm-
+          node-version: "22.18.0"
+          cache: "pnpm"
+          cache-dependency-path: autogpt_platform/frontend/pnpm-lock.yaml
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile

.github/workflows/platform-fullstack-ci.yml

@@ -29,10 +29,10 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: "22.18.0"
 
@@ -44,7 +44,7 @@ jobs:
         run: echo "key=${{ runner.os }}-pnpm-${{ hashFiles('autogpt_platform/frontend/pnpm-lock.yaml', 'autogpt_platform/frontend/package.json') }}" >> $GITHUB_OUTPUT
 
       - name: Cache dependencies
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ~/.pnpm-store
           key: ${{ steps.cache-key.outputs.key }}
@@ -56,19 +56,19 @@ jobs:
         run: pnpm install --frozen-lockfile
 
   types:
-    runs-on: ubuntu-latest
+    runs-on: big-boi
     needs: setup
     strategy:
       fail-fast: false
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           submodules: recursive
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: "22.18.0"
 
@@ -85,10 +85,10 @@ jobs:
 
       - name: Run docker compose
         run: |
-          docker compose -f ../docker-compose.yml --profile local --profile deps_backend up -d
+          docker compose -f ../docker-compose.yml --profile local up -d deps_backend
 
       - name: Restore dependencies cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
         with:
           path: ~/.pnpm-store
           key: ${{ needs.setup.outputs.cache-key }}

.github/workflows/pr-overlap-check.yml

@@ -0,0 +1,39 @@
+name: PR Overlap Detection
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches:
+      - dev
+      - master
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  check-overlaps:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Need full history for merge testing
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Configure git
+        run: |
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git config user.name "github-actions[bot]"
+
+      - name: Run overlap detection
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        # Always succeed - this check informs contributors, it shouldn't block merging
+        continue-on-error: true
+        run: |
+          python .github/scripts/detect_overlaps.py ${{ github.event.pull_request.number }}

.github/workflows/repo-workflow-checker.yml

@@ -11,7 +11,7 @@ jobs:
     steps:
       # - name: Wait some time for all actions to start
       #   run: sleep 30
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         # with:
           # fetch-depth: 0
       - name: Set up Python

.github/workflows/scripts/docker-ci-fix-compose-build-cache.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""
+Add cache configuration to a resolved docker-compose file for all services
+that have a build key, and ensure image names match what docker compose expects.
+"""
+
+import argparse
+
+import yaml
+
+
+DEFAULT_BRANCH = "dev"
+CACHE_BUILDS_FOR_COMPONENTS = ["backend", "frontend"]
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Add cache config to a resolved compose file"
+    )
+    parser.add_argument(
+        "--source",
+        required=True,
+        help="Source compose file to read (should be output of `docker compose config`)",
+    )
+    parser.add_argument(
+        "--cache-from",
+        default="type=gha",
+        help="Cache source configuration",
+    )
+    parser.add_argument(
+        "--cache-to",
+        default="type=gha,mode=max",
+        help="Cache destination configuration",
+    )
+    for component in CACHE_BUILDS_FOR_COMPONENTS:
+        parser.add_argument(
+            f"--{component}-hash",
+            default="",
+            help=f"Hash for {component} cache scope (e.g., from hashFiles())",
+        )
+    parser.add_argument(
+        "--git-ref",
+        default="",
+        help="Git ref for branch-based cache scope (e.g., refs/heads/master)",
+    )
+    args = parser.parse_args()
+
+    # Normalize git ref to a safe scope name (e.g., refs/heads/master -> master)
+    git_ref_scope = ""
+    if args.git_ref:
+        git_ref_scope = args.git_ref.replace("refs/heads/", "").replace("/", "-")
+
+    with open(args.source, "r") as f:
+        compose = yaml.safe_load(f)
+
+    # Get project name from compose file or default
+    project_name = compose.get("name", "autogpt_platform")
+
+    def get_image_name(dockerfile: str, target: str) -> str:
+        """Generate image name based on Dockerfile folder and build target."""
+        dockerfile_parts = dockerfile.replace("\\", "/").split("/")
+        if len(dockerfile_parts) >= 2:
+            folder_name = dockerfile_parts[-2]  # e.g., "backend" or "frontend"
+        else:
+            folder_name = "app"
+        return f"{project_name}-{folder_name}:{target}"
+
+    def get_build_key(dockerfile: str, target: str) -> str:
+        """Generate a unique key for a Dockerfile+target combination."""
+        return f"{dockerfile}:{target}"
+
+    def get_component(dockerfile: str) -> str | None:
+        """Get component name (frontend/backend) from dockerfile path."""
+        for component in CACHE_BUILDS_FOR_COMPONENTS:
+            if component in dockerfile:
+                return component
+        return None
+
+    # First pass: collect all services with build configs and identify duplicates
+    # Track which (dockerfile, target) combinations we've seen
+    build_key_to_first_service: dict[str, str] = {}
+    services_to_build: list[str] = []
+    services_to_dedupe: list[str] = []
+
+    for service_name, service_config in compose.get("services", {}).items():
+        if "build" not in service_config:
+            continue
+
+        build_config = service_config["build"]
+        dockerfile = build_config.get("dockerfile", "Dockerfile")
+        target = build_config.get("target", "default")
+        build_key = get_build_key(dockerfile, target)
+
+        if build_key not in build_key_to_first_service:
+            # First service with this build config - it will do the actual build
+            build_key_to_first_service[build_key] = service_name
+            services_to_build.append(service_name)
+        else:
+            # Duplicate - will just use the image from the first service
+            services_to_dedupe.append(service_name)
+
+    # Second pass: configure builds and deduplicate
+    modified_services = []
+    for service_name, service_config in compose.get("services", {}).items():
+        if "build" not in service_config:
+            continue
+
+        build_config = service_config["build"]
+        dockerfile = build_config.get("dockerfile", "Dockerfile")
+        target = build_config.get("target", "latest")
+        image_name = get_image_name(dockerfile, target)
+
+        # Set image name for all services (needed for both builders and deduped)
+        service_config["image"] = image_name
+
+        if service_name in services_to_dedupe:
+            # Remove build config - this service will use the pre-built image
+            del service_config["build"]
+            continue
+
+        # This service will do the actual build - add cache config
+        cache_from_list = []
+        cache_to_list = []
+
+        component = get_component(dockerfile)
+        if not component:
+            # Skip services that don't clearly match frontend/backend
+            continue
+
+        # Get the hash for this component
+        component_hash = getattr(args, f"{component}_hash")
+
+        # Scope format: platform-{component}-{target}-{hash|ref}
+        # Example: platform-backend-server-abc123
+
+        if "type=gha" in args.cache_from:
+            # 1. Primary: exact hash match (most specific)
+            if component_hash:
+                hash_scope = f"platform-{component}-{target}-{component_hash}"
+                cache_from_list.append(f"{args.cache_from},scope={hash_scope}")
+
+            # 2. Fallback: branch-based cache
+            if git_ref_scope:
+                ref_scope = f"platform-{component}-{target}-{git_ref_scope}"
+                cache_from_list.append(f"{args.cache_from},scope={ref_scope}")
+
+            # 3. Fallback: dev branch cache (for PRs/feature branches)
+            if git_ref_scope and git_ref_scope != DEFAULT_BRANCH:
+                master_scope = f"platform-{component}-{target}-{DEFAULT_BRANCH}"
+                cache_from_list.append(f"{args.cache_from},scope={master_scope}")
+
+        if "type=gha" in args.cache_to:
+            # Write to both hash-based and branch-based scopes
+            if component_hash:
+                hash_scope = f"platform-{component}-{target}-{component_hash}"
+                cache_to_list.append(f"{args.cache_to},scope={hash_scope}")
+
+            if git_ref_scope:
+                ref_scope = f"platform-{component}-{target}-{git_ref_scope}"
+                cache_to_list.append(f"{args.cache_to},scope={ref_scope}")
+
+        # Ensure we have at least one cache source/target
+        if not cache_from_list:
+            cache_from_list.append(args.cache_from)
+        if not cache_to_list:
+            cache_to_list.append(args.cache_to)
+
+        build_config["cache_from"] = cache_from_list
+        build_config["cache_to"] = cache_to_list
+        modified_services.append(service_name)
+
+    # Write back to the same file
+    with open(args.source, "w") as f:
+        yaml.dump(compose, f, default_flow_style=False, sort_keys=False)
+
+    print(f"Added cache config to {len(modified_services)} services in {args.source}:")
+    for svc in modified_services:
+        svc_config = compose["services"][svc]
+        build_cfg = svc_config.get("build", {})
+        cache_from_list = build_cfg.get("cache_from", ["none"])
+        cache_to_list = build_cfg.get("cache_to", ["none"])
+        print(f"  - {svc}")
+        print(f"      image: {svc_config.get('image', 'N/A')}")
+        print(f"      cache_from: {cache_from_list}")
+        print(f"      cache_to: {cache_to_list}")
+    if services_to_dedupe:
+        print(
+            f"Deduplicated {len(services_to_dedupe)} services (will use pre-built images):"
+        )
+        for svc in services_to_dedupe:
+            print(f"  - {svc} -> {compose['services'][svc].get('image', 'N/A')}")
+
+
+if __name__ == "__main__":
+    main()

.gitignore

@@ -178,5 +178,6 @@ autogpt_platform/backend/settings.py
 *.ign.*
 .test-contents
 .claude/settings.local.json
+CLAUDE.local.md
 /autogpt_platform/backend/logs
 .next

AGENTS.md

@@ -16,7 +16,6 @@ See `docs/content/platform/getting-started.md` for setup instructions.
 - Format Python code with `poetry run format`.
 - Format frontend code using `pnpm format`.
 
-
 ## Frontend guidelines:
 
 See `/frontend/CONTRIBUTING.md` for complete patterns. Quick reference:
@@ -33,14 +32,17 @@ See `/frontend/CONTRIBUTING.md` for complete patterns. Quick reference:
 4. **Styling**: Tailwind CSS only, use design tokens, Phosphor Icons only
 5. **Testing**: Add Storybook stories for new components, Playwright for E2E
 6. **Code conventions**: Function declarations (not arrow functions) for components/handlers
+
 - Component props should be `interface Props { ... }` (not exported) unless the interface needs to be used outside the component
 - Separate render logic from business logic (component.tsx + useComponent.ts + helpers.ts)
 - Colocate state when possible and avoid creating large components, use sub-components ( local `/components` folder next to the parent component ) when sensible
 - Avoid large hooks, abstract logic into `helpers.ts` files when sensible
 - Use function declarations for components, arrow functions only for callbacks
 - No barrel files or `index.ts` re-exports
-- Do not use `useCallback` or `useMemo` unless strictly needed
 - Avoid comments at all times unless the code is very complex
+- Do not use `useCallback` or `useMemo` unless asked to optimise a given function
+- Do not type hook returns, let Typescript infer as much as possible
+- Never type with `any`, if not types available use `unknown`
 
 ## Testing
 
@@ -49,22 +51,8 @@ See `/frontend/CONTRIBUTING.md` for complete patterns. Quick reference:
 
 Always run the relevant linters and tests before committing.
 Use conventional commit messages for all commits (e.g. `feat(backend): add API`).
-  Types:
-    - feat
-    - fix
-    - refactor
-    - ci
-    - dx (developer experience)
-  Scopes:
-    - platform
-      - platform/library
-      - platform/marketplace
-      - backend
-        - backend/executor
-      - frontend
-        - frontend/library
-        - frontend/marketplace
-      - blocks
+Types: - feat - fix - refactor - ci - dx (developer experience)
+Scopes: - platform - platform/library - platform/marketplace - backend - backend/executor - frontend - frontend/library - frontend/marketplace - blocks
 
 ## Pull requests
 

README.md

@@ -54,7 +54,7 @@ Before proceeding with the installation, ensure your system meets the following
 ### Updated Setup Instructions:
 We've moved to a fully maintained and regularly updated documentation site.
 
-👉 [Follow the official self-hosting guide here](https://docs.agpt.co/platform/getting-started/)
+👉 [Follow the official self-hosting guide here](https://agpt.co/docs/platform/getting-started/getting-started)
 
 
 This tutorial assumes you have Docker, VSCode, git and npm installed.

autogpt_platform/CLAUDE.md

@@ -6,152 +6,30 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 AutoGPT Platform is a monorepo containing:
 
-- **Backend** (`/backend`): Python FastAPI server with async support
-- **Frontend** (`/frontend`): Next.js React application
-- **Shared Libraries** (`/autogpt_libs`): Common Python utilities
+- **Backend** (`backend`): Python FastAPI server with async support
+- **Frontend** (`frontend`): Next.js React application
+- **Shared Libraries** (`autogpt_libs`): Common Python utilities
 
-## Essential Commands
+## Component Documentation
 
-### Backend Development
+- **Backend**: See @backend/CLAUDE.md for backend-specific commands, architecture, and development tasks
+- **Frontend**: See @frontend/CLAUDE.md for frontend-specific commands, architecture, and development patterns
 
-```bash
-# Install dependencies
-cd backend && poetry install
-
-# Run database migrations
-poetry run prisma migrate dev
-
-# Start all services (database, redis, rabbitmq, clamav)
-docker compose up -d
-
-# Run the backend server
-poetry run serve
-
-# Run tests
-poetry run test
-
-# Run specific test
-poetry run pytest path/to/test_file.py::test_function_name
-
-# Run block tests (tests that validate all blocks work correctly)
-poetry run pytest backend/blocks/test/test_block.py -xvs
-
-# Run tests for a specific block (e.g., GetCurrentTimeBlock)
-poetry run pytest 'backend/blocks/test/test_block.py::test_available_blocks[GetCurrentTimeBlock]' -xvs
-
-# Lint and format
-# prefer format if you want to just "fix" it and only get the errors that can't be autofixed
-poetry run format  # Black + isort
-poetry run lint    # ruff
-```
-
-More details can be found in TESTING.md
-
-#### Creating/Updating Snapshots
-
-When you first write a test or when the expected output changes:
-
-```bash
-poetry run pytest path/to/test.py --snapshot-update
-```
-
-⚠️ **Important**: Always review snapshot changes before committing! Use `git diff` to verify the changes are expected.
-
-### Frontend Development
-
-```bash
-# Install dependencies
-cd frontend && pnpm i
-
-# Generate API client from OpenAPI spec
-pnpm generate:api
-
-# Start development server
-pnpm dev
-
-# Run E2E tests
-pnpm test
-
-# Run Storybook for component development
-pnpm storybook
-
-# Build production
-pnpm build
-
-# Format and lint
-pnpm format
-
-# Type checking
-pnpm types
-```
-
-**📖 Complete Guide**: See `/frontend/CONTRIBUTING.md` and `/frontend/.cursorrules` for comprehensive frontend patterns.
-
-**Key Frontend Conventions:**
-
-- Separate render logic from data/behavior in components
-- Use generated API hooks from `@/app/api/__generated__/endpoints/`
-- Use function declarations (not arrow functions) for components/handlers
-- Use design system components from `src/components/` (atoms, molecules, organisms)
-- Only use Phosphor Icons
-- Never use `src/components/__legacy__/*` or deprecated `BackendAPI`
-
-## Architecture Overview
-
-### Backend Architecture
-
-- **API Layer**: FastAPI with REST and WebSocket endpoints
-- **Database**: PostgreSQL with Prisma ORM, includes pgvector for embeddings
-- **Queue System**: RabbitMQ for async task processing
-- **Execution Engine**: Separate executor service processes agent workflows
-- **Authentication**: JWT-based with Supabase integration
-- **Security**: Cache protection middleware prevents sensitive data caching in browsers/proxies
-
-### Frontend Architecture
-
-- **Framework**: Next.js 15 App Router (client-first approach)
-- **Data Fetching**: Type-safe generated API hooks via Orval + React Query
-- **State Management**: React Query for server state, co-located UI state in components/hooks
-- **Component Structure**: Separate render logic (`.tsx`) from business logic (`use*.ts` hooks)
-- **Workflow Builder**: Visual graph editor using @xyflow/react
-- **UI Components**: shadcn/ui (Radix UI primitives) with Tailwind CSS styling
-- **Icons**: Phosphor Icons only
-- **Feature Flags**: LaunchDarkly integration
-- **Error Handling**: ErrorCard for render errors, toast for mutations, Sentry for exceptions
-- **Testing**: Playwright for E2E, Storybook for component development
-
-### Key Concepts
+## Key Concepts
 
 1. **Agent Graphs**: Workflow definitions stored as JSON, executed by the backend
-2. **Blocks**: Reusable components in `/backend/blocks/` that perform specific tasks
+2. **Blocks**: Reusable components in `backend/backend/blocks/` that perform specific tasks
 3. **Integrations**: OAuth and API connections stored per user
 4. **Store**: Marketplace for sharing agent templates
 5. **Virus Scanning**: ClamAV integration for file upload security
 
-### Testing Approach
-
-- Backend uses pytest with snapshot testing for API responses
-- Test files are colocated with source files (`*_test.py`)
-- Frontend uses Playwright for E2E tests
-- Component testing via Storybook
-
-### Database Schema
-
-Key models (defined in `/backend/schema.prisma`):
-
-- `User`: Authentication and profile data
-- `AgentGraph`: Workflow definitions with version control
-- `AgentGraphExecution`: Execution history and results
-- `AgentNode`: Individual nodes in a workflow
-- `StoreListing`: Marketplace listings for sharing agents
-
 ### Environment Configuration
 
 #### Configuration Files
 
-- **Backend**: `/backend/.env.default` (defaults) → `/backend/.env` (user overrides)
-- **Frontend**: `/frontend/.env.default` (defaults) → `/frontend/.env` (user overrides)
-- **Platform**: `/.env.default` (Supabase/shared defaults) → `/.env` (user overrides)
+- **Backend**: `backend/.env.default` (defaults) → `backend/.env` (user overrides)
+- **Frontend**: `frontend/.env.default` (defaults) → `frontend/.env` (user overrides)
+- **Platform**: `.env.default` (Supabase/shared defaults) → `.env` (user overrides)
 
 #### Docker Environment Loading Order
 
@@ -167,83 +45,17 @@ Key models (defined in `/backend/schema.prisma`):
 - Backend/Frontend services use YAML anchors for consistent configuration
 - Supabase services (`db/docker/docker-compose.yml`) follow the same pattern
 
-### Common Development Tasks
+### Branching Strategy
 
-**Adding a new block:**
-
-Follow the comprehensive [Block SDK Guide](../../../docs/content/platform/block-sdk-guide.md) which covers:
-
-- Provider configuration with `ProviderBuilder`
-- Block schema definition
-- Authentication (API keys, OAuth, webhooks)
-- Testing and validation
-- File organization
-
-Quick steps:
-
-1. Create new file in `/backend/backend/blocks/`
-2. Configure provider using `ProviderBuilder` in `_config.py`
-3. Inherit from `Block` base class
-4. Define input/output schemas using `BlockSchema`
-5. Implement async `run` method
-6. Generate unique block ID using `uuid.uuid4()`
-7. Test with `poetry run pytest backend/blocks/test/test_block.py`
-
-Note: when making many new blocks analyze the interfaces for each of these blocks and picture if they would go well together in a graph based editor or would they struggle to connect productively?
-ex: do the inputs and outputs tie well together?
-
-If you get any pushback or hit complex block conditions check the new_blocks guide in the docs.
-
-**Modifying the API:**
-
-1. Update route in `/backend/backend/server/routers/`
-2. Add/update Pydantic models in same directory
-3. Write tests alongside the route file
-4. Run `poetry run test` to verify
-
-### Frontend guidelines:
-
-See `/frontend/CONTRIBUTING.md` for complete patterns. Quick reference:
-
-1. **Pages**: Create in `src/app/(platform)/feature-name/page.tsx`
-   - Add `usePageName.ts` hook for logic
-   - Put sub-components in local `components/` folder
-2. **Components**: Structure as `ComponentName/ComponentName.tsx` + `useComponentName.ts` + `helpers.ts`
-   - Use design system components from `src/components/` (atoms, molecules, organisms)
-   - Never use `src/components/__legacy__/*`
-3. **Data fetching**: Use generated API hooks from `@/app/api/__generated__/endpoints/`
-   - Regenerate with `pnpm generate:api`
-   - Pattern: `use{Method}{Version}{OperationName}`
-4. **Styling**: Tailwind CSS only, use design tokens, Phosphor Icons only
-5. **Testing**: Add Storybook stories for new components, Playwright for E2E
-6. **Code conventions**: Function declarations (not arrow functions) for components/handlers
-- Component props should be `interface Props { ... }` (not exported) unless the interface needs to be used outside the component
-- Separate render logic from business logic (component.tsx + useComponent.ts + helpers.ts)
-- Colocate state when possible and avoid creating large components, use sub-components ( local `/components` folder next to the parent component ) when sensible
-- Avoid large hooks, abstract logic into `helpers.ts` files when sensible
-- Use function declarations for components, arrow functions only for callbacks
-- No barrel files or `index.ts` re-exports
-- Do not use `useCallback` or `useMemo` unless strictly needed
-- Avoid comments at all times unless the code is very complex
-
-### Security Implementation
-
-**Cache Protection Middleware:**
-
-- Located in `/backend/backend/server/middleware/security.py`
-- Default behavior: Disables caching for ALL endpoints with `Cache-Control: no-store, no-cache, must-revalidate, private`
-- Uses an allow list approach - only explicitly permitted paths can be cached
-- Cacheable paths include: static assets (`/static/*`, `/_next/static/*`), health checks, public store pages, documentation
-- Prevents sensitive data (auth tokens, API keys, user data) from being cached by browsers/proxies
-- To allow caching for a new endpoint, add it to `CACHEABLE_PATHS` in the middleware
-- Applied to both main API server and external API applications
+- **`dev`** is the main development branch. All PRs should target `dev`.
+- **`master`** is the production branch. Only used for production releases.
 
 ### Creating Pull Requests
 
-- Create the PR aginst the `dev` branch of the repository.
-- Ensure the branch name is descriptive (e.g., `feature/add-new-block`)/
-- Use conventional commit messages (see below)/
-- Fill out the .github/PULL_REQUEST_TEMPLATE.md template as the PR description/
+- Create the PR against the `dev` branch of the repository.
+- Ensure the branch name is descriptive (e.g., `feature/add-new-block`)
+- Use conventional commit messages (see below)
+- Fill out the .github/PULL_REQUEST_TEMPLATE.md template as the PR description
 - Run the github pre-commit hooks to ensure code quality.
 
 ### Reviewing/Revising Pull Requests

autogpt_platform/autogpt_libs/pyproject.toml

@@ -9,25 +9,25 @@ packages = [{ include = "autogpt_libs" }]
 [tool.poetry.dependencies]
 python = ">=3.10,<4.0"
 colorama = "^0.4.6"
-cryptography = "^45.0"
+cryptography = "^46.0"
 expiringdict = "^1.2.2"
-fastapi = "^0.116.1"
-google-cloud-logging = "^3.12.1"
-launchdarkly-server-sdk = "^9.12.0"
-pydantic = "^2.11.7"
-pydantic-settings = "^2.10.1"
-pyjwt = { version = "^2.10.1", extras = ["crypto"] }
+fastapi = "^0.128.7"
+google-cloud-logging = "^3.13.0"
+launchdarkly-server-sdk = "^9.15.0"
+pydantic = "^2.12.5"
+pydantic-settings = "^2.12.0"
+pyjwt = { version = "^2.11.0", extras = ["crypto"] }
 redis = "^6.2.0"
-supabase = "^2.16.0"
-uvicorn = "^0.35.0"
+supabase = "^2.28.0"
+uvicorn = "^0.40.0"
 
 [tool.poetry.group.dev.dependencies]
-pyright = "^1.1.404"
+pyright = "^1.1.408"
 pytest = "^8.4.1"
-pytest-asyncio = "^1.1.0"
-pytest-mock = "^3.14.1"
-pytest-cov = "^6.2.1"
-ruff = "^0.12.11"
+pytest-asyncio = "^1.3.0"
+pytest-mock = "^3.15.1"
+pytest-cov = "^7.0.0"
+ruff = "^0.15.0"
 
 [build-system]
 requires = ["poetry-core"]

autogpt_platform/backend/.env.default

@@ -104,6 +104,12 @@ TWITTER_CLIENT_SECRET=
 # Make a new workspace for your OAuth APP -- trust me
 # https://linear.app/settings/api/applications/new
 # Callback URL: http://localhost:3000/auth/integrations/oauth_callback
+LINEAR_API_KEY=
+# Linear project and team IDs for the feature request tracker.
+# Find these in your Linear workspace URL: linear.app/<workspace>/project/<project-id>
+# and in team settings. Used by the chat copilot to file and search feature requests.
+LINEAR_FEATURE_REQUEST_PROJECT_ID=
+LINEAR_FEATURE_REQUEST_TEAM_ID=
 LINEAR_CLIENT_ID=
 LINEAR_CLIENT_SECRET=
 
@@ -152,6 +158,7 @@ REPLICATE_API_KEY=
 REVID_API_KEY=
 SCREENSHOTONE_API_KEY=
 UNREAL_SPEECH_API_KEY=
+ELEVENLABS_API_KEY=
 
 # Data & Search Services
 E2B_API_KEY=

autogpt_platform/backend/.gitignore

@@ -19,3 +19,6 @@ load-tests/*.json
 load-tests/*.log
 load-tests/node_modules/*
 migrations/*/rollback*.sql
+
+# Workspace files
+workspaces/

autogpt_platform/backend/CLAUDE.md

@@ -0,0 +1,170 @@
+# CLAUDE.md - Backend
+
+This file provides guidance to Claude Code when working with the backend.
+
+## Essential Commands
+
+To run something with Python package dependencies you MUST use `poetry run ...`.
+
+```bash
+# Install dependencies
+poetry install
+
+# Run database migrations
+poetry run prisma migrate dev
+
+# Start all services (database, redis, rabbitmq, clamav)
+docker compose up -d
+
+# Run the backend as a whole
+poetry run app
+
+# Run tests
+poetry run test
+
+# Run specific test
+poetry run pytest path/to/test_file.py::test_function_name
+
+# Run block tests (tests that validate all blocks work correctly)
+poetry run pytest backend/blocks/test/test_block.py -xvs
+
+# Run tests for a specific block (e.g., GetCurrentTimeBlock)
+poetry run pytest 'backend/blocks/test/test_block.py::test_available_blocks[GetCurrentTimeBlock]' -xvs
+
+# Lint and format
+# prefer format if you want to just "fix" it and only get the errors that can't be autofixed
+poetry run format  # Black + isort
+poetry run lint    # ruff
+```
+
+More details can be found in @TESTING.md
+
+### Creating/Updating Snapshots
+
+When you first write a test or when the expected output changes:
+
+```bash
+poetry run pytest path/to/test.py --snapshot-update
+```
+
+⚠️ **Important**: Always review snapshot changes before committing! Use `git diff` to verify the changes are expected.
+
+## Architecture
+
+- **API Layer**: FastAPI with REST and WebSocket endpoints
+- **Database**: PostgreSQL with Prisma ORM, includes pgvector for embeddings
+- **Queue System**: RabbitMQ for async task processing
+- **Execution Engine**: Separate executor service processes agent workflows
+- **Authentication**: JWT-based with Supabase integration
+- **Security**: Cache protection middleware prevents sensitive data caching in browsers/proxies
+
+## Testing Approach
+
+- Uses pytest with snapshot testing for API responses
+- Test files are colocated with source files (`*_test.py`)
+
+## Database Schema
+
+Key models (defined in `schema.prisma`):
+
+- `User`: Authentication and profile data
+- `AgentGraph`: Workflow definitions with version control
+- `AgentGraphExecution`: Execution history and results
+- `AgentNode`: Individual nodes in a workflow
+- `StoreListing`: Marketplace listings for sharing agents
+
+## Environment Configuration
+
+- **Backend**: `.env.default` (defaults) → `.env` (user overrides)
+
+## Common Development Tasks
+
+### Adding a new block
+
+Follow the comprehensive [Block SDK Guide](@../../docs/content/platform/block-sdk-guide.md) which covers:
+
+- Provider configuration with `ProviderBuilder`
+- Block schema definition
+- Authentication (API keys, OAuth, webhooks)
+- Testing and validation
+- File organization
+
+Quick steps:
+
+1. Create new file in `backend/blocks/`
+2. Configure provider using `ProviderBuilder` in `_config.py`
+3. Inherit from `Block` base class
+4. Define input/output schemas using `BlockSchema`
+5. Implement async `run` method
+6. Generate unique block ID using `uuid.uuid4()`
+7. Test with `poetry run pytest backend/blocks/test/test_block.py`
+
+Note: when making many new blocks analyze the interfaces for each of these blocks and picture if they would go well together in a graph-based editor or would they struggle to connect productively?
+ex: do the inputs and outputs tie well together?
+
+If you get any pushback or hit complex block conditions check the new_blocks guide in the docs.
+
+#### Handling files in blocks with `store_media_file()`
+
+When blocks need to work with files (images, videos, documents), use `store_media_file()` from `backend.util.file`. The `return_format` parameter determines what you get back:
+
+| Format | Use When | Returns |
+|--------|----------|---------|
+| `"for_local_processing"` | Processing with local tools (ffmpeg, MoviePy, PIL) | Local file path (e.g., `"image.png"`) |
+| `"for_external_api"` | Sending content to external APIs (Replicate, OpenAI) | Data URI (e.g., `"data:image/png;base64,..."`) |
+| `"for_block_output"` | Returning output from your block | Smart: `workspace://` in CoPilot, data URI in graphs |
+
+**Examples:**
+
+```python
+# INPUT: Need to process file locally with ffmpeg
+local_path = await store_media_file(
+    file=input_data.video,
+    execution_context=execution_context,
+    return_format="for_local_processing",
+)
+# local_path = "video.mp4" - use with Path/ffmpeg/etc
+
+# INPUT: Need to send to external API like Replicate
+image_b64 = await store_media_file(
+    file=input_data.image,
+    execution_context=execution_context,
+    return_format="for_external_api",
+)
+# image_b64 = "data:image/png;base64,iVBORw0..." - send to API
+
+# OUTPUT: Returning result from block
+result_url = await store_media_file(
+    file=generated_image_url,
+    execution_context=execution_context,
+    return_format="for_block_output",
+)
+yield "image_url", result_url
+# In CoPilot: result_url = "workspace://abc123"
+# In graphs:  result_url = "data:image/png;base64,..."
+```
+
+**Key points:**
+
+- `for_block_output` is the ONLY format that auto-adapts to execution context
+- Always use `for_block_output` for block outputs unless you have a specific reason not to
+- Never hardcode workspace checks - let `for_block_output` handle it
+
+### Modifying the API
+
+1. Update route in `backend/api/features/`
+2. Add/update Pydantic models in same directory
+3. Write tests alongside the route file
+4. Run `poetry run test` to verify
+
+## Security Implementation
+
+### Cache Protection Middleware
+
+- Located in `backend/api/middleware/security.py`
+- Default behavior: Disables caching for ALL endpoints with `Cache-Control: no-store, no-cache, must-revalidate, private`
+- Uses an allow list approach - only explicitly permitted paths can be cached
+- Cacheable paths include: static assets (`static/*`, `_next/static/*`), health checks, public store pages, documentation
+- Prevents sensitive data (auth tokens, API keys, user data) from being cached by browsers/proxies
+- To allow caching for a new endpoint, add it to `CACHEABLE_PATHS` in the middleware
+- Applied to both main API server and external API applications

autogpt_platform/backend/Dockerfile

@@ -1,3 +1,5 @@
+# ============================ DEPENDENCY BUILDER ============================ #
+
 FROM debian:13-slim AS builder
 
 # Set environment variables
@@ -51,25 +53,62 @@ COPY autogpt_platform/backend/backend/data/partial_types.py ./backend/data/parti
 COPY autogpt_platform/backend/gen_prisma_types_stub.py ./
 RUN poetry run prisma generate && poetry run gen-prisma-stub
 
-FROM debian:13-slim AS server_dependencies
+# =============================== DB MIGRATOR =============================== #
+
+# Lightweight migrate stage - only needs Prisma CLI, not full Python environment
+FROM debian:13-slim AS migrate
+
+WORKDIR /app/autogpt_platform/backend
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Install only what's needed for prisma migrate: Node.js and minimal Python for prisma-python
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3.13 \
+    python3-pip \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy Node.js from builder (needed for Prisma CLI)
+COPY --from=builder /usr/bin/node /usr/bin/node
+COPY --from=builder /usr/lib/node_modules /usr/lib/node_modules
+COPY --from=builder /usr/bin/npm /usr/bin/npm
+
+# Copy Prisma binaries
+COPY --from=builder /root/.cache/prisma-python/binaries /root/.cache/prisma-python/binaries
+
+# Install prisma-client-py directly (much smaller than copying full venv)
+RUN pip3 install prisma>=0.15.0 --break-system-packages
+
+COPY autogpt_platform/backend/schema.prisma ./
+COPY autogpt_platform/backend/backend/data/partial_types.py ./backend/data/partial_types.py
+COPY autogpt_platform/backend/gen_prisma_types_stub.py ./
+COPY autogpt_platform/backend/migrations ./migrations
+
+# ============================== BACKEND SERVER ============================== #
+
+FROM debian:13-slim AS server
 
 WORKDIR /app
 
-ENV POETRY_HOME=/opt/poetry \
-    POETRY_NO_INTERACTION=1 \
-    POETRY_VIRTUALENVS_CREATE=true \
-    POETRY_VIRTUALENVS_IN_PROJECT=true \
-    DEBIAN_FRONTEND=noninteractive
-ENV PATH=/opt/poetry/bin:$PATH
+ENV DEBIAN_FRONTEND=noninteractive
 
-# Install Python without upgrading system-managed packages
-RUN apt-get update && apt-get install -y \
+# Install Python, FFmpeg, ImageMagick, and CLI tools for agent use.
+# bubblewrap provides OS-level sandbox (whitelist-only FS + no network)
+# for the bash_exec MCP tool.
+# Using --no-install-recommends saves ~650MB by skipping unnecessary deps like llvm, mesa, etc.
+RUN apt-get update && apt-get install -y --no-install-recommends \
     python3.13 \
     python3-pip \
+    ffmpeg \
+    imagemagick \
+    jq \
+    ripgrep \
+    tree \
+    bubblewrap \
     && rm -rf /var/lib/apt/lists/*
 
-# Copy only necessary files from builder
-COPY --from=builder /app /app
+# Copy poetry (build-time only, for `poetry install --only-root` to create entry points)
 COPY --from=builder /usr/local/lib/python3* /usr/local/lib/python3*
 COPY --from=builder /usr/local/bin/poetry /usr/local/bin/poetry
 # Copy Node.js installation for Prisma
@@ -79,30 +118,25 @@ COPY --from=builder /usr/bin/npm /usr/bin/npm
 COPY --from=builder /usr/bin/npx /usr/bin/npx
 COPY --from=builder /root/.cache/prisma-python/binaries /root/.cache/prisma-python/binaries
 
-ENV PATH="/app/autogpt_platform/backend/.venv/bin:$PATH"
-
-RUN mkdir -p /app/autogpt_platform/autogpt_libs
-RUN mkdir -p /app/autogpt_platform/backend
-
-COPY autogpt_platform/autogpt_libs /app/autogpt_platform/autogpt_libs
-
-COPY autogpt_platform/backend/poetry.lock autogpt_platform/backend/pyproject.toml /app/autogpt_platform/backend/
-
 WORKDIR /app/autogpt_platform/backend
 
-FROM server_dependencies AS migrate
+# Copy only the .venv from builder (not the entire /app directory)
+# The .venv includes the generated Prisma client
+COPY --from=builder /app/autogpt_platform/backend/.venv ./.venv
+ENV PATH="/app/autogpt_platform/backend/.venv/bin:$PATH"
 
-# Migration stage only needs schema and migrations - much lighter than full backend
-COPY autogpt_platform/backend/schema.prisma /app/autogpt_platform/backend/
-COPY autogpt_platform/backend/backend/data/partial_types.py /app/autogpt_platform/backend/backend/data/partial_types.py
-COPY autogpt_platform/backend/migrations /app/autogpt_platform/backend/migrations
+# Copy dependency files + autogpt_libs (path dependency)
+COPY autogpt_platform/autogpt_libs /app/autogpt_platform/autogpt_libs
+COPY autogpt_platform/backend/poetry.lock autogpt_platform/backend/pyproject.toml ./
 
-FROM server_dependencies AS server
-
-COPY autogpt_platform/backend /app/autogpt_platform/backend
+# Copy backend code + docs (for Copilot docs search)
+COPY autogpt_platform/backend ./
 COPY docs /app/docs
-RUN poetry install --no-ansi --only-root
+# Install the project package to create entry point scripts in .venv/bin/
+# (e.g., rest, executor, ws, db, scheduler, notification - see [tool.poetry.scripts])
+RUN POETRY_VIRTUALENVS_CREATE=true POETRY_VIRTUALENVS_IN_PROJECT=true \
+    poetry install --no-ansi --only-root
 
 ENV PORT=8000
 
-CMD ["poetry", "run", "rest"]
+CMD ["rest"]

autogpt_platform/backend/TESTING.md

@@ -138,7 +138,7 @@ If the test doesn't need the `user_id` specifically, mocking is not necessary as
 
 #### Using Global Auth Fixtures
 
-Two global auth fixtures are provided by `backend/server/conftest.py`:
+Two global auth fixtures are provided by `backend/api/conftest.py`:
 
 - `mock_jwt_user` - Regular user with `test_user_id` ("test-user-id")
 - `mock_jwt_admin` - Admin user with `admin_user_id` ("admin-user-id")

autogpt_platform/backend/backend/api/conftest.py

@@ -1,4 +1,9 @@
-"""Common test fixtures for server tests."""
+"""Common test fixtures for server tests.
+
+Note: Common fixtures like test_user_id, admin_user_id, target_user_id,
+setup_test_user, and setup_admin_user are defined in the parent conftest.py
+(backend/conftest.py) and are available here automatically.
+"""
 
 import pytest
 from pytest_snapshot.plugin import Snapshot
@@ -11,54 +16,6 @@ def configured_snapshot(snapshot: Snapshot) -> Snapshot:
     return snapshot
 
 
-@pytest.fixture
-def test_user_id() -> str:
-    """Test user ID fixture."""
-    return "3e53486c-cf57-477e-ba2a-cb02dc828e1a"
-
-
-@pytest.fixture
-def admin_user_id() -> str:
-    """Admin user ID fixture."""
-    return "4e53486c-cf57-477e-ba2a-cb02dc828e1b"
-
-
-@pytest.fixture
-def target_user_id() -> str:
-    """Target user ID fixture."""
-    return "5e53486c-cf57-477e-ba2a-cb02dc828e1c"
-
-
-@pytest.fixture
-async def setup_test_user(test_user_id):
-    """Create test user in database before tests."""
-    from backend.data.user import get_or_create_user
-
-    # Create the test user in the database using JWT token format
-    user_data = {
-        "sub": test_user_id,
-        "email": "test@example.com",
-        "user_metadata": {"name": "Test User"},
-    }
-    await get_or_create_user(user_data)
-    return test_user_id
-
-
-@pytest.fixture
-async def setup_admin_user(admin_user_id):
-    """Create admin user in database before tests."""
-    from backend.data.user import get_or_create_user
-
-    # Create the admin user in the database using JWT token format
-    user_data = {
-        "sub": admin_user_id,
-        "email": "test-admin@example.com",
-        "user_metadata": {"name": "Test Admin"},
-    }
-    await get_or_create_user(user_data)
-    return admin_user_id
-
-
 @pytest.fixture
 def mock_jwt_user(test_user_id):
     """Provide mock JWT payload for regular user testing."""

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

@@ -10,7 +10,7 @@ from typing_extensions import TypedDict
 
 import backend.api.features.store.cache as store_cache
 import backend.api.features.store.model as store_model
-import backend.data.block
+import backend.blocks
 from backend.api.external.middleware import require_permission
 from backend.data import execution as execution_db
 from backend.data import graph as graph_db
@@ -67,7 +67,7 @@ async def get_user_info(
     dependencies=[Security(require_permission(APIKeyPermission.READ_BLOCK))],
 )
 async def get_graph_blocks() -> Sequence[dict[Any, Any]]:
-    blocks = [block() for block in backend.data.block.get_blocks().values()]
+    blocks = [block() for block in backend.blocks.get_blocks().values()]
     return [b.to_dict() for b in blocks if not b.disabled]
 
 
@@ -83,7 +83,7 @@ async def execute_graph_block(
         require_permission(APIKeyPermission.EXECUTE_BLOCK)
     ),
 ) -> CompletedBlockOutput:
-    obj = backend.data.block.get_block(block_id)
+    obj = backend.blocks.get_block(block_id)
     if not obj:
         raise HTTPException(status_code=404, detail=f"Block #{block_id} not found.")
     if obj.disabled:

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

@@ -15,9 +15,9 @@ from prisma.enums import APIKeyPermission
 from pydantic import BaseModel, Field
 
 from backend.api.external.middleware import require_permission
-from backend.api.features.chat.model import ChatSession
-from backend.api.features.chat.tools import find_agent_tool, run_agent_tool
-from backend.api.features.chat.tools.models import ToolResponseBase
+from backend.copilot.model import ChatSession
+from backend.copilot.tools import find_agent_tool, run_agent_tool
+from backend.copilot.tools.models import ToolResponseBase
 from backend.data.auth.base import APIAuthorizationInfo
 
 logger = logging.getLogger(__name__)

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

@@ -10,10 +10,15 @@ import backend.api.features.library.db as library_db
 import backend.api.features.library.model as library_model
 import backend.api.features.store.db as store_db
 import backend.api.features.store.model as store_model
-import backend.data.block
 from backend.blocks import load_all_blocks
+from backend.blocks._base import (
+    AnyBlockSchema,
+    BlockCategory,
+    BlockInfo,
+    BlockSchema,
+    BlockType,
+)
 from backend.blocks.llm import LlmModel
-from backend.data.block import AnyBlockSchema, BlockCategory, BlockInfo, BlockSchema
 from backend.data.db import query_raw_with_schema
 from backend.integrations.providers import ProviderName
 from backend.util.cache import cached
@@ -22,7 +27,7 @@ from backend.util.models import Pagination
 from .model import (
     BlockCategoryResponse,
     BlockResponse,
-    BlockType,
+    BlockTypeFilter,
     CountResponse,
     FilterType,
     Provider,
@@ -88,7 +93,7 @@ def get_block_categories(category_blocks: int = 3) -> list[BlockCategoryResponse
 def get_blocks(
     *,
     category: str | None = None,
-    type: BlockType | None = None,
+    type: BlockTypeFilter | None = None,
     provider: ProviderName | None = None,
     page: int = 1,
     page_size: int = 50,
@@ -669,9 +674,9 @@ async def get_suggested_blocks(count: int = 5) -> list[BlockInfo]:
     for block_type in load_all_blocks().values():
         block: AnyBlockSchema = block_type()
         if block.disabled or block.block_type in (
-            backend.data.block.BlockType.INPUT,
-            backend.data.block.BlockType.OUTPUT,
-            backend.data.block.BlockType.AGENT,
+            BlockType.INPUT,
+            BlockType.OUTPUT,
+            BlockType.AGENT,
         ):
             continue
         # Find the execution count for this block

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

@@ -4,7 +4,7 @@ from pydantic import BaseModel
 
 import backend.api.features.library.model as library_model
 import backend.api.features.store.model as store_model
-from backend.data.block import BlockInfo
+from backend.blocks._base import BlockInfo
 from backend.integrations.providers import ProviderName
 from backend.util.models import Pagination
 
@@ -15,7 +15,7 @@ FilterType = Literal[
     "my_agents",
 ]
 
-BlockType = Literal["all", "input", "action", "output"]
+BlockTypeFilter = Literal["all", "input", "action", "output"]
 
 
 class SearchEntry(BaseModel):

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

@@ -17,7 +17,7 @@ router = fastapi.APIRouter(
 )
 
 
-# Taken from backend/server/v2/store/db.py
+# Taken from backend/api/features/store/db.py
 def sanitize_query(query: str | None) -> str | None:
     if query is None:
         return query
@@ -88,7 +88,7 @@ async def get_block_categories(
 )
 async def get_blocks(
     category: Annotated[str | None, fastapi.Query()] = None,
-    type: Annotated[builder_model.BlockType | None, fastapi.Query()] = None,
+    type: Annotated[builder_model.BlockTypeFilter | None, fastapi.Query()] = None,
     provider: Annotated[ProviderName | None, fastapi.Query()] = None,
     page: Annotated[int, fastapi.Query()] = 1,
     page_size: Annotated[int, fastapi.Query()] = 50,

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

@@ -1,96 +0,0 @@
-"""Configuration management for chat system."""
-
-import os
-
-from pydantic import Field, field_validator
-from pydantic_settings import BaseSettings
-
-
-class ChatConfig(BaseSettings):
-    """Configuration for the chat system."""
-
-    # OpenAI API Configuration
-    model: str = Field(
-        default="anthropic/claude-opus-4.5", description="Default model to use"
-    )
-    title_model: str = Field(
-        default="openai/gpt-4o-mini",
-        description="Model to use for generating session titles (should be fast/cheap)",
-    )
-    api_key: str | None = Field(default=None, description="OpenAI API key")
-    base_url: str | None = Field(
-        default="https://openrouter.ai/api/v1",
-        description="Base URL for API (e.g., for OpenRouter)",
-    )
-
-    # Session TTL Configuration - 12 hours
-    session_ttl: int = Field(default=43200, description="Session TTL in seconds")
-
-    # Streaming Configuration
-    max_context_messages: int = Field(
-        default=50, ge=1, le=200, description="Maximum context messages"
-    )
-
-    stream_timeout: int = Field(default=300, description="Stream timeout in seconds")
-    max_retries: int = Field(default=3, description="Maximum number of retries")
-    max_agent_runs: int = Field(default=30, description="Maximum number of agent runs")
-    max_agent_schedules: int = Field(
-        default=30, description="Maximum number of agent schedules"
-    )
-
-    # Long-running operation configuration
-    long_running_operation_ttl: int = Field(
-        default=600,
-        description="TTL in seconds for long-running operation tracking in Redis (safety net if pod dies)",
-    )
-
-    # Langfuse Prompt Management Configuration
-    # Note: Langfuse credentials are in Settings().secrets (settings.py)
-    langfuse_prompt_name: str = Field(
-        default="CoPilot Prompt",
-        description="Name of the prompt in Langfuse to fetch",
-    )
-
-    @field_validator("api_key", mode="before")
-    @classmethod
-    def get_api_key(cls, v):
-        """Get API key from environment if not provided."""
-        if v is None:
-            # Try to get from environment variables
-            # First check for CHAT_API_KEY (Pydantic prefix)
-            v = os.getenv("CHAT_API_KEY")
-            if not v:
-                # Fall back to OPEN_ROUTER_API_KEY
-                v = os.getenv("OPEN_ROUTER_API_KEY")
-            if not v:
-                # Fall back to OPENAI_API_KEY
-                v = os.getenv("OPENAI_API_KEY")
-        return v
-
-    @field_validator("base_url", mode="before")
-    @classmethod
-    def get_base_url(cls, v):
-        """Get base URL from environment if not provided."""
-        if v is None:
-            # Check for OpenRouter or custom base URL
-            v = os.getenv("CHAT_BASE_URL")
-            if not v:
-                v = os.getenv("OPENROUTER_BASE_URL")
-            if not v:
-                v = os.getenv("OPENAI_BASE_URL")
-            if not v:
-                v = "https://openrouter.ai/api/v1"
-        return v
-
-    # Prompt paths for different contexts
-    PROMPT_PATHS: dict[str, str] = {
-        "default": "prompts/chat_system.md",
-        "onboarding": "prompts/onboarding_system.md",
-    }
-
-    class Config:
-        """Pydantic config."""
-
-        env_file = ".env"
-        env_file_encoding = "utf-8"
-        extra = "ignore"  # Ignore extra environment variables

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

@@ -1,119 +0,0 @@
-import pytest
-
-from .model import (
-    ChatMessage,
-    ChatSession,
-    Usage,
-    get_chat_session,
-    upsert_chat_session,
-)
-
-messages = [
-    ChatMessage(content="Hello, how are you?", role="user"),
-    ChatMessage(
-        content="I'm fine, thank you!",
-        role="assistant",
-        tool_calls=[
-            {
-                "id": "t123",
-                "type": "function",
-                "function": {
-                    "name": "get_weather",
-                    "arguments": '{"city": "New York"}',
-                },
-            }
-        ],
-    ),
-    ChatMessage(
-        content="I'm using the tool to get the weather",
-        role="tool",
-        tool_call_id="t123",
-    ),
-]
-
-
-@pytest.mark.asyncio(loop_scope="session")
-async def test_chatsession_serialization_deserialization():
-    s = ChatSession.new(user_id="abc123")
-    s.messages = messages
-    s.usage = [Usage(prompt_tokens=100, completion_tokens=200, total_tokens=300)]
-    serialized = s.model_dump_json()
-    s2 = ChatSession.model_validate_json(serialized)
-    assert s2.model_dump() == s.model_dump()
-
-
-@pytest.mark.asyncio(loop_scope="session")
-async def test_chatsession_redis_storage(setup_test_user, test_user_id):
-
-    s = ChatSession.new(user_id=test_user_id)
-    s.messages = messages
-
-    s = await upsert_chat_session(s)
-
-    s2 = await get_chat_session(
-        session_id=s.session_id,
-        user_id=s.user_id,
-    )
-
-    assert s2 == s
-
-
-@pytest.mark.asyncio(loop_scope="session")
-async def test_chatsession_redis_storage_user_id_mismatch(
-    setup_test_user, test_user_id
-):
-
-    s = ChatSession.new(user_id=test_user_id)
-    s.messages = messages
-    s = await upsert_chat_session(s)
-
-    s2 = await get_chat_session(s.session_id, "different_user_id")
-
-    assert s2 is None
-
-
-@pytest.mark.asyncio(loop_scope="session")
-async def test_chatsession_db_storage(setup_test_user, test_user_id):
-    """Test that messages are correctly saved to and loaded from DB (not cache)."""
-    from backend.data.redis_client import get_redis_async
-
-    # Create session with messages including assistant message
-    s = ChatSession.new(user_id=test_user_id)
-    s.messages = messages  # Contains user, assistant, and tool messages
-    assert s.session_id is not None, "Session id is not set"
-    # Upsert to save to both cache and DB
-    s = await upsert_chat_session(s)
-
-    # Clear the Redis cache to force DB load
-    redis_key = f"chat:session:{s.session_id}"
-    async_redis = await get_redis_async()
-    await async_redis.delete(redis_key)
-
-    # Load from DB (cache was cleared)
-    s2 = await get_chat_session(
-        session_id=s.session_id,
-        user_id=s.user_id,
-    )
-
-    assert s2 is not None, "Session not found after loading from DB"
-    assert len(s2.messages) == len(
-        s.messages
-    ), f"Message count mismatch: expected {len(s.messages)}, got {len(s2.messages)}"
-
-    # Verify all roles are present
-    roles = [m.role for m in s2.messages]
-    assert "user" in roles, f"User message missing. Roles found: {roles}"
-    assert "assistant" in roles, f"Assistant message missing. Roles found: {roles}"
-    assert "tool" in roles, f"Tool message missing. Roles found: {roles}"
-
-    # Verify message content
-    for orig, loaded in zip(s.messages, s2.messages):
-        assert orig.role == loaded.role, f"Role mismatch: {orig.role} != {loaded.role}"
-        assert (
-            orig.content == loaded.content
-        ), f"Content mismatch for {orig.role}: {orig.content} != {loaded.content}"
-        if orig.tool_calls:
-            assert (
-                loaded.tool_calls is not None
-            ), f"Tool calls missing for {orig.role} message"
-            assert len(orig.tool_calls) == len(loaded.tool_calls)

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

@@ -1,20 +1,60 @@
 """Chat API routes for chat session management and streaming via SSE."""
 
+import asyncio
 import logging
+import uuid as uuid_module
 from collections.abc import AsyncGenerator
 from typing import Annotated
 
 from autogpt_libs import auth
-from fastapi import APIRouter, Depends, Query, Security
+from fastapi import APIRouter, Depends, Header, HTTPException, Query, Response, Security
 from fastapi.responses import StreamingResponse
 from pydantic import BaseModel
 
+from backend.copilot import service as chat_service
+from backend.copilot import stream_registry
+from backend.copilot.completion_handler import (
+    process_operation_failure,
+    process_operation_success,
+)
+from backend.copilot.config import ChatConfig
+from backend.copilot.executor.utils import enqueue_copilot_task
+from backend.copilot.model import (
+    ChatMessage,
+    ChatSession,
+    append_and_save_message,
+    create_chat_session,
+    delete_chat_session,
+    get_chat_session,
+    get_user_sessions,
+)
+from backend.copilot.response_model import StreamError, StreamFinish, StreamHeartbeat
+from backend.copilot.tools.models import (
+    AgentDetailsResponse,
+    AgentOutputResponse,
+    AgentPreviewResponse,
+    AgentSavedResponse,
+    AgentsFoundResponse,
+    BlockDetailsResponse,
+    BlockListResponse,
+    BlockOutputResponse,
+    ClarificationNeededResponse,
+    DocPageResponse,
+    DocSearchResultsResponse,
+    ErrorResponse,
+    ExecutionStartedResponse,
+    InputValidationErrorResponse,
+    NeedLoginResponse,
+    NoResultsResponse,
+    OperationInProgressResponse,
+    OperationPendingResponse,
+    OperationStartedResponse,
+    SetupRequirementsResponse,
+    UnderstandingUpdatedResponse,
+)
+from backend.copilot.tracking import track_user_message
 from backend.util.exceptions import NotFoundError
 
-from . import service as chat_service
-from .config import ChatConfig
-from .model import ChatSession, create_chat_session, get_chat_session, get_user_sessions
-
 config = ChatConfig()
 
 
@@ -55,6 +95,15 @@ class CreateSessionResponse(BaseModel):
     user_id: str | None
 
 
+class ActiveStreamInfo(BaseModel):
+    """Information about an active stream for reconnection."""
+
+    task_id: str
+    last_message_id: str  # Redis Stream message ID for resumption
+    operation_id: str  # Operation ID for completion tracking
+    tool_name: str  # Name of the tool being executed
+
+
 class SessionDetailResponse(BaseModel):
     """Response model providing complete details for a chat session, including messages."""
 
@@ -63,6 +112,7 @@ class SessionDetailResponse(BaseModel):
     updated_at: str
     user_id: str | None
     messages: list[dict]
+    active_stream: ActiveStreamInfo | None = None  # Present if stream is still active
 
 
 class SessionSummaryResponse(BaseModel):
@@ -81,6 +131,14 @@ class ListSessionsResponse(BaseModel):
     total: int
 
 
+class OperationCompleteRequest(BaseModel):
+    """Request model for external completion webhook."""
+
+    success: bool
+    result: dict | str | None = None
+    error: str | None = None
+
+
 # ========== Routes ==========
 
 
@@ -155,6 +213,43 @@ async def create_session(
     )
 
 
+@router.delete(
+    "/sessions/{session_id}",
+    dependencies=[Security(auth.requires_user)],
+    status_code=204,
+    responses={404: {"description": "Session not found or access denied"}},
+)
+async def delete_session(
+    session_id: str,
+    user_id: Annotated[str, Security(auth.get_user_id)],
+) -> Response:
+    """
+    Delete a chat session.
+
+    Permanently removes a chat session and all its messages.
+    Only the owner can delete their sessions.
+
+    Args:
+        session_id: The session ID to delete.
+        user_id: The authenticated user's ID.
+
+    Returns:
+        204 No Content on success.
+
+    Raises:
+        HTTPException: 404 if session not found or not owned by user.
+    """
+    deleted = await delete_chat_session(session_id, user_id)
+
+    if not deleted:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Session {session_id} not found or access denied",
+        )
+
+    return Response(status_code=204)
+
+
 @router.get(
     "/sessions/{session_id}",
 )
@@ -166,13 +261,14 @@ async def get_session(
     Retrieve the details of a specific chat session.
 
     Looks up a chat session by ID for the given user (if authenticated) and returns all session data including messages.
+    If there's an active stream for this session, returns the task_id for reconnection.
 
     Args:
         session_id: The unique identifier for the desired chat session.
         user_id: The optional authenticated user ID, or None for anonymous access.
 
     Returns:
-        SessionDetailResponse: Details for the requested session, or None if not found.
+        SessionDetailResponse: Details for the requested session, including active_stream info if applicable.
 
     """
     session = await get_chat_session(session_id, user_id)
@@ -180,11 +276,32 @@ async def get_session(
         raise NotFoundError(f"Session {session_id} not found.")
 
     messages = [message.model_dump() for message in session.messages]
-    logger.info(
-        f"Returning session {session_id}: "
-        f"message_count={len(messages)}, "
-        f"roles={[m.get('role') for m in messages]}"
+
+    # Check if there's an active stream for this session
+    active_stream_info = None
+    active_task, last_message_id = await stream_registry.get_active_task_for_session(
+        session_id, user_id
     )
+    logger.info(
+        f"[GET_SESSION] session={session_id}, active_task={active_task is not None}, "
+        f"msg_count={len(messages)}, last_role={messages[-1].get('role') if messages else 'none'}"
+    )
+    if active_task:
+        # Filter out the in-progress assistant message from the session response.
+        # The client will receive the complete assistant response through the SSE
+        # stream replay instead, preventing duplicate content.
+        if messages and messages[-1].get("role") == "assistant":
+            messages = messages[:-1]
+
+        # Use "0-0" as last_message_id to replay the stream from the beginning.
+        # Since we filtered out the cached assistant message, the client needs
+        # the full stream to reconstruct the response.
+        active_stream_info = ActiveStreamInfo(
+            task_id=active_task.task_id,
+            last_message_id="0-0",
+            operation_id=active_task.operation_id,
+            tool_name=active_task.tool_name,
+        )
 
     return SessionDetailResponse(
         id=session.session_id,
@@ -192,6 +309,7 @@ async def get_session(
         updated_at=session.updated_at.isoformat(),
         user_id=session.user_id or None,
         messages=messages,
+        active_stream=active_stream_info,
     )
 
 
@@ -211,49 +329,225 @@ async def stream_chat_post(
       - Tool call UI elements (if invoked)
       - Tool execution results
 
+    The AI generation runs in a background task that continues even if the client disconnects.
+    All chunks are written to Redis for reconnection support. If the client disconnects,
+    they can reconnect using GET /tasks/{task_id}/stream to resume from where they left off.
+
     Args:
         session_id: The chat session identifier to associate with the streamed messages.
         request: Request body containing message, is_user_message, and optional context.
         user_id: Optional authenticated user ID.
     Returns:
-        StreamingResponse: SSE-formatted response chunks.
+        StreamingResponse: SSE-formatted response chunks. First chunk is a "start" event
+        containing the task_id for reconnection.
 
     """
-    session = await _validate_and_get_session(session_id, user_id)
+    import asyncio
+    import time
 
-    async def event_generator() -> AsyncGenerator[str, None]:
-        chunk_count = 0
-        first_chunk_type: str | None = None
-        async for chunk in chat_service.stream_chat_completion(
-            session_id,
-            request.message,
-            is_user_message=request.is_user_message,
-            user_id=user_id,
-            session=session,  # Pass pre-fetched session to avoid double-fetch
-            context=request.context,
-        ):
-            if chunk_count < 3:
-                logger.info(
-                    "Chat stream chunk",
-                    extra={
-                        "session_id": session_id,
-                        "chunk_type": str(chunk.type),
-                    },
-                )
-            if not first_chunk_type:
-                first_chunk_type = str(chunk.type)
-            chunk_count += 1
-            yield chunk.to_sse()
-        logger.info(
-            "Chat stream completed",
-            extra={
-                "session_id": session_id,
-                "chunk_count": chunk_count,
-                "first_chunk_type": first_chunk_type,
-            },
+    stream_start_time = time.perf_counter()
+    log_meta = {"component": "ChatStream", "session_id": session_id}
+    if user_id:
+        log_meta["user_id"] = user_id
+
+    logger.info(
+        f"[TIMING] stream_chat_post STARTED, session={session_id}, "
+        f"user={user_id}, message_len={len(request.message)}",
+        extra={"json_fields": log_meta},
+    )
+    await _validate_and_get_session(session_id, user_id)
+    logger.info(
+        f"[TIMING] session validated in {(time.perf_counter() - stream_start_time) * 1000:.1f}ms",
+        extra={
+            "json_fields": {
+                **log_meta,
+                "duration_ms": (time.perf_counter() - stream_start_time) * 1000,
+            }
+        },
+    )
+
+    # Atomically append user message to session BEFORE creating task to avoid
+    # race condition where GET_SESSION sees task as "running" but message isn't
+    # saved yet.  append_and_save_message re-fetches inside a lock to prevent
+    # message loss from concurrent requests.
+    if request.message:
+        message = ChatMessage(
+            role="user" if request.is_user_message else "assistant",
+            content=request.message,
         )
-        # AI SDK protocol termination
-        yield "data: [DONE]\n\n"
+        if request.is_user_message:
+            track_user_message(
+                user_id=user_id,
+                session_id=session_id,
+                message_length=len(request.message),
+            )
+        logger.info(f"[STREAM] Saving user message to session {session_id}")
+        await append_and_save_message(session_id, message)
+        logger.info(f"[STREAM] User message saved for session {session_id}")
+
+    # Create a task in the stream registry for reconnection support
+    task_id = str(uuid_module.uuid4())
+    operation_id = str(uuid_module.uuid4())
+    log_meta["task_id"] = task_id
+
+    task_create_start = time.perf_counter()
+    await stream_registry.create_task(
+        task_id=task_id,
+        session_id=session_id,
+        user_id=user_id,
+        tool_call_id="chat_stream",  # Not a tool call, but needed for the model
+        tool_name="chat",
+        operation_id=operation_id,
+    )
+    logger.info(
+        f"[TIMING] create_task completed in {(time.perf_counter() - task_create_start) * 1000:.1f}ms",
+        extra={
+            "json_fields": {
+                **log_meta,
+                "duration_ms": (time.perf_counter() - task_create_start) * 1000,
+            }
+        },
+    )
+
+    await enqueue_copilot_task(
+        task_id=task_id,
+        session_id=session_id,
+        user_id=user_id,
+        operation_id=operation_id,
+        message=request.message,
+        is_user_message=request.is_user_message,
+        context=request.context,
+    )
+
+    setup_time = (time.perf_counter() - stream_start_time) * 1000
+    logger.info(
+        f"[TIMING] Task enqueued to RabbitMQ, setup={setup_time:.1f}ms",
+        extra={"json_fields": {**log_meta, "setup_time_ms": setup_time}},
+    )
+
+    # SSE endpoint that subscribes to the task's stream
+    async def event_generator() -> AsyncGenerator[str, None]:
+        import time as time_module
+
+        event_gen_start = time_module.perf_counter()
+        logger.info(
+            f"[TIMING] event_generator STARTED, task={task_id}, session={session_id}, "
+            f"user={user_id}",
+            extra={"json_fields": log_meta},
+        )
+        subscriber_queue = None
+        first_chunk_yielded = False
+        chunks_yielded = 0
+        try:
+            # Subscribe to the task stream (this replays existing messages + live updates)
+            subscriber_queue = await stream_registry.subscribe_to_task(
+                task_id=task_id,
+                user_id=user_id,
+                last_message_id="0-0",  # Get all messages from the beginning
+            )
+
+            if subscriber_queue is None:
+                yield StreamFinish().to_sse()
+                yield "data: [DONE]\n\n"
+                return
+
+            # Read from the subscriber queue and yield to SSE
+            logger.info(
+                "[TIMING] Starting to read from subscriber_queue",
+                extra={"json_fields": log_meta},
+            )
+            while True:
+                try:
+                    chunk = await asyncio.wait_for(subscriber_queue.get(), timeout=30.0)
+                    chunks_yielded += 1
+
+                    if not first_chunk_yielded:
+                        first_chunk_yielded = True
+                        elapsed = time_module.perf_counter() - event_gen_start
+                        logger.info(
+                            f"[TIMING] FIRST CHUNK from queue at {elapsed:.2f}s, "
+                            f"type={type(chunk).__name__}",
+                            extra={
+                                "json_fields": {
+                                    **log_meta,
+                                    "chunk_type": type(chunk).__name__,
+                                    "elapsed_ms": elapsed * 1000,
+                                }
+                            },
+                        )
+
+                    yield chunk.to_sse()
+
+                    # Check for finish signal
+                    if isinstance(chunk, StreamFinish):
+                        total_time = time_module.perf_counter() - event_gen_start
+                        logger.info(
+                            f"[TIMING] StreamFinish received in {total_time:.2f}s; "
+                            f"n_chunks={chunks_yielded}",
+                            extra={
+                                "json_fields": {
+                                    **log_meta,
+                                    "chunks_yielded": chunks_yielded,
+                                    "total_time_ms": total_time * 1000,
+                                }
+                            },
+                        )
+                        break
+                except asyncio.TimeoutError:
+                    yield StreamHeartbeat().to_sse()
+
+        except GeneratorExit:
+            logger.info(
+                f"[TIMING] GeneratorExit (client disconnected), chunks={chunks_yielded}",
+                extra={
+                    "json_fields": {
+                        **log_meta,
+                        "chunks_yielded": chunks_yielded,
+                        "reason": "client_disconnect",
+                    }
+                },
+            )
+            pass  # Client disconnected - background task continues
+        except Exception as e:
+            elapsed = (time_module.perf_counter() - event_gen_start) * 1000
+            logger.error(
+                f"[TIMING] event_generator ERROR after {elapsed:.1f}ms: {e}",
+                extra={
+                    "json_fields": {**log_meta, "elapsed_ms": elapsed, "error": str(e)}
+                },
+            )
+            # Surface error to frontend so it doesn't appear stuck
+            yield StreamError(
+                errorText="An error occurred. Please try again.",
+                code="stream_error",
+            ).to_sse()
+            yield StreamFinish().to_sse()
+        finally:
+            # Unsubscribe when client disconnects or stream ends
+            if subscriber_queue is not None:
+                try:
+                    await stream_registry.unsubscribe_from_task(
+                        task_id, subscriber_queue
+                    )
+                except Exception as unsub_err:
+                    logger.error(
+                        f"Error unsubscribing from task {task_id}: {unsub_err}",
+                        exc_info=True,
+                    )
+            # AI SDK protocol termination - always yield even if unsubscribe fails
+            total_time = time_module.perf_counter() - event_gen_start
+            logger.info(
+                f"[TIMING] event_generator FINISHED in {total_time:.2f}s; "
+                f"task={task_id}, session={session_id}, n_chunks={chunks_yielded}",
+                extra={
+                    "json_fields": {
+                        **log_meta,
+                        "total_time_ms": total_time * 1000,
+                        "chunks_yielded": chunks_yielded,
+                    }
+                },
+            )
+            yield "data: [DONE]\n\n"
 
     return StreamingResponse(
         event_generator(),
@@ -270,63 +564,90 @@ async def stream_chat_post(
 @router.get(
     "/sessions/{session_id}/stream",
 )
-async def stream_chat_get(
+async def resume_session_stream(
     session_id: str,
-    message: Annotated[str, Query(min_length=1, max_length=10000)],
     user_id: str | None = Depends(auth.get_user_id),
-    is_user_message: bool = Query(default=True),
 ):
     """
-    Stream chat responses for a session (GET - legacy endpoint).
+    Resume an active stream for a session.
 
-    Streams the AI/completion responses in real time over Server-Sent Events (SSE), including:
-      - Text fragments as they are generated
-      - Tool call UI elements (if invoked)
-      - Tool execution results
+    Called by the AI SDK's ``useChat(resume: true)`` on page load.
+    Checks for an active (in-progress) task on the session and either replays
+    the full SSE stream or returns 204 No Content if nothing is running.
 
     Args:
-        session_id: The chat session identifier to associate with the streamed messages.
-        message: The user's new message to process.
+        session_id: The chat session identifier.
         user_id: Optional authenticated user ID.
-        is_user_message: Whether the message is a user message.
-    Returns:
-        StreamingResponse: SSE-formatted response chunks.
 
+    Returns:
+        StreamingResponse (SSE) when an active stream exists,
+        or 204 No Content when there is nothing to resume.
     """
-    session = await _validate_and_get_session(session_id, user_id)
+    import asyncio
+
+    active_task, _last_id = await stream_registry.get_active_task_for_session(
+        session_id, user_id
+    )
+
+    if not active_task:
+        return Response(status_code=204)
+
+    subscriber_queue = await stream_registry.subscribe_to_task(
+        task_id=active_task.task_id,
+        user_id=user_id,
+        last_message_id="0-0",  # Full replay so useChat rebuilds the message
+    )
+
+    if subscriber_queue is None:
+        return Response(status_code=204)
 
     async def event_generator() -> AsyncGenerator[str, None]:
         chunk_count = 0
         first_chunk_type: str | None = None
-        async for chunk in chat_service.stream_chat_completion(
-            session_id,
-            message,
-            is_user_message=is_user_message,
-            user_id=user_id,
-            session=session,  # Pass pre-fetched session to avoid double-fetch
-        ):
-            if chunk_count < 3:
-                logger.info(
-                    "Chat stream chunk",
-                    extra={
-                        "session_id": session_id,
-                        "chunk_type": str(chunk.type),
-                    },
+        try:
+            while True:
+                try:
+                    chunk = await asyncio.wait_for(subscriber_queue.get(), timeout=30.0)
+                    if chunk_count < 3:
+                        logger.info(
+                            "Resume stream chunk",
+                            extra={
+                                "session_id": session_id,
+                                "chunk_type": str(chunk.type),
+                            },
+                        )
+                    if not first_chunk_type:
+                        first_chunk_type = str(chunk.type)
+                    chunk_count += 1
+                    yield chunk.to_sse()
+
+                    if isinstance(chunk, StreamFinish):
+                        break
+                except asyncio.TimeoutError:
+                    yield StreamHeartbeat().to_sse()
+        except GeneratorExit:
+            pass
+        except Exception as e:
+            logger.error(f"Error in resume stream for session {session_id}: {e}")
+        finally:
+            try:
+                await stream_registry.unsubscribe_from_task(
+                    active_task.task_id, subscriber_queue
                 )
-            if not first_chunk_type:
-                first_chunk_type = str(chunk.type)
-            chunk_count += 1
-            yield chunk.to_sse()
-        logger.info(
-            "Chat stream completed",
-            extra={
-                "session_id": session_id,
-                "chunk_count": chunk_count,
-                "first_chunk_type": first_chunk_type,
-            },
-        )
-        # AI SDK protocol termination
-        yield "data: [DONE]\n\n"
+            except Exception as unsub_err:
+                logger.error(
+                    f"Error unsubscribing from task {active_task.task_id}: {unsub_err}",
+                    exc_info=True,
+                )
+            logger.info(
+                "Resume stream completed",
+                extra={
+                    "session_id": session_id,
+                    "n_chunks": chunk_count,
+                    "first_chunk_type": first_chunk_type,
+                },
+            )
+            yield "data: [DONE]\n\n"
 
     return StreamingResponse(
         event_generator(),
@@ -334,8 +655,8 @@ async def stream_chat_get(
         headers={
             "Cache-Control": "no-cache",
             "Connection": "keep-alive",
-            "X-Accel-Buffering": "no",  # Disable nginx buffering
-            "x-vercel-ai-ui-message-stream": "v1",  # AI SDK protocol header
+            "X-Accel-Buffering": "no",
+            "x-vercel-ai-ui-message-stream": "v1",
         },
     )
 
@@ -366,6 +687,249 @@ async def session_assign_user(
     return {"status": "ok"}
 
 
+# ========== Task Streaming (SSE Reconnection) ==========
+
+
+@router.get(
+    "/tasks/{task_id}/stream",
+)
+async def stream_task(
+    task_id: str,
+    user_id: str | None = Depends(auth.get_user_id),
+    last_message_id: str = Query(
+        default="0-0",
+        description="Last Redis Stream message ID received (e.g., '1706540123456-0'). Use '0-0' for full replay.",
+    ),
+):
+    """
+    Reconnect to a long-running task's SSE stream.
+
+    When a long-running operation (like agent generation) starts, the client
+    receives a task_id. If the connection drops, the client can reconnect
+    using this endpoint to resume receiving updates.
+
+    Args:
+        task_id: The task ID from the operation_started response.
+        user_id: Authenticated user ID for ownership validation.
+        last_message_id: Last Redis Stream message ID received ("0-0" for full replay).
+
+    Returns:
+        StreamingResponse: SSE-formatted response chunks starting after last_message_id.
+
+    Raises:
+        HTTPException: 404 if task not found, 410 if task expired, 403 if access denied.
+    """
+    # Check task existence and expiry before subscribing
+    task, error_code = await stream_registry.get_task_with_expiry_info(task_id)
+
+    if error_code == "TASK_EXPIRED":
+        raise HTTPException(
+            status_code=410,
+            detail={
+                "code": "TASK_EXPIRED",
+                "message": "This operation has expired. Please try again.",
+            },
+        )
+
+    if error_code == "TASK_NOT_FOUND":
+        raise HTTPException(
+            status_code=404,
+            detail={
+                "code": "TASK_NOT_FOUND",
+                "message": f"Task {task_id} not found.",
+            },
+        )
+
+    # Validate ownership if task has an owner
+    if task and task.user_id and user_id != task.user_id:
+        raise HTTPException(
+            status_code=403,
+            detail={
+                "code": "ACCESS_DENIED",
+                "message": "You do not have access to this task.",
+            },
+        )
+
+    # Get subscriber queue from stream registry
+    subscriber_queue = await stream_registry.subscribe_to_task(
+        task_id=task_id,
+        user_id=user_id,
+        last_message_id=last_message_id,
+    )
+
+    if subscriber_queue is None:
+        raise HTTPException(
+            status_code=404,
+            detail={
+                "code": "TASK_NOT_FOUND",
+                "message": f"Task {task_id} not found or access denied.",
+            },
+        )
+
+    async def event_generator() -> AsyncGenerator[str, None]:
+        heartbeat_interval = 15.0  # Send heartbeat every 15 seconds
+        try:
+            while True:
+                try:
+                    # Wait for next chunk with timeout for heartbeats
+                    chunk = await asyncio.wait_for(
+                        subscriber_queue.get(), timeout=heartbeat_interval
+                    )
+                    yield chunk.to_sse()
+
+                    # Check for finish signal
+                    if isinstance(chunk, StreamFinish):
+                        break
+                except asyncio.TimeoutError:
+                    # Send heartbeat to keep connection alive
+                    yield StreamHeartbeat().to_sse()
+        except Exception as e:
+            logger.error(f"Error in task stream {task_id}: {e}", exc_info=True)
+        finally:
+            # Unsubscribe when client disconnects or stream ends
+            try:
+                await stream_registry.unsubscribe_from_task(task_id, subscriber_queue)
+            except Exception as unsub_err:
+                logger.error(
+                    f"Error unsubscribing from task {task_id}: {unsub_err}",
+                    exc_info=True,
+                )
+            # AI SDK protocol termination - always yield even if unsubscribe fails
+            yield "data: [DONE]\n\n"
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+            "x-vercel-ai-ui-message-stream": "v1",
+        },
+    )
+
+
+@router.get(
+    "/tasks/{task_id}",
+)
+async def get_task_status(
+    task_id: str,
+    user_id: str | None = Depends(auth.get_user_id),
+) -> dict:
+    """
+    Get the status of a long-running task.
+
+    Args:
+        task_id: The task ID to check.
+        user_id: Authenticated user ID for ownership validation.
+
+    Returns:
+        dict: Task status including task_id, status, tool_name, and operation_id.
+
+    Raises:
+        NotFoundError: If task_id is not found or user doesn't have access.
+    """
+    task = await stream_registry.get_task(task_id)
+
+    if task is None:
+        raise NotFoundError(f"Task {task_id} not found.")
+
+    # Validate ownership - if task has an owner, requester must match
+    if task.user_id and user_id != task.user_id:
+        raise NotFoundError(f"Task {task_id} not found.")
+
+    return {
+        "task_id": task.task_id,
+        "session_id": task.session_id,
+        "status": task.status,
+        "tool_name": task.tool_name,
+        "operation_id": task.operation_id,
+        "created_at": task.created_at.isoformat(),
+    }
+
+
+# ========== External Completion Webhook ==========
+
+
+@router.post(
+    "/operations/{operation_id}/complete",
+    status_code=200,
+)
+async def complete_operation(
+    operation_id: str,
+    request: OperationCompleteRequest,
+    x_api_key: str | None = Header(default=None),
+) -> dict:
+    """
+    External completion webhook for long-running operations.
+
+    Called by Agent Generator (or other services) when an operation completes.
+    This triggers the stream registry to publish completion and continue LLM generation.
+
+    Args:
+        operation_id: The operation ID to complete.
+        request: Completion payload with success status and result/error.
+        x_api_key: Internal API key for authentication.
+
+    Returns:
+        dict: Status of the completion.
+
+    Raises:
+        HTTPException: If API key is invalid or operation not found.
+    """
+    # Validate internal API key - reject if not configured or invalid
+    if not config.internal_api_key:
+        logger.error(
+            "Operation complete webhook rejected: CHAT_INTERNAL_API_KEY not configured"
+        )
+        raise HTTPException(
+            status_code=503,
+            detail="Webhook not available: internal API key not configured",
+        )
+    if x_api_key != config.internal_api_key:
+        raise HTTPException(status_code=401, detail="Invalid API key")
+
+    # Find task by operation_id
+    task = await stream_registry.find_task_by_operation_id(operation_id)
+    if task is None:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Operation {operation_id} not found",
+        )
+
+    logger.info(
+        f"Received completion webhook for operation {operation_id} "
+        f"(task_id={task.task_id}, success={request.success})"
+    )
+
+    if request.success:
+        await process_operation_success(task, request.result)
+    else:
+        await process_operation_failure(task, request.error)
+
+    return {"status": "ok", "task_id": task.task_id}
+
+
+# ========== Configuration ==========
+
+
+@router.get("/config/ttl", status_code=200)
+async def get_ttl_config() -> dict:
+    """
+    Get the stream TTL configuration.
+
+    Returns the Time-To-Live settings for chat streams, which determines
+    how long clients can reconnect to an active stream.
+
+    Returns:
+        dict: TTL configuration with seconds and milliseconds values.
+    """
+    return {
+        "stream_ttl_seconds": config.stream_ttl,
+        "stream_ttl_ms": config.stream_ttl * 1000,
+    }
+
+
 # ========== Health Check ==========
 
 
@@ -402,3 +966,43 @@ async def health_check() -> dict:
         "service": "chat",
         "version": "0.1.0",
     }
+
+
+# ========== Schema Export (for OpenAPI / Orval codegen) ==========
+
+ToolResponseUnion = (
+    AgentsFoundResponse
+    | NoResultsResponse
+    | AgentDetailsResponse
+    | SetupRequirementsResponse
+    | ExecutionStartedResponse
+    | NeedLoginResponse
+    | ErrorResponse
+    | InputValidationErrorResponse
+    | AgentOutputResponse
+    | UnderstandingUpdatedResponse
+    | AgentPreviewResponse
+    | AgentSavedResponse
+    | ClarificationNeededResponse
+    | BlockListResponse
+    | BlockDetailsResponse
+    | BlockOutputResponse
+    | DocSearchResultsResponse
+    | DocPageResponse
+    | OperationStartedResponse
+    | OperationPendingResponse
+    | OperationInProgressResponse
+)
+
+
+@router.get(
+    "/schema/tool-responses",
+    response_model=ToolResponseUnion,
+    include_in_schema=True,
+    summary="[Dummy] Tool response type export for codegen",
+    description="This endpoint is not meant to be called. It exists solely to "
+    "expose tool response models in the OpenAPI schema for frontend codegen.",
+)
+async def _tool_response_schema() -> ToolResponseUnion:  # type: ignore[return]
+    """Never called at runtime. Exists only so Orval generates TS types."""
+    raise HTTPException(status_code=501, detail="Schema-only endpoint")

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

@@ -1,82 +0,0 @@
-import logging
-from os import getenv
-
-import pytest
-
-from . import service as chat_service
-from .model import create_chat_session, get_chat_session, upsert_chat_session
-from .response_model import (
-    StreamError,
-    StreamFinish,
-    StreamTextDelta,
-    StreamToolOutputAvailable,
-)
-
-logger = logging.getLogger(__name__)
-
-
-@pytest.mark.asyncio(loop_scope="session")
-async def test_stream_chat_completion(setup_test_user, test_user_id):
-    """
-    Test the stream_chat_completion function.
-    """
-    api_key: str | None = getenv("OPEN_ROUTER_API_KEY")
-    if not api_key:
-        return pytest.skip("OPEN_ROUTER_API_KEY is not set, skipping test")
-
-    session = await create_chat_session(test_user_id)
-
-    has_errors = False
-    has_ended = False
-    assistant_message = ""
-    async for chunk in chat_service.stream_chat_completion(
-        session.session_id, "Hello, how are you?", user_id=session.user_id
-    ):
-        logger.info(chunk)
-        if isinstance(chunk, StreamError):
-            has_errors = True
-        if isinstance(chunk, StreamTextDelta):
-            assistant_message += chunk.delta
-        if isinstance(chunk, StreamFinish):
-            has_ended = True
-
-    assert has_ended, "Chat completion did not end"
-    assert not has_errors, "Error occurred while streaming chat completion"
-    assert assistant_message, "Assistant message is empty"
-
-
-@pytest.mark.asyncio(loop_scope="session")
-async def test_stream_chat_completion_with_tool_calls(setup_test_user, test_user_id):
-    """
-    Test the stream_chat_completion function.
-    """
-    api_key: str | None = getenv("OPEN_ROUTER_API_KEY")
-    if not api_key:
-        return pytest.skip("OPEN_ROUTER_API_KEY is not set, skipping test")
-
-    session = await create_chat_session(test_user_id)
-    session = await upsert_chat_session(session)
-
-    has_errors = False
-    has_ended = False
-    had_tool_calls = False
-    async for chunk in chat_service.stream_chat_completion(
-        session.session_id,
-        "Please find me an agent that can help me with my business. Use the query 'moneny printing agent'",
-        user_id=session.user_id,
-    ):
-        logger.info(chunk)
-        if isinstance(chunk, StreamError):
-            has_errors = True
-
-        if isinstance(chunk, StreamFinish):
-            has_ended = True
-        if isinstance(chunk, StreamToolOutputAvailable):
-            had_tool_calls = True
-
-    assert has_ended, "Chat completion did not end"
-    assert not has_errors, "Error occurred while streaming chat completion"
-    assert had_tool_calls, "Tool calls did not occur"
-    session = await get_chat_session(session.session_id)
-    assert session, "Session not found"
-    assert session.usage, "Usage is empty"

autogpt_platform/backend/backend/api/features/chat/tools/agent_generator/__init__.py

@@ -1,28 +0,0 @@
-"""Agent generator package - Creates agents from natural language."""
-
-from .core import (
-    AgentGeneratorNotConfiguredError,
-    decompose_goal,
-    generate_agent,
-    generate_agent_patch,
-    get_agent_as_json,
-    json_to_graph,
-    save_agent_to_library,
-)
-from .service import health_check as check_external_service_health
-from .service import is_external_service_configured
-
-__all__ = [
-    # Core functions
-    "decompose_goal",
-    "generate_agent",
-    "generate_agent_patch",
-    "save_agent_to_library",
-    "get_agent_as_json",
-    "json_to_graph",
-    # Exceptions
-    "AgentGeneratorNotConfiguredError",
-    # Service
-    "is_external_service_configured",
-    "check_external_service_health",
-]

autogpt_platform/backend/backend/api/features/chat/tools/agent_generator/core.py

@@ -1,277 +0,0 @@
-"""Core agent generation functions."""
-
-import logging
-import uuid
-from typing import Any
-
-from backend.api.features.library import db as library_db
-from backend.data.graph import Graph, Link, Node, create_graph
-
-from .service import (
-    decompose_goal_external,
-    generate_agent_external,
-    generate_agent_patch_external,
-    is_external_service_configured,
-)
-
-logger = logging.getLogger(__name__)
-
-
-class AgentGeneratorNotConfiguredError(Exception):
-    """Raised when the external Agent Generator service is not configured."""
-
-    pass
-
-
-def _check_service_configured() -> None:
-    """Check if the external Agent Generator service is configured.
-
-    Raises:
-        AgentGeneratorNotConfiguredError: If the service is not configured.
-    """
-    if not is_external_service_configured():
-        raise AgentGeneratorNotConfiguredError(
-            "Agent Generator service is not configured. "
-            "Set AGENTGENERATOR_HOST environment variable to enable agent generation."
-        )
-
-
-async def decompose_goal(description: str, context: str = "") -> dict[str, Any] | None:
-    """Break down a goal into steps or return clarifying questions.
-
-    Args:
-        description: Natural language goal description
-        context: Additional context (e.g., answers to previous questions)
-
-    Returns:
-        Dict with either:
-        - {"type": "clarifying_questions", "questions": [...]}
-        - {"type": "instructions", "steps": [...]}
-        Or None on error
-
-    Raises:
-        AgentGeneratorNotConfiguredError: If the external service is not configured.
-    """
-    _check_service_configured()
-    logger.info("Calling external Agent Generator service for decompose_goal")
-    return await decompose_goal_external(description, context)
-
-
-async def generate_agent(instructions: dict[str, Any]) -> dict[str, Any] | None:
-    """Generate agent JSON from instructions.
-
-    Args:
-        instructions: Structured instructions from decompose_goal
-
-    Returns:
-        Agent JSON dict or None on error
-
-    Raises:
-        AgentGeneratorNotConfiguredError: If the external service is not configured.
-    """
-    _check_service_configured()
-    logger.info("Calling external Agent Generator service for generate_agent")
-    result = await generate_agent_external(instructions)
-    if result:
-        # Ensure required fields
-        if "id" not in result:
-            result["id"] = str(uuid.uuid4())
-        if "version" not in result:
-            result["version"] = 1
-        if "is_active" not in result:
-            result["is_active"] = True
-    return result
-
-
-def json_to_graph(agent_json: dict[str, Any]) -> Graph:
-    """Convert agent JSON dict to Graph model.
-
-    Args:
-        agent_json: Agent JSON with nodes and links
-
-    Returns:
-        Graph ready for saving
-    """
-    nodes = []
-    for n in agent_json.get("nodes", []):
-        node = Node(
-            id=n.get("id", str(uuid.uuid4())),
-            block_id=n["block_id"],
-            input_default=n.get("input_default", {}),
-            metadata=n.get("metadata", {}),
-        )
-        nodes.append(node)
-
-    links = []
-    for link_data in agent_json.get("links", []):
-        link = Link(
-            id=link_data.get("id", str(uuid.uuid4())),
-            source_id=link_data["source_id"],
-            sink_id=link_data["sink_id"],
-            source_name=link_data["source_name"],
-            sink_name=link_data["sink_name"],
-            is_static=link_data.get("is_static", False),
-        )
-        links.append(link)
-
-    return Graph(
-        id=agent_json.get("id", str(uuid.uuid4())),
-        version=agent_json.get("version", 1),
-        is_active=agent_json.get("is_active", True),
-        name=agent_json.get("name", "Generated Agent"),
-        description=agent_json.get("description", ""),
-        nodes=nodes,
-        links=links,
-    )
-
-
-def _reassign_node_ids(graph: Graph) -> None:
-    """Reassign all node and link IDs to new UUIDs.
-
-    This is needed when creating a new version to avoid unique constraint violations.
-    """
-    # Create mapping from old node IDs to new UUIDs
-    id_map = {node.id: str(uuid.uuid4()) for node in graph.nodes}
-
-    # Reassign node IDs
-    for node in graph.nodes:
-        node.id = id_map[node.id]
-
-    # Update link references to use new node IDs
-    for link in graph.links:
-        link.id = str(uuid.uuid4())  # Also give links new IDs
-        if link.source_id in id_map:
-            link.source_id = id_map[link.source_id]
-        if link.sink_id in id_map:
-            link.sink_id = id_map[link.sink_id]
-
-
-async def save_agent_to_library(
-    agent_json: dict[str, Any], user_id: str, is_update: bool = False
-) -> tuple[Graph, Any]:
-    """Save agent to database and user's library.
-
-    Args:
-        agent_json: Agent JSON dict
-        user_id: User ID
-        is_update: Whether this is an update to an existing agent
-
-    Returns:
-        Tuple of (created Graph, LibraryAgent)
-    """
-    from backend.data.graph import get_graph_all_versions
-
-    graph = json_to_graph(agent_json)
-
-    if is_update:
-        # For updates, keep the same graph ID but increment version
-        # and reassign node/link IDs to avoid conflicts
-        if graph.id:
-            existing_versions = await get_graph_all_versions(graph.id, user_id)
-            if existing_versions:
-                latest_version = max(v.version for v in existing_versions)
-                graph.version = latest_version + 1
-                # Reassign node IDs (but keep graph ID the same)
-                _reassign_node_ids(graph)
-                logger.info(f"Updating agent {graph.id} to version {graph.version}")
-    else:
-        # For new agents, always generate a fresh UUID to avoid collisions
-        graph.id = str(uuid.uuid4())
-        graph.version = 1
-        # Reassign all node IDs as well
-        _reassign_node_ids(graph)
-        logger.info(f"Creating new agent with ID {graph.id}")
-
-    # Save to database
-    created_graph = await create_graph(graph, user_id)
-
-    # Add to user's library (or update existing library agent)
-    library_agents = await library_db.create_library_agent(
-        graph=created_graph,
-        user_id=user_id,
-        sensitive_action_safe_mode=True,
-        create_library_agents_for_sub_graphs=False,
-    )
-
-    return created_graph, library_agents[0]
-
-
-async def get_agent_as_json(
-    graph_id: str, user_id: str | None
-) -> dict[str, Any] | None:
-    """Fetch an agent and convert to JSON format for editing.
-
-    Args:
-        graph_id: Graph ID or library agent ID
-        user_id: User ID
-
-    Returns:
-        Agent as JSON dict or None if not found
-    """
-    from backend.data.graph import get_graph
-
-    # Try to get the graph (version=None gets the active version)
-    graph = await get_graph(graph_id, version=None, user_id=user_id)
-    if not graph:
-        return None
-
-    # Convert to JSON format
-    nodes = []
-    for node in graph.nodes:
-        nodes.append(
-            {
-                "id": node.id,
-                "block_id": node.block_id,
-                "input_default": node.input_default,
-                "metadata": node.metadata,
-            }
-        )
-
-    links = []
-    for node in graph.nodes:
-        for link in node.output_links:
-            links.append(
-                {
-                    "id": link.id,
-                    "source_id": link.source_id,
-                    "sink_id": link.sink_id,
-                    "source_name": link.source_name,
-                    "sink_name": link.sink_name,
-                    "is_static": link.is_static,
-                }
-            )
-
-    return {
-        "id": graph.id,
-        "name": graph.name,
-        "description": graph.description,
-        "version": graph.version,
-        "is_active": graph.is_active,
-        "nodes": nodes,
-        "links": links,
-    }
-
-
-async def generate_agent_patch(
-    update_request: str, current_agent: dict[str, Any]
-) -> dict[str, Any] | None:
-    """Update an existing agent using natural language.
-
-    The external Agent Generator service handles:
-    - Generating the patch
-    - Applying the patch
-    - Fixing and validating the result
-
-    Args:
-        update_request: Natural language description of changes
-        current_agent: Current agent JSON
-
-    Returns:
-        Updated agent JSON, clarifying questions dict, or None on error
-
-    Raises:
-        AgentGeneratorNotConfiguredError: If the external service is not configured.
-    """
-    _check_service_configured()
-    logger.info("Calling external Agent Generator service for generate_agent_patch")
-    return await generate_agent_patch_external(update_request, current_agent)

autogpt_platform/backend/backend/api/features/chat/tools/agent_generator/service.py

@@ -1,269 +0,0 @@
-"""External Agent Generator service client.
-
-This module provides a client for communicating with the external Agent Generator
-microservice. When AGENTGENERATOR_HOST is configured, the agent generation functions
-will delegate to the external service instead of using the built-in LLM-based implementation.
-"""
-
-import logging
-from typing import Any
-
-import httpx
-
-from backend.util.settings import Settings
-
-logger = logging.getLogger(__name__)
-
-_client: httpx.AsyncClient | None = None
-_settings: Settings | None = None
-
-
-def _get_settings() -> Settings:
-    """Get or create settings singleton."""
-    global _settings
-    if _settings is None:
-        _settings = Settings()
-    return _settings
-
-
-def is_external_service_configured() -> bool:
-    """Check if external Agent Generator service is configured."""
-    settings = _get_settings()
-    return bool(settings.config.agentgenerator_host)
-
-
-def _get_base_url() -> str:
-    """Get the base URL for the external service."""
-    settings = _get_settings()
-    host = settings.config.agentgenerator_host
-    port = settings.config.agentgenerator_port
-    return f"http://{host}:{port}"
-
-
-def _get_client() -> httpx.AsyncClient:
-    """Get or create the HTTP client for the external service."""
-    global _client
-    if _client is None:
-        settings = _get_settings()
-        _client = httpx.AsyncClient(
-            base_url=_get_base_url(),
-            timeout=httpx.Timeout(settings.config.agentgenerator_timeout),
-        )
-    return _client
-
-
-async def decompose_goal_external(
-    description: str, context: str = ""
-) -> dict[str, Any] | None:
-    """Call the external service to decompose a goal.
-
-    Args:
-        description: Natural language goal description
-        context: Additional context (e.g., answers to previous questions)
-
-    Returns:
-        Dict with either:
-        - {"type": "clarifying_questions", "questions": [...]}
-        - {"type": "instructions", "steps": [...]}
-        - {"type": "unachievable_goal", ...}
-        - {"type": "vague_goal", ...}
-        Or None on error
-    """
-    client = _get_client()
-
-    # Build the request payload
-    payload: dict[str, Any] = {"description": description}
-    if context:
-        # The external service uses user_instruction for additional context
-        payload["user_instruction"] = context
-
-    try:
-        response = await client.post("/api/decompose-description", json=payload)
-        response.raise_for_status()
-        data = response.json()
-
-        if not data.get("success"):
-            logger.error(f"External service returned error: {data.get('error')}")
-            return None
-
-        # Map the response to the expected format
-        response_type = data.get("type")
-        if response_type == "instructions":
-            return {"type": "instructions", "steps": data.get("steps", [])}
-        elif response_type == "clarifying_questions":
-            return {
-                "type": "clarifying_questions",
-                "questions": data.get("questions", []),
-            }
-        elif response_type == "unachievable_goal":
-            return {
-                "type": "unachievable_goal",
-                "reason": data.get("reason"),
-                "suggested_goal": data.get("suggested_goal"),
-            }
-        elif response_type == "vague_goal":
-            return {
-                "type": "vague_goal",
-                "suggested_goal": data.get("suggested_goal"),
-            }
-        else:
-            logger.error(
-                f"Unknown response type from external service: {response_type}"
-            )
-            return None
-
-    except httpx.HTTPStatusError as e:
-        logger.error(f"HTTP error calling external agent generator: {e}")
-        return None
-    except httpx.RequestError as e:
-        logger.error(f"Request error calling external agent generator: {e}")
-        return None
-    except Exception as e:
-        logger.error(f"Unexpected error calling external agent generator: {e}")
-        return None
-
-
-async def generate_agent_external(
-    instructions: dict[str, Any]
-) -> dict[str, Any] | None:
-    """Call the external service to generate an agent from instructions.
-
-    Args:
-        instructions: Structured instructions from decompose_goal
-
-    Returns:
-        Agent JSON dict or None on error
-    """
-    client = _get_client()
-
-    try:
-        response = await client.post(
-            "/api/generate-agent", json={"instructions": instructions}
-        )
-        response.raise_for_status()
-        data = response.json()
-
-        if not data.get("success"):
-            logger.error(f"External service returned error: {data.get('error')}")
-            return None
-
-        return data.get("agent_json")
-
-    except httpx.HTTPStatusError as e:
-        logger.error(f"HTTP error calling external agent generator: {e}")
-        return None
-    except httpx.RequestError as e:
-        logger.error(f"Request error calling external agent generator: {e}")
-        return None
-    except Exception as e:
-        logger.error(f"Unexpected error calling external agent generator: {e}")
-        return None
-
-
-async def generate_agent_patch_external(
-    update_request: str, current_agent: dict[str, Any]
-) -> dict[str, Any] | None:
-    """Call the external service to generate a patch for an existing agent.
-
-    Args:
-        update_request: Natural language description of changes
-        current_agent: Current agent JSON
-
-    Returns:
-        Updated agent JSON, clarifying questions dict, or None on error
-    """
-    client = _get_client()
-
-    try:
-        response = await client.post(
-            "/api/update-agent",
-            json={
-                "update_request": update_request,
-                "current_agent_json": current_agent,
-            },
-        )
-        response.raise_for_status()
-        data = response.json()
-
-        if not data.get("success"):
-            logger.error(f"External service returned error: {data.get('error')}")
-            return None
-
-        # Check if it's clarifying questions
-        if data.get("type") == "clarifying_questions":
-            return {
-                "type": "clarifying_questions",
-                "questions": data.get("questions", []),
-            }
-
-        # Otherwise return the updated agent JSON
-        return data.get("agent_json")
-
-    except httpx.HTTPStatusError as e:
-        logger.error(f"HTTP error calling external agent generator: {e}")
-        return None
-    except httpx.RequestError as e:
-        logger.error(f"Request error calling external agent generator: {e}")
-        return None
-    except Exception as e:
-        logger.error(f"Unexpected error calling external agent generator: {e}")
-        return None
-
-
-async def get_blocks_external() -> list[dict[str, Any]] | None:
-    """Get available blocks from the external service.
-
-    Returns:
-        List of block info dicts or None on error
-    """
-    client = _get_client()
-
-    try:
-        response = await client.get("/api/blocks")
-        response.raise_for_status()
-        data = response.json()
-
-        if not data.get("success"):
-            logger.error("External service returned error getting blocks")
-            return None
-
-        return data.get("blocks", [])
-
-    except httpx.HTTPStatusError as e:
-        logger.error(f"HTTP error getting blocks from external service: {e}")
-        return None
-    except httpx.RequestError as e:
-        logger.error(f"Request error getting blocks from external service: {e}")
-        return None
-    except Exception as e:
-        logger.error(f"Unexpected error getting blocks from external service: {e}")
-        return None
-
-
-async def health_check() -> bool:
-    """Check if the external service is healthy.
-
-    Returns:
-        True if healthy, False otherwise
-    """
-    if not is_external_service_configured():
-        return False
-
-    client = _get_client()
-
-    try:
-        response = await client.get("/health")
-        response.raise_for_status()
-        data = response.json()
-        return data.get("status") == "healthy" and data.get("blocks_loaded", False)
-    except Exception as e:
-        logger.warning(f"External agent generator health check failed: {e}")
-        return False
-
-
-async def close_client() -> None:
-    """Close the HTTP client."""
-    global _client
-    if _client is not None:
-        await _client.aclose()
-        _client = None

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

@@ -1,203 +0,0 @@
-"""Shared agent search functionality for find_agent and find_library_agent tools."""
-
-import asyncio
-import logging
-from typing import Literal
-
-from backend.api.features.library import db as library_db
-from backend.api.features.store import db as store_db
-from backend.data import graph as graph_db
-from backend.data.graph import GraphModel
-from backend.util.exceptions import DatabaseError, NotFoundError
-
-from .models import (
-    AgentInfo,
-    AgentsFoundResponse,
-    ErrorResponse,
-    NoResultsResponse,
-    ToolResponseBase,
-)
-from .utils import fetch_graph_from_store_slug
-
-logger = logging.getLogger(__name__)
-
-SearchSource = Literal["marketplace", "library"]
-
-
-async def search_agents(
-    query: str,
-    source: SearchSource,
-    session_id: str | None,
-    user_id: str | None = None,
-) -> ToolResponseBase:
-    """
-    Search for agents in marketplace or user library.
-
-    Args:
-        query: Search query string
-        source: "marketplace" or "library"
-        session_id: Chat session ID
-        user_id: User ID (required for library search)
-
-    Returns:
-        AgentsFoundResponse, NoResultsResponse, or ErrorResponse
-    """
-    if not query:
-        return ErrorResponse(
-            message="Please provide a search query", session_id=session_id
-        )
-
-    if source == "library" and not user_id:
-        return ErrorResponse(
-            message="User authentication required to search library",
-            session_id=session_id,
-        )
-
-    agents: list[AgentInfo] = []
-    try:
-        if source == "marketplace":
-            logger.info(f"Searching marketplace for: {query}")
-            results = await store_db.get_store_agents(search_query=query, page_size=5)
-
-            # Fetch all graphs in parallel for better performance
-            async def fetch_marketplace_graph(
-                creator: str, slug: str
-            ) -> GraphModel | None:
-                try:
-                    graph, _ = await fetch_graph_from_store_slug(creator, slug)
-                    return graph
-                except Exception as e:
-                    logger.warning(
-                        f"Failed to fetch input schema for {creator}/{slug}: {e}"
-                    )
-                    return None
-
-            graphs = await asyncio.gather(
-                *(
-                    fetch_marketplace_graph(agent.creator, agent.slug)
-                    for agent in results.agents
-                )
-            )
-
-            for agent, graph in zip(results.agents, graphs):
-                agents.append(
-                    AgentInfo(
-                        id=f"{agent.creator}/{agent.slug}",
-                        name=agent.agent_name,
-                        description=agent.description or "",
-                        source="marketplace",
-                        in_library=False,
-                        creator=agent.creator,
-                        category="general",
-                        rating=agent.rating,
-                        runs=agent.runs,
-                        is_featured=False,
-                        inputs=graph.input_schema if graph else None,
-                    )
-                )
-        else:  # library
-            logger.info(f"Searching user library for: {query}")
-            results = await library_db.list_library_agents(
-                user_id=user_id,  # type: ignore[arg-type]
-                search_term=query,
-                page_size=10,
-            )
-
-            # Fetch all graphs in parallel for better performance
-            # (list_library_agents doesn't include nodes for performance)
-            async def fetch_library_graph(
-                graph_id: str, graph_version: int
-            ) -> GraphModel | None:
-                try:
-                    return await graph_db.get_graph(
-                        graph_id=graph_id,
-                        version=graph_version,
-                        user_id=user_id,
-                    )
-                except Exception as e:
-                    logger.warning(
-                        f"Failed to fetch input schema for graph {graph_id}: {e}"
-                    )
-                    return None
-
-            graphs = await asyncio.gather(
-                *(
-                    fetch_library_graph(agent.graph_id, agent.graph_version)
-                    for agent in results.agents
-                )
-            )
-
-            for agent, graph in zip(results.agents, graphs):
-                agents.append(
-                    AgentInfo(
-                        id=agent.id,
-                        name=agent.name,
-                        description=agent.description or "",
-                        source="library",
-                        in_library=True,
-                        creator=agent.creator_name,
-                        status=agent.status.value,
-                        can_access_graph=agent.can_access_graph,
-                        has_external_trigger=agent.has_external_trigger,
-                        new_output=agent.new_output,
-                        graph_id=agent.graph_id,
-                        inputs=graph.input_schema if graph else None,
-                    )
-                )
-        logger.info(f"Found {len(agents)} agents in {source}")
-    except NotFoundError:
-        pass
-    except DatabaseError as e:
-        logger.error(f"Error searching {source}: {e}", exc_info=True)
-        return ErrorResponse(
-            message=f"Failed to search {source}. Please try again.",
-            error=str(e),
-            session_id=session_id,
-        )
-
-    if not agents:
-        suggestions = (
-            [
-                "Try more general terms",
-                "Browse categories in the marketplace",
-                "Check spelling",
-            ]
-            if source == "marketplace"
-            else [
-                "Try different keywords",
-                "Use find_agent to search the marketplace",
-                "Check your library at /library",
-            ]
-        )
-        no_results_msg = (
-            f"No agents found matching '{query}'. Try different keywords or browse the marketplace."
-            if source == "marketplace"
-            else f"No agents matching '{query}' found in your library."
-        )
-        return NoResultsResponse(
-            message=no_results_msg, session_id=session_id, suggestions=suggestions
-        )
-
-    title = f"Found {len(agents)} agent{'s' if len(agents) != 1 else ''} "
-    title += (
-        f"for '{query}'"
-        if source == "marketplace"
-        else f"in your library for '{query}'"
-    )
-
-    message = (
-        "Now you have found some options for the user to choose from. "
-        "You can add a link to a recommended agent at: /marketplace/agent/agent_id "
-        "Please ask the user if they would like to use any of these agents."
-        if source == "marketplace"
-        else "Found agents in the user's library. You can provide a link to view an agent at: "
-        "/library/agents/{agent_id}. Use agent_output to get execution results, or run_agent to execute."
-    )
-
-    return AgentsFoundResponse(
-        message=message,
-        title=title,
-        agents=agents,
-        count=len(agents),
-        session_id=session_id,
-    )

autogpt_platform/backend/backend/api/features/integrations/router.py

@@ -1,7 +1,7 @@
 import asyncio
 import logging
 from datetime import datetime, timedelta, timezone
-from typing import TYPE_CHECKING, Annotated, List, Literal
+from typing import TYPE_CHECKING, Annotated, Any, List, Literal
 
 from autogpt_libs.auth import get_user_id
 from fastapi import (
@@ -14,7 +14,7 @@ from fastapi import (
     Security,
     status,
 )
-from pydantic import BaseModel, Field, SecretStr
+from pydantic import BaseModel, Field, SecretStr, model_validator
 from starlette.status import HTTP_500_INTERNAL_SERVER_ERROR, HTTP_502_BAD_GATEWAY
 
 from backend.api.features.library.db import set_preset_webhook, update_preset
@@ -39,7 +39,11 @@ from backend.data.onboarding import OnboardingStep, complete_onboarding_step
 from backend.data.user import get_user_integrations
 from backend.executor.utils import add_graph_execution
 from backend.integrations.ayrshare import AyrshareClient, SocialPlatform
-from backend.integrations.creds_manager import IntegrationCredentialsManager
+from backend.integrations.credentials_store import provider_matches
+from backend.integrations.creds_manager import (
+    IntegrationCredentialsManager,
+    create_mcp_oauth_handler,
+)
 from backend.integrations.oauth import CREDENTIALS_BY_PROVIDER, HANDLERS_BY_NAME
 from backend.integrations.providers import ProviderName
 from backend.integrations.webhooks import get_webhook_manager
@@ -102,9 +106,37 @@ class CredentialsMetaResponse(BaseModel):
     scopes: list[str] | None
     username: str | None
     host: str | None = Field(
-        default=None, description="Host pattern for host-scoped credentials"
+        default=None,
+        description="Host pattern for host-scoped or MCP server URL for MCP credentials",
     )
 
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_provider(cls, data: Any) -> Any:
+        """Fix ``ProviderName.X`` format from Python 3.13 ``str(Enum)`` bug."""
+        if isinstance(data, dict):
+            prov = data.get("provider", "")
+            if isinstance(prov, str) and prov.startswith("ProviderName."):
+                member = prov.removeprefix("ProviderName.")
+                try:
+                    data = {**data, "provider": ProviderName[member].value}
+                except KeyError:
+                    pass
+        return data
+
+    @staticmethod
+    def get_host(cred: Credentials) -> str | None:
+        """Extract host from credential: HostScoped host or MCP server URL."""
+        if isinstance(cred, HostScopedCredentials):
+            return cred.host
+        if isinstance(cred, OAuth2Credentials) and cred.provider in (
+            ProviderName.MCP,
+            ProviderName.MCP.value,
+            "ProviderName.MCP",
+        ):
+            return (cred.metadata or {}).get("mcp_server_url")
+        return None
+
 
 @router.post("/{provider}/callback", summary="Exchange OAuth code for tokens")
 async def callback(
@@ -179,9 +211,7 @@ async def callback(
         title=credentials.title,
         scopes=credentials.scopes,
         username=credentials.username,
-        host=(
-            credentials.host if isinstance(credentials, HostScopedCredentials) else None
-        ),
+        host=(CredentialsMetaResponse.get_host(credentials)),
     )
 
 
@@ -199,7 +229,7 @@ async def list_credentials(
             title=cred.title,
             scopes=cred.scopes if isinstance(cred, OAuth2Credentials) else None,
             username=cred.username if isinstance(cred, OAuth2Credentials) else None,
-            host=cred.host if isinstance(cred, HostScopedCredentials) else None,
+            host=CredentialsMetaResponse.get_host(cred),
         )
         for cred in credentials
     ]
@@ -222,7 +252,7 @@ async def list_credentials_by_provider(
             title=cred.title,
             scopes=cred.scopes if isinstance(cred, OAuth2Credentials) else None,
             username=cred.username if isinstance(cred, OAuth2Credentials) else None,
-            host=cred.host if isinstance(cred, HostScopedCredentials) else None,
+            host=CredentialsMetaResponse.get_host(cred),
         )
         for cred in credentials
     ]
@@ -322,7 +352,11 @@ async def delete_credentials(
 
     tokens_revoked = None
     if isinstance(creds, OAuth2Credentials):
-        handler = _get_provider_oauth_handler(request, provider)
+        if provider_matches(provider.value, ProviderName.MCP.value):
+            # MCP uses dynamic per-server OAuth — create handler from metadata
+            handler = create_mcp_oauth_handler(creds)
+        else:
+            handler = _get_provider_oauth_handler(request, provider)
         tokens_revoked = await handler.revoke_tokens(creds)
 
     return CredentialsDeletionResponse(revoked=tokens_revoked)

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

@@ -12,14 +12,16 @@ 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
 import backend.data.integrations as integrations_db
-from backend.data.block import BlockInput
 from backend.data.db import transaction
 from backend.data.execution import get_graph_execution
 from backend.data.graph import GraphSettings
 from backend.data.includes import AGENT_PRESET_INCLUDE, library_agent_include
-from backend.data.model import CredentialsMetaInput
+from backend.data.model import CredentialsMetaInput, GraphInput
 from backend.integrations.creds_manager import IntegrationCredentialsManager
-from backend.integrations.webhooks.graph_lifecycle_hooks import on_graph_activate
+from backend.integrations.webhooks.graph_lifecycle_hooks import (
+    on_graph_activate,
+    on_graph_deactivate,
+)
 from backend.util.clients import get_scheduler_client
 from backend.util.exceptions import DatabaseError, InvalidInputError, NotFoundError
 from backend.util.json import SafeJson
@@ -39,6 +41,7 @@ async def list_library_agents(
     sort_by: library_model.LibraryAgentSort = library_model.LibraryAgentSort.UPDATED_AT,
     page: int = 1,
     page_size: int = 50,
+    include_executions: bool = False,
 ) -> library_model.LibraryAgentResponse:
     """
     Retrieves a paginated list of LibraryAgent records for a given user.
@@ -49,6 +52,9 @@ async def list_library_agents(
         sort_by: Sorting field (createdAt, updatedAt, isFavorite, isCreatedByUser).
         page: Current page (1-indexed).
         page_size: Number of items per page.
+        include_executions: Whether to include execution data for status calculation.
+            Defaults to False for performance (UI fetches status separately).
+            Set to True when accurate status/metrics are needed (e.g., agent generator).
 
     Returns:
         A LibraryAgentResponse containing the list of agents and pagination details.
@@ -76,7 +82,6 @@ async def list_library_agents(
         "isArchived": False,
     }
 
-    # Build search filter if applicable
     if search_term:
         where_clause["OR"] = [
             {
@@ -93,7 +98,6 @@ async def list_library_agents(
             },
         ]
 
-    # Determine sorting
     order_by: prisma.types.LibraryAgentOrderByInput | None = None
 
     if sort_by == library_model.LibraryAgentSort.CREATED_AT:
@@ -105,7 +109,7 @@ async def list_library_agents(
         library_agents = await prisma.models.LibraryAgent.prisma().find_many(
             where=where_clause,
             include=library_agent_include(
-                user_id, include_nodes=False, include_executions=False
+                user_id, include_nodes=False, include_executions=include_executions
             ),
             order=order_by,
             skip=(page - 1) * page_size,
@@ -369,7 +373,7 @@ async def get_library_agent_by_graph_id(
 
 
 async def add_generated_agent_image(
-    graph: graph_db.BaseGraph,
+    graph: graph_db.GraphBaseMeta,
     user_id: str,
     library_agent_id: str,
 ) -> Optional[prisma.models.LibraryAgent]:
@@ -535,6 +539,92 @@ async def update_agent_version_in_library(
     return library_model.LibraryAgent.from_db(lib)
 
 
+async def create_graph_in_library(
+    graph: graph_db.Graph,
+    user_id: str,
+) -> tuple[graph_db.GraphModel, library_model.LibraryAgent]:
+    """Create a new graph and add it to the user's library."""
+    graph.version = 1
+    graph_model = graph_db.make_graph_model(graph, user_id)
+    graph_model.reassign_ids(user_id=user_id, reassign_graph_id=True)
+
+    created_graph = await graph_db.create_graph(graph_model, user_id)
+
+    library_agents = await create_library_agent(
+        graph=created_graph,
+        user_id=user_id,
+        sensitive_action_safe_mode=True,
+        create_library_agents_for_sub_graphs=False,
+    )
+
+    if created_graph.is_active:
+        created_graph = await on_graph_activate(created_graph, user_id=user_id)
+
+    return created_graph, library_agents[0]
+
+
+async def update_graph_in_library(
+    graph: graph_db.Graph,
+    user_id: str,
+) -> tuple[graph_db.GraphModel, library_model.LibraryAgent]:
+    """Create a new version of an existing graph and update the library entry."""
+    existing_versions = await graph_db.get_graph_all_versions(graph.id, user_id)
+    current_active_version = (
+        next((v for v in existing_versions if v.is_active), None)
+        if existing_versions
+        else None
+    )
+    graph.version = (
+        max(v.version for v in existing_versions) + 1 if existing_versions else 1
+    )
+
+    graph_model = graph_db.make_graph_model(graph, user_id)
+    graph_model.reassign_ids(user_id=user_id, reassign_graph_id=False)
+
+    created_graph = await graph_db.create_graph(graph_model, user_id)
+
+    library_agent = await get_library_agent_by_graph_id(user_id, created_graph.id)
+    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
+    )
+
+    if created_graph.is_active:
+        created_graph = await on_graph_activate(created_graph, user_id=user_id)
+        await graph_db.set_graph_active_version(
+            graph_id=created_graph.id,
+            version=created_graph.version,
+            user_id=user_id,
+        )
+        if current_active_version:
+            await on_graph_deactivate(current_active_version, user_id=user_id)
+
+    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,
@@ -1039,7 +1129,7 @@ async def create_preset_from_graph_execution(
 async def update_preset(
     user_id: str,
     preset_id: str,
-    inputs: Optional[BlockInput] = None,
+    inputs: Optional[GraphInput] = None,
     credentials: Optional[dict[str, CredentialsMetaInput]] = None,
     name: Optional[str] = None,
     description: Optional[str] = None,

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

@@ -6,9 +6,13 @@ import prisma.enums
 import prisma.models
 import pydantic
 
-from backend.data.block import BlockInput
 from backend.data.graph import GraphModel, GraphSettings, GraphTriggerInfo
-from backend.data.model import CredentialsMetaInput, is_credentials_field_name
+from backend.data.model import (
+    CredentialsMetaInput,
+    GraphInput,
+    is_credentials_field_name,
+)
+from backend.util.json import loads as json_loads
 from backend.util.models import Pagination
 
 if TYPE_CHECKING:
@@ -16,10 +20,10 @@ if TYPE_CHECKING:
 
 
 class LibraryAgentStatus(str, Enum):
-    COMPLETED = "COMPLETED"  # All runs completed
-    HEALTHY = "HEALTHY"  # Agent is running (not all runs have completed)
-    WAITING = "WAITING"  # Agent is queued or waiting to start
-    ERROR = "ERROR"  # Agent is in an error state
+    COMPLETED = "COMPLETED"
+    HEALTHY = "HEALTHY"
+    WAITING = "WAITING"
+    ERROR = "ERROR"
 
 
 class MarketplaceListingCreator(pydantic.BaseModel):
@@ -39,6 +43,30 @@ class MarketplaceListing(pydantic.BaseModel):
     creator: MarketplaceListingCreator
 
 
+class RecentExecution(pydantic.BaseModel):
+    """Summary of a recent execution for quality assessment.
+
+    Used by the LLM to understand the agent's recent performance with specific examples
+    rather than just aggregate statistics.
+    """
+
+    status: str
+    correctness_score: float | None = None
+    activity_summary: str | None = None
+
+
+def _parse_settings(settings: dict | str | None) -> GraphSettings:
+    """Parse settings from database, handling both dict and string formats."""
+    if settings is None:
+        return GraphSettings()
+    try:
+        if isinstance(settings, str):
+            settings = json_loads(settings)
+        return GraphSettings.model_validate(settings)
+    except Exception:
+        return GraphSettings()
+
+
 class LibraryAgent(pydantic.BaseModel):
     """
     Represents an agent in the library, including metadata for display and
@@ -48,7 +76,7 @@ class LibraryAgent(pydantic.BaseModel):
     id: str
     graph_id: str
     graph_version: int
-    owner_user_id: str  # ID of user who owns/created this agent graph
+    owner_user_id: str
 
     image_url: str | None
 
@@ -64,7 +92,7 @@ class LibraryAgent(pydantic.BaseModel):
     description: str
     instructions: str | None = None
 
-    input_schema: dict[str, Any]  # Should be BlockIOObjectSubSchema in frontend
+    input_schema: dict[str, Any]
     output_schema: dict[str, Any]
     credentials_input_schema: dict[str, Any] | None = pydantic.Field(
         description="Input schema for credentials required by the agent",
@@ -81,25 +109,19 @@ class LibraryAgent(pydantic.BaseModel):
     )
     trigger_setup_info: Optional[GraphTriggerInfo] = None
 
-    # Indicates whether there's a new output (based on recent runs)
     new_output: bool
-
-    # Whether the user can access the underlying graph
+    execution_count: int = 0
+    success_rate: float | None = None
+    avg_correctness_score: float | None = None
+    recent_executions: list[RecentExecution] = pydantic.Field(
+        default_factory=list,
+        description="List of recent executions with status, score, and summary",
+    )
     can_access_graph: bool
-
-    # Indicates if this agent is the latest version
     is_latest_version: bool
-
-    # Whether the agent is marked as favorite by the user
     is_favorite: bool
-
-    # Recommended schedule cron (from marketplace agents)
     recommended_schedule_cron: str | None = None
-
-    # User-specific settings for this library agent
     settings: GraphSettings = pydantic.Field(default_factory=GraphSettings)
-
-    # Marketplace listing information if the agent has been published
     marketplace_listing: Optional["MarketplaceListing"] = None
 
     @staticmethod
@@ -123,7 +145,6 @@ class LibraryAgent(pydantic.BaseModel):
         agent_updated_at = agent.AgentGraph.updatedAt
         lib_agent_updated_at = agent.updatedAt
 
-        # Compute updated_at as the latest between library agent and graph
         updated_at = (
             max(agent_updated_at, lib_agent_updated_at)
             if agent_updated_at
@@ -136,7 +157,6 @@ class LibraryAgent(pydantic.BaseModel):
             creator_name = agent.Creator.name or "Unknown"
             creator_image_url = agent.Creator.avatarUrl or ""
 
-        # Logic to calculate status and new_output
         week_ago = datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(
             days=7
         )
@@ -145,13 +165,55 @@ class LibraryAgent(pydantic.BaseModel):
         status = status_result.status
         new_output = status_result.new_output
 
-        # Check if user can access the graph
-        can_access_graph = agent.AgentGraph.userId == agent.userId
+        execution_count = len(executions)
+        success_rate: float | None = None
+        avg_correctness_score: float | None = None
+        if execution_count > 0:
+            success_count = sum(
+                1
+                for e in executions
+                if e.executionStatus == prisma.enums.AgentExecutionStatus.COMPLETED
+            )
+            success_rate = (success_count / execution_count) * 100
 
-        # Hard-coded to True until a method to check is implemented
+            correctness_scores = []
+            for e in executions:
+                if e.stats and isinstance(e.stats, dict):
+                    score = e.stats.get("correctness_score")
+                    if score is not None and isinstance(score, (int, float)):
+                        correctness_scores.append(float(score))
+            if correctness_scores:
+                avg_correctness_score = sum(correctness_scores) / len(
+                    correctness_scores
+                )
+
+        recent_executions: list[RecentExecution] = []
+        for e in executions:
+            exec_score: float | None = None
+            exec_summary: str | None = None
+            if e.stats and isinstance(e.stats, dict):
+                score = e.stats.get("correctness_score")
+                if score is not None and isinstance(score, (int, float)):
+                    exec_score = float(score)
+                summary = e.stats.get("activity_status")
+                if summary is not None and isinstance(summary, str):
+                    exec_summary = summary
+            exec_status = (
+                e.executionStatus.value
+                if hasattr(e.executionStatus, "value")
+                else str(e.executionStatus)
+            )
+            recent_executions.append(
+                RecentExecution(
+                    status=exec_status,
+                    correctness_score=exec_score,
+                    activity_summary=exec_summary,
+                )
+            )
+
+        can_access_graph = agent.AgentGraph.userId == agent.userId
         is_latest_version = True
 
-        # Build marketplace_listing if available
         marketplace_listing_data = None
         if store_listing and store_listing.ActiveVersion and profile:
             creator_data = MarketplaceListingCreator(
@@ -190,11 +252,15 @@ class LibraryAgent(pydantic.BaseModel):
             has_sensitive_action=graph.has_sensitive_action,
             trigger_setup_info=graph.trigger_setup_info,
             new_output=new_output,
+            execution_count=execution_count,
+            success_rate=success_rate,
+            avg_correctness_score=avg_correctness_score,
+            recent_executions=recent_executions,
             can_access_graph=can_access_graph,
             is_latest_version=is_latest_version,
             is_favorite=agent.isFavorite,
             recommended_schedule_cron=agent.AgentGraph.recommendedScheduleCron,
-            settings=GraphSettings.model_validate(agent.settings),
+            settings=_parse_settings(agent.settings),
             marketplace_listing=marketplace_listing_data,
         )
 
@@ -220,18 +286,15 @@ def _calculate_agent_status(
     if not executions:
         return AgentStatusResult(status=LibraryAgentStatus.COMPLETED, new_output=False)
 
-    # Track how many times each execution status appears
     status_counts = {status: 0 for status in prisma.enums.AgentExecutionStatus}
     new_output = False
 
     for execution in executions:
-        # Check if there's a completed run more recent than `recent_threshold`
         if execution.createdAt >= recent_threshold:
             if execution.executionStatus == prisma.enums.AgentExecutionStatus.COMPLETED:
                 new_output = True
         status_counts[execution.executionStatus] += 1
 
-    # Determine the final status based on counts
     if status_counts[prisma.enums.AgentExecutionStatus.FAILED] > 0:
         return AgentStatusResult(status=LibraryAgentStatus.ERROR, new_output=new_output)
     elif status_counts[prisma.enums.AgentExecutionStatus.QUEUED] > 0:
@@ -263,7 +326,7 @@ class LibraryAgentPresetCreatable(pydantic.BaseModel):
     graph_id: str
     graph_version: int
 
-    inputs: BlockInput
+    inputs: GraphInput
     credentials: dict[str, CredentialsMetaInput]
 
     name: str
@@ -292,7 +355,7 @@ class LibraryAgentPresetUpdatable(pydantic.BaseModel):
     Request model used when updating a preset for a library agent.
     """
 
-    inputs: Optional[BlockInput] = None
+    inputs: Optional[GraphInput] = None
     credentials: Optional[dict[str, CredentialsMetaInput]] = None
 
     name: Optional[str] = None
@@ -335,7 +398,7 @@ class LibraryAgentPreset(LibraryAgentPresetCreatable):
                 "Webhook must be included in AgentPreset query when webhookId is set"
             )
 
-        input_data: BlockInput = {}
+        input_data: GraphInput = {}
         input_credentials: dict[str, CredentialsMetaInput] = {}
 
         for preset_input in preset.InputPresets:

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

@@ -0,0 +1,404 @@
+"""
+MCP (Model Context Protocol) API routes.
+
+Provides endpoints for MCP tool discovery and OAuth authentication so the
+frontend can list available tools on an MCP server before placing a block.
+"""
+
+import logging
+from typing import Annotated, Any
+from urllib.parse import urlparse
+
+import fastapi
+from autogpt_libs.auth import get_user_id
+from fastapi import Security
+from pydantic import BaseModel, Field
+
+from backend.api.features.integrations.router import CredentialsMetaResponse
+from backend.blocks.mcp.client import MCPClient, MCPClientError
+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
+from backend.util.settings import Settings
+
+logger = logging.getLogger(__name__)
+
+settings = Settings()
+router = fastapi.APIRouter(tags=["mcp"])
+creds_manager = IntegrationCredentialsManager()
+
+
+# ====================== Tool Discovery ====================== #
+
+
+class DiscoverToolsRequest(BaseModel):
+    """Request to discover tools on an MCP server."""
+
+    server_url: str = Field(description="URL of the MCP server")
+    auth_token: str | None = Field(
+        default=None,
+        description="Optional Bearer token for authenticated MCP servers",
+    )
+
+
+class MCPToolResponse(BaseModel):
+    """A single MCP tool returned by discovery."""
+
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+
+
+class DiscoverToolsResponse(BaseModel):
+    """Response containing the list of tools available on an MCP server."""
+
+    tools: list[MCPToolResponse]
+    server_name: str | None = None
+    protocol_version: str | None = None
+
+
+@router.post(
+    "/discover-tools",
+    summary="Discover available tools on an MCP server",
+    response_model=DiscoverToolsResponse,
+)
+async def discover_tools(
+    request: DiscoverToolsRequest,
+    user_id: Annotated[str, Security(get_user_id)],
+) -> DiscoverToolsResponse:
+    """
+    Connect to an MCP server and return its available tools.
+
+    If the user has a stored MCP credential for this server URL, it will be
+    used automatically — no need to pass an explicit auth token.
+    """
+    auth_token = request.auth_token
+
+    # Auto-use stored MCP credential when no explicit token is provided.
+    if not auth_token:
+        mcp_creds = await creds_manager.store.get_creds_by_provider(
+            user_id, ProviderName.MCP.value
+        )
+        # Find the freshest credential for this server URL
+        best_cred: OAuth2Credentials | None = None
+        for cred in mcp_creds:
+            if (
+                isinstance(cred, OAuth2Credentials)
+                and (cred.metadata or {}).get("mcp_server_url") == request.server_url
+            ):
+                if best_cred is None or (
+                    (cred.access_token_expires_at or 0)
+                    > (best_cred.access_token_expires_at or 0)
+                ):
+                    best_cred = cred
+        if best_cred:
+            # Refresh the token if expired before using it
+            best_cred = await creds_manager.refresh_if_needed(user_id, best_cred)
+            logger.info(
+                f"Using MCP credential {best_cred.id} for {request.server_url}, "
+                f"expires_at={best_cred.access_token_expires_at}"
+            )
+            auth_token = best_cred.access_token.get_secret_value()
+
+    client = MCPClient(request.server_url, auth_token=auth_token)
+
+    try:
+        init_result = await client.initialize()
+        tools = await client.list_tools()
+    except HTTPClientError as e:
+        if e.status_code in (401, 403):
+            raise fastapi.HTTPException(
+                status_code=401,
+                detail="This MCP server requires authentication. "
+                "Please provide a valid auth token.",
+            )
+        raise fastapi.HTTPException(status_code=502, detail=str(e))
+    except MCPClientError as e:
+        raise fastapi.HTTPException(status_code=502, detail=str(e))
+    except Exception as e:
+        raise fastapi.HTTPException(
+            status_code=502,
+            detail=f"Failed to connect to MCP server: {e}",
+        )
+
+    return DiscoverToolsResponse(
+        tools=[
+            MCPToolResponse(
+                name=t.name,
+                description=t.description,
+                input_schema=t.input_schema,
+            )
+            for t in tools
+        ],
+        server_name=(
+            init_result.get("serverInfo", {}).get("name")
+            or urlparse(request.server_url).hostname
+            or "MCP"
+        ),
+        protocol_version=init_result.get("protocolVersion"),
+    )
+
+
+# ======================== OAuth Flow ======================== #
+
+
+class MCPOAuthLoginRequest(BaseModel):
+    """Request to start an OAuth flow for an MCP server."""
+
+    server_url: str = Field(description="URL of the MCP server that requires OAuth")
+
+
+class MCPOAuthLoginResponse(BaseModel):
+    """Response with the OAuth login URL for the user to authenticate."""
+
+    login_url: str
+    state_token: str
+
+
+@router.post(
+    "/oauth/login",
+    summary="Initiate OAuth login for an MCP server",
+)
+async def mcp_oauth_login(
+    request: MCPOAuthLoginRequest,
+    user_id: Annotated[str, Security(get_user_id)],
+) -> MCPOAuthLoginResponse:
+    """
+    Discover OAuth metadata from the MCP server and return a login URL.
+
+    1. Discovers the protected-resource metadata (RFC 9728)
+    2. Fetches the authorization server metadata (RFC 8414)
+    3. Performs Dynamic Client Registration (RFC 7591) if available
+    4. Returns the authorization URL for the frontend to open in a popup
+    """
+    client = MCPClient(request.server_url)
+
+    # Step 1: Discover protected-resource metadata (RFC 9728)
+    protected_resource = await client.discover_auth()
+
+    metadata: dict[str, Any] | None = None
+
+    if protected_resource and protected_resource.get("authorization_servers"):
+        auth_server_url = protected_resource["authorization_servers"][0]
+        resource_url = protected_resource.get("resource", request.server_url)
+
+        # Step 2a: Discover auth-server metadata (RFC 8414)
+        metadata = await client.discover_auth_server_metadata(auth_server_url)
+    else:
+        # Fallback: Some MCP servers (e.g. Linear) are their own auth server
+        # and serve OAuth metadata directly without protected-resource metadata.
+        # Don't assume a resource_url — omitting it lets the auth server choose
+        # the correct audience for the token (RFC 8707 resource is optional).
+        resource_url = None
+        metadata = await client.discover_auth_server_metadata(request.server_url)
+
+    if (
+        not metadata
+        or "authorization_endpoint" not in metadata
+        or "token_endpoint" not in metadata
+    ):
+        raise fastapi.HTTPException(
+            status_code=400,
+            detail="This MCP server does not advertise OAuth support. "
+            "You may need to provide an auth token manually.",
+        )
+
+    authorize_url = metadata["authorization_endpoint"]
+    token_url = metadata["token_endpoint"]
+    registration_endpoint = metadata.get("registration_endpoint")
+    revoke_url = metadata.get("revocation_endpoint")
+
+    # Step 3: Dynamic Client Registration (RFC 7591) if available
+    frontend_base_url = settings.config.frontend_base_url
+    if not frontend_base_url:
+        raise fastapi.HTTPException(
+            status_code=500,
+            detail="Frontend base URL is not configured.",
+        )
+    redirect_uri = f"{frontend_base_url}/auth/integrations/mcp_callback"
+
+    client_id = ""
+    client_secret = ""
+    if registration_endpoint:
+        reg_result = await _register_mcp_client(
+            registration_endpoint, redirect_uri, request.server_url
+        )
+        if reg_result:
+            client_id = reg_result.get("client_id", "")
+            client_secret = reg_result.get("client_secret", "")
+
+    if not client_id:
+        client_id = "autogpt-platform"
+
+    # Step 4: Store state token with OAuth metadata for the callback
+    scopes = (protected_resource or {}).get("scopes_supported") or metadata.get(
+        "scopes_supported", []
+    )
+    state_token, code_challenge = await creds_manager.store.store_state_token(
+        user_id,
+        ProviderName.MCP.value,
+        scopes,
+        state_metadata={
+            "authorize_url": authorize_url,
+            "token_url": token_url,
+            "revoke_url": revoke_url,
+            "resource_url": resource_url,
+            "server_url": request.server_url,
+            "client_id": client_id,
+            "client_secret": client_secret,
+        },
+    )
+
+    # Step 5: Build and return the login URL
+    handler = MCPOAuthHandler(
+        client_id=client_id,
+        client_secret=client_secret,
+        redirect_uri=redirect_uri,
+        authorize_url=authorize_url,
+        token_url=token_url,
+        resource_url=resource_url,
+    )
+    login_url = handler.get_login_url(
+        scopes, state_token, code_challenge=code_challenge
+    )
+
+    return MCPOAuthLoginResponse(login_url=login_url, state_token=state_token)
+
+
+class MCPOAuthCallbackRequest(BaseModel):
+    """Request to exchange an OAuth code for tokens."""
+
+    code: str = Field(description="Authorization code from OAuth callback")
+    state_token: str = Field(description="State token for CSRF verification")
+
+
+class MCPOAuthCallbackResponse(BaseModel):
+    """Response after successfully storing OAuth credentials."""
+
+    credential_id: str
+
+
+@router.post(
+    "/oauth/callback",
+    summary="Exchange OAuth code for MCP tokens",
+)
+async def mcp_oauth_callback(
+    request: MCPOAuthCallbackRequest,
+    user_id: Annotated[str, Security(get_user_id)],
+) -> CredentialsMetaResponse:
+    """
+    Exchange the authorization code for tokens and store the credential.
+
+    The frontend calls this after receiving the OAuth code from the popup.
+    On success, subsequent ``/discover-tools`` calls for the same server URL
+    will automatically use the stored credential.
+    """
+    valid_state = await creds_manager.store.verify_state_token(
+        user_id, request.state_token, ProviderName.MCP.value
+    )
+    if not valid_state:
+        raise fastapi.HTTPException(
+            status_code=400,
+            detail="Invalid or expired state token.",
+        )
+
+    meta = valid_state.state_metadata
+    frontend_base_url = settings.config.frontend_base_url
+    if not frontend_base_url:
+        raise fastapi.HTTPException(
+            status_code=500,
+            detail="Frontend base URL is not configured.",
+        )
+    redirect_uri = f"{frontend_base_url}/auth/integrations/mcp_callback"
+
+    handler = MCPOAuthHandler(
+        client_id=meta["client_id"],
+        client_secret=meta.get("client_secret", ""),
+        redirect_uri=redirect_uri,
+        authorize_url=meta["authorize_url"],
+        token_url=meta["token_url"],
+        revoke_url=meta.get("revoke_url"),
+        resource_url=meta.get("resource_url"),
+    )
+
+    try:
+        credentials = await handler.exchange_code_for_tokens(
+            request.code, valid_state.scopes, valid_state.code_verifier
+        )
+    except Exception as e:
+        raise fastapi.HTTPException(
+            status_code=400,
+            detail=f"OAuth token exchange failed: {e}",
+        )
+
+    # Enrich credential metadata for future lookup and token refresh
+    if credentials.metadata is None:
+        credentials.metadata = {}
+    credentials.metadata["mcp_server_url"] = meta["server_url"]
+    credentials.metadata["mcp_client_id"] = meta["client_id"]
+    credentials.metadata["mcp_client_secret"] = meta.get("client_secret", "")
+    credentials.metadata["mcp_token_url"] = meta["token_url"]
+    credentials.metadata["mcp_resource_url"] = meta.get("resource_url", "")
+
+    hostname = urlparse(meta["server_url"]).hostname or meta["server_url"]
+    credentials.title = f"MCP: {hostname}"
+
+    # Remove old MCP credentials for the same server to prevent stale token buildup.
+    try:
+        old_creds = await creds_manager.store.get_creds_by_provider(
+            user_id, ProviderName.MCP.value
+        )
+        for old in old_creds:
+            if (
+                isinstance(old, OAuth2Credentials)
+                and (old.metadata or {}).get("mcp_server_url") == meta["server_url"]
+            ):
+                await creds_manager.store.delete_creds_by_id(user_id, old.id)
+                logger.info(
+                    f"Removed old MCP credential {old.id} for {meta['server_url']}"
+                )
+    except Exception:
+        logger.debug("Could not clean up old MCP credentials", exc_info=True)
+
+    await creds_manager.create(user_id, credentials)
+
+    return CredentialsMetaResponse(
+        id=credentials.id,
+        provider=credentials.provider,
+        type=credentials.type,
+        title=credentials.title,
+        scopes=credentials.scopes,
+        username=credentials.username,
+        host=credentials.metadata.get("mcp_server_url"),
+    )
+
+
+# ======================== Helpers ======================== #
+
+
+async def _register_mcp_client(
+    registration_endpoint: str,
+    redirect_uri: str,
+    server_url: str,
+) -> dict[str, Any] | None:
+    """Attempt Dynamic Client Registration (RFC 7591) with an MCP auth server."""
+    try:
+        response = await Requests(raise_for_status=True).post(
+            registration_endpoint,
+            json={
+                "client_name": "AutoGPT Platform",
+                "redirect_uris": [redirect_uri],
+                "grant_types": ["authorization_code"],
+                "response_types": ["code"],
+                "token_endpoint_auth_method": "client_secret_post",
+            },
+        )
+        data = response.json()
+        if isinstance(data, dict) and "client_id" in data:
+            return data
+        return None
+    except Exception as e:
+        logger.warning(f"Dynamic client registration failed for {server_url}: {e}")
+        return None

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

@@ -0,0 +1,436 @@
+"""Tests for MCP API routes.
+
+Uses httpx.AsyncClient with ASGITransport instead of fastapi.testclient.TestClient
+to avoid creating blocking portals that can corrupt pytest-asyncio's session event loop.
+"""
+
+from unittest.mock import AsyncMock, patch
+
+import fastapi
+import httpx
+import pytest
+import pytest_asyncio
+from autogpt_libs.auth import get_user_id
+
+from backend.api.features.mcp.routes import router
+from backend.blocks.mcp.client import MCPClientError, MCPTool
+from backend.util.request import HTTPClientError
+
+app = fastapi.FastAPI()
+app.include_router(router)
+app.dependency_overrides[get_user_id] = lambda: "test-user-id"
+
+
+@pytest_asyncio.fixture(scope="module")
+async def client():
+    transport = httpx.ASGITransport(app=app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as c:
+        yield c
+
+
+class TestDiscoverTools:
+    @pytest.mark.asyncio(loop_scope="session")
+    async def test_discover_tools_success(self, client):
+        mock_tools = [
+            MCPTool(
+                name="get_weather",
+                description="Get weather for a city",
+                input_schema={
+                    "type": "object",
+                    "properties": {"city": {"type": "string"}},
+                    "required": ["city"],
+                },
+            ),
+            MCPTool(
+                name="add_numbers",
+                description="Add two numbers",
+                input_schema={
+                    "type": "object",
+                    "properties": {
+                        "a": {"type": "number"},
+                        "b": {"type": "number"},
+                    },
+                },
+            ),
+        ]
+
+        with (
+            patch("backend.api.features.mcp.routes.MCPClient") as MockClient,
+            patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+        ):
+            mock_cm.store.get_creds_by_provider = AsyncMock(return_value=[])
+            instance = MockClient.return_value
+            instance.initialize = AsyncMock(
+                return_value={
+                    "protocolVersion": "2025-03-26",
+                    "serverInfo": {"name": "test-server"},
+                }
+            )
+            instance.list_tools = AsyncMock(return_value=mock_tools)
+
+            response = await client.post(
+                "/discover-tools",
+                json={"server_url": "https://mcp.example.com/mcp"},
+            )
+
+        assert response.status_code == 200
+        data = response.json()
+        assert len(data["tools"]) == 2
+        assert data["tools"][0]["name"] == "get_weather"
+        assert data["tools"][1]["name"] == "add_numbers"
+        assert data["server_name"] == "test-server"
+        assert data["protocol_version"] == "2025-03-26"
+
+    @pytest.mark.asyncio(loop_scope="session")
+    async def test_discover_tools_with_auth_token(self, client):
+        with patch("backend.api.features.mcp.routes.MCPClient") as MockClient:
+            instance = MockClient.return_value
+            instance.initialize = AsyncMock(
+                return_value={"serverInfo": {}, "protocolVersion": "2025-03-26"}
+            )
+            instance.list_tools = AsyncMock(return_value=[])
+
+            response = await client.post(
+                "/discover-tools",
+                json={
+                    "server_url": "https://mcp.example.com/mcp",
+                    "auth_token": "my-secret-token",
+                },
+            )
+
+        assert response.status_code == 200
+        MockClient.assert_called_once_with(
+            "https://mcp.example.com/mcp",
+            auth_token="my-secret-token",
+        )
+
+    @pytest.mark.asyncio(loop_scope="session")
+    async def test_discover_tools_auto_uses_stored_credential(self, client):
+        """When no explicit token is given, stored MCP credentials are used."""
+        from pydantic import SecretStr
+
+        from backend.data.model import OAuth2Credentials
+
+        stored_cred = OAuth2Credentials(
+            provider="mcp",
+            title="MCP: example.com",
+            access_token=SecretStr("stored-token-123"),
+            refresh_token=None,
+            access_token_expires_at=None,
+            refresh_token_expires_at=None,
+            scopes=[],
+            metadata={"mcp_server_url": "https://mcp.example.com/mcp"},
+        )
+
+        with (
+            patch("backend.api.features.mcp.routes.MCPClient") as MockClient,
+            patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+        ):
+            mock_cm.store.get_creds_by_provider = AsyncMock(return_value=[stored_cred])
+            mock_cm.refresh_if_needed = AsyncMock(return_value=stored_cred)
+            instance = MockClient.return_value
+            instance.initialize = AsyncMock(
+                return_value={"serverInfo": {}, "protocolVersion": "2025-03-26"}
+            )
+            instance.list_tools = AsyncMock(return_value=[])
+
+            response = await client.post(
+                "/discover-tools",
+                json={"server_url": "https://mcp.example.com/mcp"},
+            )
+
+        assert response.status_code == 200
+        MockClient.assert_called_once_with(
+            "https://mcp.example.com/mcp",
+            auth_token="stored-token-123",
+        )
+
+    @pytest.mark.asyncio(loop_scope="session")
+    async def test_discover_tools_mcp_error(self, client):
+        with (
+            patch("backend.api.features.mcp.routes.MCPClient") as MockClient,
+            patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+        ):
+            mock_cm.store.get_creds_by_provider = AsyncMock(return_value=[])
+            instance = MockClient.return_value
+            instance.initialize = AsyncMock(
+                side_effect=MCPClientError("Connection refused")
+            )
+
+            response = await client.post(
+                "/discover-tools",
+                json={"server_url": "https://bad-server.example.com/mcp"},
+            )
+
+        assert response.status_code == 502
+        assert "Connection refused" in response.json()["detail"]
+
+    @pytest.mark.asyncio(loop_scope="session")
+    async def test_discover_tools_generic_error(self, client):
+        with (
+            patch("backend.api.features.mcp.routes.MCPClient") as MockClient,
+            patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+        ):
+            mock_cm.store.get_creds_by_provider = AsyncMock(return_value=[])
+            instance = MockClient.return_value
+            instance.initialize = AsyncMock(side_effect=Exception("Network timeout"))
+
+            response = await client.post(
+                "/discover-tools",
+                json={"server_url": "https://timeout.example.com/mcp"},
+            )
+
+        assert response.status_code == 502
+        assert "Failed to connect" in response.json()["detail"]
+
+    @pytest.mark.asyncio(loop_scope="session")
+    async def test_discover_tools_auth_required(self, client):
+        with (
+            patch("backend.api.features.mcp.routes.MCPClient") as MockClient,
+            patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+        ):
+            mock_cm.store.get_creds_by_provider = AsyncMock(return_value=[])
+            instance = MockClient.return_value
+            instance.initialize = AsyncMock(
+                side_effect=HTTPClientError("HTTP 401 Error: Unauthorized", 401)
+            )
+
+            response = await client.post(
+                "/discover-tools",
+                json={"server_url": "https://auth-server.example.com/mcp"},
+            )
+
+        assert response.status_code == 401
+        assert "requires authentication" in response.json()["detail"]
+
+    @pytest.mark.asyncio(loop_scope="session")
+    async def test_discover_tools_forbidden(self, client):
+        with (
+            patch("backend.api.features.mcp.routes.MCPClient") as MockClient,
+            patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+        ):
+            mock_cm.store.get_creds_by_provider = AsyncMock(return_value=[])
+            instance = MockClient.return_value
+            instance.initialize = AsyncMock(
+                side_effect=HTTPClientError("HTTP 403 Error: Forbidden", 403)
+            )
+
+            response = await client.post(
+                "/discover-tools",
+                json={"server_url": "https://auth-server.example.com/mcp"},
+            )
+
+        assert response.status_code == 401
+        assert "requires authentication" in response.json()["detail"]
+
+    @pytest.mark.asyncio(loop_scope="session")
+    async def test_discover_tools_missing_url(self, client):
+        response = await client.post("/discover-tools", json={})
+        assert response.status_code == 422
+
+
+class TestOAuthLogin:
+    @pytest.mark.asyncio(loop_scope="session")
+    async def test_oauth_login_success(self, client):
+        with (
+            patch("backend.api.features.mcp.routes.MCPClient") as MockClient,
+            patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+            patch("backend.api.features.mcp.routes.settings") as mock_settings,
+            patch(
+                "backend.api.features.mcp.routes._register_mcp_client"
+            ) as mock_register,
+        ):
+            instance = MockClient.return_value
+            instance.discover_auth = AsyncMock(
+                return_value={
+                    "authorization_servers": ["https://auth.sentry.io"],
+                    "resource": "https://mcp.sentry.dev/mcp",
+                    "scopes_supported": ["openid"],
+                }
+            )
+            instance.discover_auth_server_metadata = AsyncMock(
+                return_value={
+                    "authorization_endpoint": "https://auth.sentry.io/authorize",
+                    "token_endpoint": "https://auth.sentry.io/token",
+                    "registration_endpoint": "https://auth.sentry.io/register",
+                }
+            )
+            mock_register.return_value = {
+                "client_id": "registered-client-id",
+                "client_secret": "registered-secret",
+            }
+            mock_cm.store.store_state_token = AsyncMock(
+                return_value=("state-token-123", "code-challenge-abc")
+            )
+            mock_settings.config.frontend_base_url = "http://localhost:3000"
+
+            response = await client.post(
+                "/oauth/login",
+                json={"server_url": "https://mcp.sentry.dev/mcp"},
+            )
+
+        assert response.status_code == 200
+        data = response.json()
+        assert "login_url" in data
+        assert data["state_token"] == "state-token-123"
+        assert "auth.sentry.io/authorize" in data["login_url"]
+        assert "registered-client-id" in data["login_url"]
+
+    @pytest.mark.asyncio(loop_scope="session")
+    async def test_oauth_login_no_oauth_support(self, client):
+        with patch("backend.api.features.mcp.routes.MCPClient") as MockClient:
+            instance = MockClient.return_value
+            instance.discover_auth = AsyncMock(return_value=None)
+            instance.discover_auth_server_metadata = AsyncMock(return_value=None)
+
+            response = await client.post(
+                "/oauth/login",
+                json={"server_url": "https://simple-server.example.com/mcp"},
+            )
+
+        assert response.status_code == 400
+        assert "does not advertise OAuth" in response.json()["detail"]
+
+    @pytest.mark.asyncio(loop_scope="session")
+    async def test_oauth_login_fallback_to_public_client(self, client):
+        """When DCR is unavailable, falls back to default public client ID."""
+        with (
+            patch("backend.api.features.mcp.routes.MCPClient") as MockClient,
+            patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+            patch("backend.api.features.mcp.routes.settings") as mock_settings,
+        ):
+            instance = MockClient.return_value
+            instance.discover_auth = AsyncMock(
+                return_value={
+                    "authorization_servers": ["https://auth.example.com"],
+                    "resource": "https://mcp.example.com/mcp",
+                }
+            )
+            instance.discover_auth_server_metadata = AsyncMock(
+                return_value={
+                    "authorization_endpoint": "https://auth.example.com/authorize",
+                    "token_endpoint": "https://auth.example.com/token",
+                    # No registration_endpoint
+                }
+            )
+            mock_cm.store.store_state_token = AsyncMock(
+                return_value=("state-abc", "challenge-xyz")
+            )
+            mock_settings.config.frontend_base_url = "http://localhost:3000"
+
+            response = await client.post(
+                "/oauth/login",
+                json={"server_url": "https://mcp.example.com/mcp"},
+            )
+
+        assert response.status_code == 200
+        data = response.json()
+        assert "autogpt-platform" in data["login_url"]
+
+
+class TestOAuthCallback:
+    @pytest.mark.asyncio(loop_scope="session")
+    async def test_oauth_callback_success(self, client):
+        from pydantic import SecretStr
+
+        from backend.data.model import OAuth2Credentials
+
+        mock_creds = OAuth2Credentials(
+            provider="mcp",
+            title=None,
+            access_token=SecretStr("access-token-xyz"),
+            refresh_token=None,
+            access_token_expires_at=None,
+            refresh_token_expires_at=None,
+            scopes=[],
+            metadata={
+                "mcp_token_url": "https://auth.sentry.io/token",
+                "mcp_resource_url": "https://mcp.sentry.dev/mcp",
+            },
+        )
+
+        with (
+            patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+            patch("backend.api.features.mcp.routes.settings") as mock_settings,
+            patch("backend.api.features.mcp.routes.MCPOAuthHandler") as MockHandler,
+        ):
+            mock_settings.config.frontend_base_url = "http://localhost:3000"
+
+            # Mock state verification
+            mock_state = AsyncMock()
+            mock_state.state_metadata = {
+                "authorize_url": "https://auth.sentry.io/authorize",
+                "token_url": "https://auth.sentry.io/token",
+                "client_id": "test-client-id",
+                "client_secret": "test-secret",
+                "server_url": "https://mcp.sentry.dev/mcp",
+            }
+            mock_state.scopes = ["openid"]
+            mock_state.code_verifier = "verifier-123"
+            mock_cm.store.verify_state_token = AsyncMock(return_value=mock_state)
+            mock_cm.create = AsyncMock()
+
+            handler_instance = MockHandler.return_value
+            handler_instance.exchange_code_for_tokens = AsyncMock(
+                return_value=mock_creds
+            )
+
+            # Mock old credential cleanup
+            mock_cm.store.get_creds_by_provider = AsyncMock(return_value=[])
+
+            response = await client.post(
+                "/oauth/callback",
+                json={"code": "auth-code-abc", "state_token": "state-token-123"},
+            )
+
+        assert response.status_code == 200
+        data = response.json()
+        assert "id" in data
+        assert data["provider"] == "mcp"
+        assert data["type"] == "oauth2"
+        mock_cm.create.assert_called_once()
+
+    @pytest.mark.asyncio(loop_scope="session")
+    async def test_oauth_callback_invalid_state(self, client):
+        with patch("backend.api.features.mcp.routes.creds_manager") as mock_cm:
+            mock_cm.store.verify_state_token = AsyncMock(return_value=None)
+
+            response = await client.post(
+                "/oauth/callback",
+                json={"code": "auth-code", "state_token": "bad-state"},
+            )
+
+        assert response.status_code == 400
+        assert "Invalid or expired" in response.json()["detail"]
+
+    @pytest.mark.asyncio(loop_scope="session")
+    async def test_oauth_callback_token_exchange_fails(self, client):
+        with (
+            patch("backend.api.features.mcp.routes.creds_manager") as mock_cm,
+            patch("backend.api.features.mcp.routes.settings") as mock_settings,
+            patch("backend.api.features.mcp.routes.MCPOAuthHandler") as MockHandler,
+        ):
+            mock_settings.config.frontend_base_url = "http://localhost:3000"
+            mock_state = AsyncMock()
+            mock_state.state_metadata = {
+                "authorize_url": "https://auth.example.com/authorize",
+                "token_url": "https://auth.example.com/token",
+                "client_id": "cid",
+                "server_url": "https://mcp.example.com/mcp",
+            }
+            mock_state.scopes = []
+            mock_state.code_verifier = "v"
+            mock_cm.store.verify_state_token = AsyncMock(return_value=mock_state)
+
+            handler_instance = MockHandler.return_value
+            handler_instance.exchange_code_for_tokens = AsyncMock(
+                side_effect=RuntimeError("Token exchange failed")
+            )
+
+            response = await client.post(
+                "/oauth/callback",
+                json={"code": "bad-code", "state_token": "state"},
+            )
+
+        assert response.status_code == 400
+        assert "token exchange failed" in response.json()["detail"].lower()

autogpt_platform/backend/backend/api/features/otto/service.py

@@ -5,8 +5,8 @@ from typing import Optional
 import aiohttp
 from fastapi import HTTPException
 
+from backend.blocks import get_block
 from backend.data import graph as graph_db
-from backend.data.block import get_block
 from backend.util.settings import Settings
 
 from .models import ApiResponse, ChatRequest, GraphData

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

@@ -152,7 +152,7 @@ class BlockHandler(ContentHandler):
 
     async def get_missing_items(self, batch_size: int) -> list[ContentItem]:
         """Fetch blocks without embeddings."""
-        from backend.data.block import get_blocks
+        from backend.blocks import get_blocks
 
         # Get all available blocks
         all_blocks = get_blocks()
@@ -249,7 +249,7 @@ class BlockHandler(ContentHandler):
 
     async def get_stats(self) -> dict[str, int]:
         """Get statistics about block embedding coverage."""
-        from backend.data.block import get_blocks
+        from backend.blocks import get_blocks
 
         all_blocks = get_blocks()
 

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

@@ -93,7 +93,7 @@ async def test_block_handler_get_missing_items(mocker):
     mock_existing = []
 
     with patch(
-        "backend.data.block.get_blocks",
+        "backend.blocks.get_blocks",
         return_value=mock_blocks,
     ):
         with patch(
@@ -135,7 +135,7 @@ async def test_block_handler_get_stats(mocker):
     mock_embedded = [{"count": 2}]
 
     with patch(
-        "backend.data.block.get_blocks",
+        "backend.blocks.get_blocks",
         return_value=mock_blocks,
     ):
         with patch(
@@ -327,7 +327,7 @@ async def test_block_handler_handles_missing_attributes():
     mock_blocks = {"block-minimal": mock_block_class}
 
     with patch(
-        "backend.data.block.get_blocks",
+        "backend.blocks.get_blocks",
         return_value=mock_blocks,
     ):
         with patch(
@@ -360,7 +360,7 @@ async def test_block_handler_skips_failed_blocks():
     mock_blocks = {"good-block": good_block, "bad-block": bad_block}
 
     with patch(
-        "backend.data.block.get_blocks",
+        "backend.blocks.get_blocks",
         return_value=mock_blocks,
     ):
         with patch(

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

@@ -1,7 +1,7 @@
 import asyncio
 import logging
 from datetime import datetime, timezone
-from typing import Any, Literal
+from typing import Any, Literal, overload
 
 import fastapi
 import prisma.enums
@@ -11,8 +11,8 @@ import prisma.types
 
 from backend.data.db import transaction
 from backend.data.graph import (
-    GraphMeta,
     GraphModel,
+    GraphModelWithoutNodes,
     get_graph,
     get_graph_as_admin,
     get_sub_graphs,
@@ -112,6 +112,7 @@ async def get_store_agents(
                             description=agent["description"],
                             runs=agent["runs"],
                             rating=agent["rating"],
+                            agent_graph_id=agent.get("agentGraphId", ""),
                         )
                         store_agents.append(store_agent)
                     except Exception as e:
@@ -170,6 +171,7 @@ async def get_store_agents(
                         description=agent.description,
                         runs=agent.runs,
                         rating=agent.rating,
+                        agent_graph_id=agent.agentGraphId,
                     )
                     # Add to the list only if creation was successful
                     store_agents.append(store_agent)
@@ -332,7 +334,22 @@ async def get_store_agent_details(
         raise DatabaseError("Failed to fetch agent details") from e
 
 
-async def get_available_graph(store_listing_version_id: str) -> GraphMeta:
+@overload
+async def get_available_graph(
+    store_listing_version_id: str, hide_nodes: Literal[False]
+) -> GraphModel: ...
+
+
+@overload
+async def get_available_graph(
+    store_listing_version_id: str, hide_nodes: Literal[True] = True
+) -> GraphModelWithoutNodes: ...
+
+
+async def get_available_graph(
+    store_listing_version_id: str,
+    hide_nodes: bool = True,
+) -> GraphModelWithoutNodes | GraphModel:
     try:
         # Get avaialble, non-deleted store listing version
         store_listing_version = (
@@ -342,7 +359,7 @@ async def get_available_graph(store_listing_version_id: str) -> GraphMeta:
                     "isAvailable": True,
                     "isDeleted": False,
                 },
-                include={"AgentGraph": {"include": {"Nodes": True}}},
+                include={"AgentGraph": {"include": AGENT_GRAPH_INCLUDE}},
             )
         )
 
@@ -352,7 +369,9 @@ async def get_available_graph(store_listing_version_id: str) -> GraphMeta:
                 detail=f"Store listing version {store_listing_version_id} not found",
             )
 
-        return GraphModel.from_db(store_listing_version.AgentGraph).meta()
+        return (GraphModelWithoutNodes if hide_nodes else GraphModel).from_db(
+            store_listing_version.AgentGraph
+        )
 
     except Exception as e:
         logger.error(f"Error getting agent: {e}")

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

@@ -662,7 +662,7 @@ async def cleanup_orphaned_embeddings() -> dict[str, Any]:
                 )
                 current_ids = {row["id"] for row in valid_agents}
             elif content_type == ContentType.BLOCK:
-                from backend.data.block import get_blocks
+                from backend.blocks import get_blocks
 
                 current_ids = set(get_blocks().keys())
             elif content_type == ContentType.DOCUMENTATION:

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

@@ -454,6 +454,9 @@ async def test_unified_hybrid_search_pagination(
     cleanup_embeddings: list,
 ):
     """Test unified search pagination works correctly."""
+    # Use a unique search term to avoid matching other test data
+    unique_term = f"xyzpagtest{uuid.uuid4().hex[:8]}"
+
     # Create multiple items
     content_ids = []
     for i in range(5):
@@ -465,14 +468,14 @@ async def test_unified_hybrid_search_pagination(
             content_type=ContentType.BLOCK,
             content_id=content_id,
             embedding=mock_embedding,
-            searchable_text=f"pagination test item number {i}",
+            searchable_text=f"{unique_term} item number {i}",
             metadata={"index": i},
             user_id=None,
         )
 
     # Get first page
     page1_results, total1 = await unified_hybrid_search(
-        query="pagination test",
+        query=unique_term,
         content_types=[ContentType.BLOCK],
         page=1,
         page_size=2,
@@ -480,7 +483,7 @@ async def test_unified_hybrid_search_pagination(
 
     # Get second page
     page2_results, total2 = await unified_hybrid_search(
-        query="pagination test",
+        query=unique_term,
         content_types=[ContentType.BLOCK],
         page=2,
         page_size=2,

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

@@ -8,6 +8,7 @@ Includes BM25 reranking for improved lexical relevance.
 
 import logging
 import re
+import time
 from dataclasses import dataclass
 from typing import Any, Literal
 
@@ -362,7 +363,11 @@ async def unified_hybrid_search(
         LIMIT {limit_param} OFFSET {offset_param}
     """
 
-    results = await query_raw_with_schema(sql_query, *params)
+    try:
+        results = await query_raw_with_schema(sql_query, *params)
+    except Exception as e:
+        await _log_vector_error_diagnostics(e)
+        raise
 
     total = results[0]["total_count"] if results else 0
     # Apply BM25 reranking
@@ -600,6 +605,7 @@ async def hybrid_search(
                 sa.featured,
                 sa.is_available,
                 sa.updated_at,
+                sa."agentGraphId",
                 -- Searchable text for BM25 reranking
                 COALESCE(sa.agent_name, '') || ' ' || COALESCE(sa.sub_heading, '') || ' ' || COALESCE(sa.description, '') as searchable_text,
                 -- Semantic score
@@ -659,6 +665,7 @@ async def hybrid_search(
                 featured,
                 is_available,
                 updated_at,
+                "agentGraphId",
                 searchable_text,
                 semantic_score,
                 lexical_score,
@@ -684,7 +691,11 @@ async def hybrid_search(
         LIMIT {limit_param} OFFSET {offset_param}
     """
 
-    results = await query_raw_with_schema(sql_query, *params)
+    try:
+        results = await query_raw_with_schema(sql_query, *params)
+    except Exception as e:
+        await _log_vector_error_diagnostics(e)
+        raise
 
     total = results[0]["total_count"] if results else 0
 
@@ -716,6 +727,87 @@ async def hybrid_search_simple(
     return await hybrid_search(query=query, page=page, page_size=page_size)
 
 
+# ============================================================================
+# Diagnostics
+# ============================================================================
+
+# Rate limit: only log vector error diagnostics once per this interval
+_VECTOR_DIAG_INTERVAL_SECONDS = 60
+_last_vector_diag_time: float = 0
+
+
+async def _log_vector_error_diagnostics(error: Exception) -> None:
+    """Log diagnostic info when 'type vector does not exist' error occurs.
+
+    Note: Diagnostic queries use query_raw_with_schema which may run on a different
+    pooled connection than the one that failed. Session-level search_path can differ,
+    so these diagnostics show cluster-wide state, not necessarily the failed session.
+
+    Includes rate limiting to avoid log spam - only logs once per minute.
+    Caller should re-raise the error after calling this function.
+    """
+    global _last_vector_diag_time
+
+    # Check if this is the vector type error
+    error_str = str(error).lower()
+    if not (
+        "type" in error_str and "vector" in error_str and "does not exist" in error_str
+    ):
+        return
+
+    # Rate limit: only log once per interval
+    now = time.time()
+    if now - _last_vector_diag_time < _VECTOR_DIAG_INTERVAL_SECONDS:
+        return
+    _last_vector_diag_time = now
+
+    try:
+        diagnostics: dict[str, object] = {}
+
+        try:
+            search_path_result = await query_raw_with_schema("SHOW search_path")
+            diagnostics["search_path"] = search_path_result
+        except Exception as e:
+            diagnostics["search_path"] = f"Error: {e}"
+
+        try:
+            schema_result = await query_raw_with_schema("SELECT current_schema()")
+            diagnostics["current_schema"] = schema_result
+        except Exception as e:
+            diagnostics["current_schema"] = f"Error: {e}"
+
+        try:
+            user_result = await query_raw_with_schema(
+                "SELECT current_user, session_user, current_database()"
+            )
+            diagnostics["user_info"] = user_result
+        except Exception as e:
+            diagnostics["user_info"] = f"Error: {e}"
+
+        try:
+            # Check pgvector extension installation (cluster-wide, stable info)
+            ext_result = await query_raw_with_schema(
+                "SELECT extname, extversion, nspname as schema "
+                "FROM pg_extension e "
+                "JOIN pg_namespace n ON e.extnamespace = n.oid "
+                "WHERE extname = 'vector'"
+            )
+            diagnostics["pgvector_extension"] = ext_result
+        except Exception as e:
+            diagnostics["pgvector_extension"] = f"Error: {e}"
+
+        logger.error(
+            f"Vector type error diagnostics:\n"
+            f"  Error: {error}\n"
+            f"  search_path: {diagnostics.get('search_path')}\n"
+            f"  current_schema: {diagnostics.get('current_schema')}\n"
+            f"  user_info: {diagnostics.get('user_info')}\n"
+            f"  pgvector_extension: {diagnostics.get('pgvector_extension')}"
+        )
+    except Exception as diag_error:
+        logger.error(f"Failed to collect vector error diagnostics: {diag_error}")
+
+
 # Backward compatibility alias - HybridSearchWeights maps to StoreAgentSearchWeights
 # for existing code that expects the popularity parameter
 HybridSearchWeights = StoreAgentSearchWeights

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

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

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

@@ -38,6 +38,7 @@ class StoreAgent(pydantic.BaseModel):
     description: str
     runs: int
     rating: float
+    agent_graph_id: str
 
 
 class StoreAgentsResponse(pydantic.BaseModel):

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

@@ -26,11 +26,13 @@ def test_store_agent():
         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():
@@ -46,6 +48,7 @@ def test_store_agents_response():
                 description="Test description",
                 runs=50,
                 rating=4.5,
+                agent_graph_id="test-graph-id",
             )
         ],
         pagination=store_model.Pagination(

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

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

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

@@ -82,6 +82,7 @@ def test_get_agents_featured(
                 description="Featured agent description",
                 runs=100,
                 rating=4.5,
+                agent_graph_id="test-graph-1",
             )
         ],
         pagination=store_model.Pagination(
@@ -127,6 +128,7 @@ def test_get_agents_by_creator(
                 description="Creator agent description",
                 runs=50,
                 rating=4.0,
+                agent_graph_id="test-graph-2",
             )
         ],
         pagination=store_model.Pagination(
@@ -172,6 +174,7 @@ def test_get_agents_sorted(
                 description="Top agent description",
                 runs=1000,
                 rating=5.0,
+                agent_graph_id="test-graph-3",
             )
         ],
         pagination=store_model.Pagination(
@@ -217,6 +220,7 @@ def test_get_agents_search(
                 description="Specific search term description",
                 runs=75,
                 rating=4.2,
+                agent_graph_id="test-graph-search",
             )
         ],
         pagination=store_model.Pagination(
@@ -262,6 +266,7 @@ def test_get_agents_category(
                 description="Category agent description",
                 runs=60,
                 rating=4.1,
+                agent_graph_id="test-graph-category",
             )
         ],
         pagination=store_model.Pagination(
@@ -306,6 +311,7 @@ def test_get_agents_pagination(
                 description=f"Agent {i} description",
                 runs=i * 10,
                 rating=4.0,
+                agent_graph_id="test-graph-2",
             )
             for i in range(5)
         ],

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

@@ -33,6 +33,7 @@ class TestCacheDeletion:
                     description="Test description",
                     runs=100,
                     rating=4.5,
+                    agent_graph_id="test-graph-id",
                 )
             ],
             pagination=Pagination(

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

@@ -40,10 +40,11 @@ from backend.api.model import (
     UpdateTimezoneRequest,
     UploadFileResponse,
 )
+from backend.blocks import get_block, get_blocks
 from backend.data import execution as execution_db
 from backend.data import graph as graph_db
 from backend.data.auth import api_key as api_key_db
-from backend.data.block import BlockInput, CompletedBlockOutput, get_block, get_blocks
+from backend.data.block import BlockInput, CompletedBlockOutput
 from backend.data.credit import (
     AutoTopUpConfig,
     RefundRequest,
@@ -101,7 +102,6 @@ from backend.util.timezone_utils import (
 from backend.util.virus_scanner import scan_content_safe
 
 from .library import db as library_db
-from .library import model as library_model
 from .store.model import StoreAgentDetails
 
 
@@ -823,18 +823,16 @@ async def update_graph(
     graph: graph_db.Graph,
     user_id: Annotated[str, Security(get_user_id)],
 ) -> graph_db.GraphModel:
-    # Sanity check
     if graph.id and graph.id != graph_id:
         raise HTTPException(400, detail="Graph ID does not match ID in URI")
 
-    # Determine new version
     existing_versions = await graph_db.get_graph_all_versions(graph_id, user_id=user_id)
     if not existing_versions:
         raise HTTPException(404, detail=f"Graph #{graph_id} not found")
-    latest_version_number = max(g.version for g in existing_versions)
-    graph.version = latest_version_number + 1
 
+    graph.version = max(g.version for g in existing_versions) + 1
     current_active_version = next((v for v in existing_versions if v.is_active), None)
+
     graph = graph_db.make_graph_model(graph, user_id)
     graph.reassign_ids(user_id=user_id, reassign_graph_id=False)
     graph.validate_graph(for_run=False)
@@ -842,27 +840,23 @@ async def update_graph(
     new_graph_version = await graph_db.create_graph(graph, user_id=user_id)
 
     if new_graph_version.is_active:
-        # Keep the library agent up to date with the new active version
-        await _update_library_agent_version_and_settings(user_id, new_graph_version)
-
-        # Handle activation of the new graph first to ensure continuity
+        await library_db.update_library_agent_version_and_settings(
+            user_id, new_graph_version
+        )
         new_graph_version = await on_graph_activate(new_graph_version, user_id=user_id)
-        # Ensure new version is the only active version
         await graph_db.set_graph_active_version(
             graph_id=graph_id, version=new_graph_version.version, user_id=user_id
         )
         if current_active_version:
-            # Handle deactivation of the previously active version
             await on_graph_deactivate(current_active_version, user_id=user_id)
 
-    # Fetch new graph version *with sub-graphs* (needed for credentials input schema)
     new_graph_version_with_subgraphs = await graph_db.get_graph(
         graph_id,
         new_graph_version.version,
         user_id=user_id,
         include_subgraphs=True,
     )
-    assert new_graph_version_with_subgraphs  # make type checker happy
+    assert new_graph_version_with_subgraphs
     return new_graph_version_with_subgraphs
 
 
@@ -900,33 +894,15 @@ async def set_graph_active_version(
     )
 
     # Keep the library agent up to date with the new active version
-    await _update_library_agent_version_and_settings(user_id, new_active_graph)
+    await library_db.update_library_agent_version_and_settings(
+        user_id, new_active_graph
+    )
 
     if current_active_graph and current_active_graph.version != new_active_version:
         # Handle deactivation of the previously active version
         await on_graph_deactivate(current_active_graph, user_id=user_id)
 
 
-async def _update_library_agent_version_and_settings(
-    user_id: str, agent_graph: graph_db.GraphModel
-) -> library_model.LibraryAgent:
-    library = await library_db.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 library_db.update_library_agent(
-            library_agent_id=library.id,
-            user_id=user_id,
-            settings=updated_settings,
-        )
-    return library
-
-
 @v1_router.patch(
     path="/graphs/{graph_id}/settings",
     summary="Update graph settings",

autogpt_platform/backend/backend/api/features/workspace/__init__.py

@@ -0,0 +1 @@
+# Workspace API feature module

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

@@ -0,0 +1,122 @@
+"""
+Workspace API routes for managing user file storage.
+"""
+
+import logging
+import re
+from typing import Annotated
+from urllib.parse import quote
+
+import fastapi
+from autogpt_libs.auth.dependencies import get_user_id, requires_user
+from fastapi.responses import Response
+
+from backend.data.workspace import WorkspaceFile, get_workspace, get_workspace_file
+from backend.util.workspace_storage import get_workspace_storage
+
+
+def _sanitize_filename_for_header(filename: str) -> str:
+    """
+    Sanitize filename for Content-Disposition header to prevent header injection.
+
+    Removes/replaces characters that could break the header or inject new headers.
+    Uses RFC5987 encoding for non-ASCII characters.
+    """
+    # Remove CR, LF, and null bytes (header injection prevention)
+    sanitized = re.sub(r"[\r\n\x00]", "", filename)
+    # Escape quotes
+    sanitized = sanitized.replace('"', '\\"')
+    # For non-ASCII, use RFC5987 filename* parameter
+    # Check if filename has non-ASCII characters
+    try:
+        sanitized.encode("ascii")
+        return f'attachment; filename="{sanitized}"'
+    except UnicodeEncodeError:
+        # Use RFC5987 encoding for UTF-8 filenames
+        encoded = quote(sanitized, safe="")
+        return f"attachment; filename*=UTF-8''{encoded}"
+
+
+logger = logging.getLogger(__name__)
+
+router = fastapi.APIRouter(
+    dependencies=[fastapi.Security(requires_user)],
+)
+
+
+def _create_streaming_response(content: bytes, file: WorkspaceFile) -> Response:
+    """Create a streaming response for file content."""
+    return Response(
+        content=content,
+        media_type=file.mime_type,
+        headers={
+            "Content-Disposition": _sanitize_filename_for_header(file.name),
+            "Content-Length": str(len(content)),
+        },
+    )
+
+
+async def _create_file_download_response(file: WorkspaceFile) -> Response:
+    """
+    Create a download response for a workspace file.
+
+    Handles both local storage (direct streaming) and GCS (signed URL redirect
+    with fallback to streaming).
+    """
+    storage = await get_workspace_storage()
+
+    # For local storage, stream the file directly
+    if file.storage_path.startswith("local://"):
+        content = await storage.retrieve(file.storage_path)
+        return _create_streaming_response(content, file)
+
+    # For GCS, try to redirect to signed URL, fall back to streaming
+    try:
+        url = await storage.get_download_url(file.storage_path, expires_in=300)
+        # If we got back an API path (fallback), stream directly instead
+        if url.startswith("/api/"):
+            content = await storage.retrieve(file.storage_path)
+            return _create_streaming_response(content, file)
+        return fastapi.responses.RedirectResponse(url=url, status_code=302)
+    except Exception as e:
+        # Log the signed URL failure with context
+        logger.error(
+            f"Failed to get signed URL for file {file.id} "
+            f"(storagePath={file.storage_path}): {e}",
+            exc_info=True,
+        )
+        # Fall back to streaming directly from GCS
+        try:
+            content = await storage.retrieve(file.storage_path)
+            return _create_streaming_response(content, file)
+        except Exception as fallback_error:
+            logger.error(
+                f"Fallback streaming also failed for file {file.id} "
+                f"(storagePath={file.storage_path}): {fallback_error}",
+                exc_info=True,
+            )
+            raise
+
+
+@router.get(
+    "/files/{file_id}/download",
+    summary="Download file by ID",
+)
+async def download_file(
+    user_id: Annotated[str, fastapi.Security(get_user_id)],
+    file_id: str,
+) -> Response:
+    """
+    Download a file by its ID.
+
+    Returns the file content directly or redirects to a signed URL for GCS.
+    """
+    workspace = await get_workspace(user_id)
+    if workspace is None:
+        raise fastapi.HTTPException(status_code=404, detail="Workspace not found")
+
+    file = await get_workspace_file(file_id, workspace.id)
+    if file is None:
+        raise fastapi.HTTPException(status_code=404, detail="File not found")
+
+    return await _create_file_download_response(file)

autogpt_platform/backend/backend/api/rest_api.py

@@ -26,12 +26,14 @@ import backend.api.features.executions.review.routes
 import backend.api.features.library.db
 import backend.api.features.library.model
 import backend.api.features.library.routes
+import backend.api.features.mcp.routes as mcp_routes
 import backend.api.features.oauth
 import backend.api.features.otto.routes
 import backend.api.features.postmark.postmark
 import backend.api.features.store.model
 import backend.api.features.store.routes
 import backend.api.features.v1
+import backend.api.features.workspace.routes as workspace_routes
 import backend.data.block
 import backend.data.db
 import backend.data.graph
@@ -40,6 +42,10 @@ import backend.integrations.webhooks.utils
 import backend.util.service
 import backend.util.settings
 from backend.blocks.llm import DEFAULT_LLM_MODEL
+from backend.copilot.completion_consumer import (
+    start_completion_consumer,
+    stop_completion_consumer,
+)
 from backend.data.model import Credentials
 from backend.integrations.providers import ProviderName
 from backend.monitoring.instrumentation import instrument_fastapi
@@ -52,6 +58,7 @@ from backend.util.exceptions import (
 )
 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
 
 from .external.fastapi_app import external_api
 from .features.analytics import router as analytics_router
@@ -116,14 +123,31 @@ async def lifespan_context(app: fastapi.FastAPI):
     await backend.data.graph.migrate_llm_models(DEFAULT_LLM_MODEL)
     await backend.integrations.webhooks.utils.migrate_legacy_triggered_graphs()
 
+    # Start chat completion consumer for Redis Streams notifications
+    try:
+        await start_completion_consumer()
+    except Exception as e:
+        logger.warning(f"Could not start chat completion consumer: {e}")
+
     with launch_darkly_context():
         yield
 
+    # Stop chat completion consumer
+    try:
+        await stop_completion_consumer()
+    except Exception as e:
+        logger.warning(f"Error stopping chat completion consumer: {e}")
+
     try:
         await shutdown_cloud_storage_handler()
     except Exception as e:
         logger.warning(f"Error shutting down cloud storage handler: {e}")
 
+    try:
+        await shutdown_workspace_storage()
+    except Exception as e:
+        logger.warning(f"Error shutting down workspace storage: {e}")
+
     await backend.data.db.disconnect()
 
 
@@ -315,6 +339,16 @@ app.include_router(
     tags=["v2", "chat"],
     prefix="/api/chat",
 )
+app.include_router(
+    workspace_routes.router,
+    tags=["workspace"],
+    prefix="/api/workspace",
+)
+app.include_router(
+    mcp_routes.router,
+    tags=["v2", "mcp"],
+    prefix="/api/mcp",
+)
 app.include_router(
     backend.api.features.oauth.router,
     tags=["oauth"],

autogpt_platform/backend/backend/api/ws_api.py

@@ -66,18 +66,24 @@ async def event_broadcaster(manager: ConnectionManager):
     execution_bus = AsyncRedisExecutionEventBus()
     notification_bus = AsyncRedisNotificationEventBus()
 
-    async def execution_worker():
-        async for event in execution_bus.listen("*"):
-            await manager.send_execution_update(event)
+    try:
 
-    async def notification_worker():
-        async for notification in notification_bus.listen("*"):
-            await manager.send_notification(
-                user_id=notification.user_id,
-                payload=notification.payload,
-            )
+        async def execution_worker():
+            async for event in execution_bus.listen("*"):
+                await manager.send_execution_update(event)
 
-    await asyncio.gather(execution_worker(), notification_worker())
+        async def notification_worker():
+            async for notification in notification_bus.listen("*"):
+                await manager.send_notification(
+                    user_id=notification.user_id,
+                    payload=notification.payload,
+                )
+
+        await asyncio.gather(execution_worker(), notification_worker())
+    finally:
+        # Ensure PubSub connections are closed on any exit to prevent leaks
+        await execution_bus.close()
+        await notification_bus.close()
 
 
 async def authenticate_websocket(websocket: WebSocket) -> str:

autogpt_platform/backend/backend/app.py

@@ -38,7 +38,9 @@ def main(**kwargs):
 
     from backend.api.rest_api import AgentServer
     from backend.api.ws_api import WebsocketServer
-    from backend.executor import DatabaseManager, ExecutionManager, Scheduler
+    from backend.copilot.executor.manager import CoPilotExecutor
+    from backend.data.db_manager import DatabaseManager
+    from backend.executor import ExecutionManager, Scheduler
     from backend.notifications import NotificationManager
 
     run_processes(
@@ -48,6 +50,7 @@ def main(**kwargs):
         WebsocketServer(),
         AgentServer(),
         ExecutionManager(),
+        CoPilotExecutor(),
         **kwargs,
     )
 

autogpt_platform/backend/backend/blocks/__init__.py

@@ -3,22 +3,19 @@ import logging
 import os
 import re
 from pathlib import Path
-from typing import TYPE_CHECKING, TypeVar
+from typing import Sequence, Type, TypeVar
 
+from backend.blocks._base import AnyBlockSchema, BlockType
 from backend.util.cache import cached
 
 logger = logging.getLogger(__name__)
 
-
-if TYPE_CHECKING:
-    from backend.data.block import Block
-
 T = TypeVar("T")
 
 
 @cached(ttl_seconds=3600)
-def load_all_blocks() -> dict[str, type["Block"]]:
-    from backend.data.block import Block
+def load_all_blocks() -> dict[str, type["AnyBlockSchema"]]:
+    from backend.blocks._base import Block
     from backend.util.settings import Config
 
     # Check if example blocks should be loaded from settings
@@ -50,8 +47,8 @@ def load_all_blocks() -> dict[str, type["Block"]]:
         importlib.import_module(f".{module}", package=__name__)
 
     # Load all Block instances from the available modules
-    available_blocks: dict[str, type["Block"]] = {}
-    for block_cls in all_subclasses(Block):
+    available_blocks: dict[str, type["AnyBlockSchema"]] = {}
+    for block_cls in _all_subclasses(Block):
         class_name = block_cls.__name__
 
         if class_name.endswith("Base"):
@@ -64,7 +61,7 @@ def load_all_blocks() -> dict[str, type["Block"]]:
                 "please name the class with 'Base' at the end"
             )
 
-        block = block_cls.create()
+        block = block_cls()  # pyright: ignore[reportAbstractUsage]
 
         if not isinstance(block.id, str) or len(block.id) != 36:
             raise ValueError(
@@ -105,7 +102,7 @@ def load_all_blocks() -> dict[str, type["Block"]]:
         available_blocks[block.id] = block_cls
 
     # Filter out blocks with incomplete auth configs, e.g. missing OAuth server secrets
-    from backend.data.block import is_block_auth_configured
+    from ._utils import is_block_auth_configured
 
     filtered_blocks = {}
     for block_id, block_cls in available_blocks.items():
@@ -115,11 +112,48 @@ def load_all_blocks() -> dict[str, type["Block"]]:
     return filtered_blocks
 
 
-__all__ = ["load_all_blocks"]
-
-
-def all_subclasses(cls: type[T]) -> list[type[T]]:
+def _all_subclasses(cls: type[T]) -> list[type[T]]:
     subclasses = cls.__subclasses__()
     for subclass in subclasses:
-        subclasses += all_subclasses(subclass)
+        subclasses += _all_subclasses(subclass)
     return subclasses
+
+
+# ============== Block access helper functions ============== #
+
+
+def get_blocks() -> dict[str, Type["AnyBlockSchema"]]:
+    return load_all_blocks()
+
+
+# Note on the return type annotation: https://github.com/microsoft/pyright/issues/10281
+def get_block(block_id: str) -> "AnyBlockSchema | None":
+    cls = get_blocks().get(block_id)
+    return cls() if cls else None
+
+
+@cached(ttl_seconds=3600)
+def get_webhook_block_ids() -> Sequence[str]:
+    return [
+        id
+        for id, B in get_blocks().items()
+        if B().block_type in (BlockType.WEBHOOK, BlockType.WEBHOOK_MANUAL)
+    ]
+
+
+@cached(ttl_seconds=3600)
+def get_io_block_ids() -> Sequence[str]:
+    return [
+        id
+        for id, B in get_blocks().items()
+        if B().block_type in (BlockType.INPUT, BlockType.OUTPUT)
+    ]
+
+
+@cached(ttl_seconds=3600)
+def get_human_in_the_loop_block_ids() -> Sequence[str]:
+    return [
+        id
+        for id, B in get_blocks().items()
+        if B().block_type == BlockType.HUMAN_IN_THE_LOOP
+    ]

autogpt_platform/backend/backend/blocks/_base.py

@@ -0,0 +1,740 @@
+import inspect
+import logging
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    ClassVar,
+    Generic,
+    Optional,
+    Type,
+    TypeAlias,
+    TypeVar,
+    cast,
+    get_origin,
+)
+
+import jsonref
+import jsonschema
+from pydantic import BaseModel
+
+from backend.data.block import BlockInput, BlockOutput, BlockOutputEntry
+from backend.data.model import (
+    Credentials,
+    CredentialsFieldInfo,
+    CredentialsMetaInput,
+    SchemaField,
+    is_credentials_field_name,
+)
+from backend.integrations.providers import ProviderName
+from backend.util import json
+from backend.util.exceptions import (
+    BlockError,
+    BlockExecutionError,
+    BlockInputError,
+    BlockOutputError,
+    BlockUnknownError,
+)
+from backend.util.settings import Config
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from backend.data.execution import ExecutionContext
+    from backend.data.model import ContributorDetails, NodeExecutionStats
+
+    from ..data.graph import Link
+
+app_config = Config()
+
+
+BlockTestOutput = BlockOutputEntry | tuple[str, Callable[[Any], bool]]
+
+
+class BlockType(Enum):
+    STANDARD = "Standard"
+    INPUT = "Input"
+    OUTPUT = "Output"
+    NOTE = "Note"
+    WEBHOOK = "Webhook"
+    WEBHOOK_MANUAL = "Webhook (manual)"
+    AGENT = "Agent"
+    AI = "AI"
+    AYRSHARE = "Ayrshare"
+    HUMAN_IN_THE_LOOP = "Human In The Loop"
+    MCP_TOOL = "MCP Tool"
+
+
+class BlockCategory(Enum):
+    AI = "Block that leverages AI to perform a task."
+    SOCIAL = "Block that interacts with social media platforms."
+    TEXT = "Block that processes text data."
+    SEARCH = "Block that searches or extracts information from the internet."
+    BASIC = "Block that performs basic operations."
+    INPUT = "Block that interacts with input of the graph."
+    OUTPUT = "Block that interacts with output of the graph."
+    LOGIC = "Programming logic to control the flow of your agent"
+    COMMUNICATION = "Block that interacts with communication platforms."
+    DEVELOPER_TOOLS = "Developer tools such as GitHub blocks."
+    DATA = "Block that interacts with structured data."
+    HARDWARE = "Block that interacts with hardware."
+    AGENT = "Block that interacts with other agents."
+    CRM = "Block that interacts with CRM services."
+    SAFETY = (
+        "Block that provides AI safety mechanisms such as detecting harmful content"
+    )
+    PRODUCTIVITY = "Block that helps with productivity"
+    ISSUE_TRACKING = "Block that helps with issue tracking"
+    MULTIMEDIA = "Block that interacts with multimedia content"
+    MARKETING = "Block that helps with marketing"
+
+    def dict(self) -> dict[str, str]:
+        return {"category": self.name, "description": self.value}
+
+
+class BlockCostType(str, Enum):
+    RUN = "run"  # cost X credits per run
+    BYTE = "byte"  # cost X credits per byte
+    SECOND = "second"  # cost X credits per second
+
+
+class BlockCost(BaseModel):
+    cost_amount: int
+    cost_filter: BlockInput
+    cost_type: BlockCostType
+
+    def __init__(
+        self,
+        cost_amount: int,
+        cost_type: BlockCostType = BlockCostType.RUN,
+        cost_filter: Optional[BlockInput] = None,
+        **data: Any,
+    ) -> None:
+        super().__init__(
+            cost_amount=cost_amount,
+            cost_filter=cost_filter or {},
+            cost_type=cost_type,
+            **data,
+        )
+
+
+class BlockInfo(BaseModel):
+    id: str
+    name: str
+    inputSchema: dict[str, Any]
+    outputSchema: dict[str, Any]
+    costs: list[BlockCost]
+    description: str
+    categories: list[dict[str, str]]
+    contributors: list[dict[str, Any]]
+    staticOutput: bool
+    uiType: str
+
+
+class BlockSchema(BaseModel):
+    cached_jsonschema: ClassVar[dict[str, Any]]
+
+    @classmethod
+    def jsonschema(cls) -> dict[str, Any]:
+        if cls.cached_jsonschema:
+            return cls.cached_jsonschema
+
+        model = jsonref.replace_refs(cls.model_json_schema(), merge_props=True)
+
+        def ref_to_dict(obj):
+            if isinstance(obj, dict):
+                # OpenAPI <3.1 does not support sibling fields that has a $ref key
+                # So sometimes, the schema has an "allOf"/"anyOf"/"oneOf" with 1 item.
+                keys = {"allOf", "anyOf", "oneOf"}
+                one_key = next((k for k in keys if k in obj and len(obj[k]) == 1), None)
+                if one_key:
+                    obj.update(obj[one_key][0])
+
+                return {
+                    key: ref_to_dict(value)
+                    for key, value in obj.items()
+                    if not key.startswith("$") and key != one_key
+                }
+            elif isinstance(obj, list):
+                return [ref_to_dict(item) for item in obj]
+
+            return obj
+
+        cls.cached_jsonschema = cast(dict[str, Any], ref_to_dict(model))
+
+        return cls.cached_jsonschema
+
+    @classmethod
+    def validate_data(cls, data: BlockInput) -> str | None:
+        return json.validate_with_jsonschema(
+            schema=cls.jsonschema(),
+            data={k: v for k, v in data.items() if v is not None},
+        )
+
+    @classmethod
+    def get_mismatch_error(cls, data: BlockInput) -> str | None:
+        return cls.validate_data(data)
+
+    @classmethod
+    def get_field_schema(cls, field_name: str) -> dict[str, Any]:
+        model_schema = cls.jsonschema().get("properties", {})
+        if not model_schema:
+            raise ValueError(f"Invalid model schema {cls}")
+
+        property_schema = model_schema.get(field_name)
+        if not property_schema:
+            raise ValueError(f"Invalid property name {field_name}")
+
+        return property_schema
+
+    @classmethod
+    def validate_field(cls, field_name: str, data: BlockInput) -> str | None:
+        """
+        Validate the data against a specific property (one of the input/output name).
+        Returns the validation error message if the data does not match the schema.
+        """
+        try:
+            property_schema = cls.get_field_schema(field_name)
+            jsonschema.validate(json.to_dict(data), property_schema)
+            return None
+        except jsonschema.ValidationError as e:
+            return str(e)
+
+    @classmethod
+    def get_fields(cls) -> set[str]:
+        return set(cls.model_fields.keys())
+
+    @classmethod
+    def get_required_fields(cls) -> set[str]:
+        return {
+            field
+            for field, field_info in cls.model_fields.items()
+            if field_info.is_required()
+        }
+
+    @classmethod
+    def __pydantic_init_subclass__(cls, **kwargs):
+        """Validates the schema definition. Rules:
+        - Fields with annotation `CredentialsMetaInput` MUST be
+          named `credentials` or `*_credentials`
+        - Fields named `credentials` or `*_credentials` MUST be
+          of type `CredentialsMetaInput`
+        """
+        super().__pydantic_init_subclass__(**kwargs)
+
+        # Reset cached JSON schema to prevent inheriting it from parent class
+        cls.cached_jsonschema = {}
+
+        credentials_fields = cls.get_credentials_fields()
+
+        for field_name in cls.get_fields():
+            if is_credentials_field_name(field_name):
+                if field_name not in credentials_fields:
+                    raise TypeError(
+                        f"Credentials field '{field_name}' on {cls.__qualname__} "
+                        f"is not of type {CredentialsMetaInput.__name__}"
+                    )
+
+                CredentialsMetaInput.validate_credentials_field_schema(
+                    cls.get_field_schema(field_name), field_name
+                )
+
+            elif field_name in credentials_fields:
+                raise KeyError(
+                    f"Credentials field '{field_name}' on {cls.__qualname__} "
+                    "has invalid name: must be 'credentials' or *_credentials"
+                )
+
+    @classmethod
+    def get_credentials_fields(cls) -> dict[str, type[CredentialsMetaInput]]:
+        return {
+            field_name: info.annotation
+            for field_name, info in cls.model_fields.items()
+            if (
+                inspect.isclass(info.annotation)
+                and issubclass(
+                    get_origin(info.annotation) or info.annotation,
+                    CredentialsMetaInput,
+                )
+            )
+        }
+
+    @classmethod
+    def get_auto_credentials_fields(cls) -> dict[str, dict[str, Any]]:
+        """
+        Get fields that have auto_credentials metadata (e.g., GoogleDriveFileInput).
+
+        Returns a dict mapping kwarg_name -> {field_name, auto_credentials_config}
+
+        Raises:
+            ValueError: If multiple fields have the same kwarg_name, as this would
+                cause silent overwriting and only the last field would be processed.
+        """
+        result: dict[str, dict[str, Any]] = {}
+        schema = cls.jsonschema()
+        properties = schema.get("properties", {})
+
+        for field_name, field_schema in properties.items():
+            auto_creds = field_schema.get("auto_credentials")
+            if auto_creds:
+                kwarg_name = auto_creds.get("kwarg_name", "credentials")
+                if kwarg_name in result:
+                    raise ValueError(
+                        f"Duplicate auto_credentials kwarg_name '{kwarg_name}' "
+                        f"in fields '{result[kwarg_name]['field_name']}' and "
+                        f"'{field_name}' on {cls.__qualname__}"
+                    )
+                result[kwarg_name] = {
+                    "field_name": field_name,
+                    "config": auto_creds,
+                }
+        return result
+
+    @classmethod
+    def get_credentials_fields_info(cls) -> dict[str, CredentialsFieldInfo]:
+        result = {}
+
+        # Regular credentials fields
+        for field_name in cls.get_credentials_fields().keys():
+            result[field_name] = CredentialsFieldInfo.model_validate(
+                cls.get_field_schema(field_name), by_alias=True
+            )
+
+        # Auto-generated credentials fields (from GoogleDriveFileInput etc.)
+        for kwarg_name, info in cls.get_auto_credentials_fields().items():
+            config = info["config"]
+            # Build a schema-like dict that CredentialsFieldInfo can parse
+            auto_schema = {
+                "credentials_provider": [config.get("provider", "google")],
+                "credentials_types": [config.get("type", "oauth2")],
+                "credentials_scopes": config.get("scopes"),
+            }
+            result[kwarg_name] = CredentialsFieldInfo.model_validate(
+                auto_schema, by_alias=True
+            )
+
+        return result
+
+    @classmethod
+    def get_input_defaults(cls, data: BlockInput) -> BlockInput:
+        return data  # Return as is, by default.
+
+    @classmethod
+    def get_missing_links(cls, data: BlockInput, links: list["Link"]) -> set[str]:
+        input_fields_from_nodes = {link.sink_name for link in links}
+        return input_fields_from_nodes - set(data)
+
+    @classmethod
+    def get_missing_input(cls, data: BlockInput) -> set[str]:
+        return cls.get_required_fields() - set(data)
+
+
+class BlockSchemaInput(BlockSchema):
+    """
+    Base schema class for block inputs.
+    All block input schemas should extend this class for consistency.
+    """
+
+    pass
+
+
+class BlockSchemaOutput(BlockSchema):
+    """
+    Base schema class for block outputs that includes a standard error field.
+    All block output schemas should extend this class to ensure consistent error handling.
+    """
+
+    error: str = SchemaField(
+        description="Error message if the operation failed", default=""
+    )
+
+
+BlockSchemaInputType = TypeVar("BlockSchemaInputType", bound=BlockSchemaInput)
+BlockSchemaOutputType = TypeVar("BlockSchemaOutputType", bound=BlockSchemaOutput)
+
+
+class EmptyInputSchema(BlockSchemaInput):
+    pass
+
+
+class EmptyOutputSchema(BlockSchemaOutput):
+    pass
+
+
+# For backward compatibility - will be deprecated
+EmptySchema = EmptyOutputSchema
+
+
+# --8<-- [start:BlockWebhookConfig]
+class BlockManualWebhookConfig(BaseModel):
+    """
+    Configuration model for webhook-triggered blocks on which
+    the user has to manually set up the webhook at the provider.
+    """
+
+    provider: ProviderName
+    """The service provider that the webhook connects to"""
+
+    webhook_type: str
+    """
+    Identifier for the webhook type. E.g. GitHub has repo and organization level hooks.
+
+    Only for use in the corresponding `WebhooksManager`.
+    """
+
+    event_filter_input: str = ""
+    """
+    Name of the block's event filter input.
+    Leave empty if the corresponding webhook doesn't have distinct event/payload types.
+    """
+
+    event_format: str = "{event}"
+    """
+    Template string for the event(s) that a block instance subscribes to.
+    Applied individually to each event selected in the event filter input.
+
+    Example: `"pull_request.{event}"` -> `"pull_request.opened"`
+    """
+
+
+class BlockWebhookConfig(BlockManualWebhookConfig):
+    """
+    Configuration model for webhook-triggered blocks for which
+    the webhook can be automatically set up through the provider's API.
+    """
+
+    resource_format: str
+    """
+    Template string for the resource that a block instance subscribes to.
+    Fields will be filled from the block's inputs (except `payload`).
+
+    Example: `f"{repo}/pull_requests"` (note: not how it's actually implemented)
+
+    Only for use in the corresponding `WebhooksManager`.
+    """
+    # --8<-- [end:BlockWebhookConfig]
+
+
+class Block(ABC, Generic[BlockSchemaInputType, BlockSchemaOutputType]):
+    def __init__(
+        self,
+        id: str = "",
+        description: str = "",
+        contributors: list["ContributorDetails"] = [],
+        categories: set[BlockCategory] | None = None,
+        input_schema: Type[BlockSchemaInputType] = EmptyInputSchema,
+        output_schema: Type[BlockSchemaOutputType] = EmptyOutputSchema,
+        test_input: BlockInput | list[BlockInput] | None = None,
+        test_output: BlockTestOutput | list[BlockTestOutput] | None = None,
+        test_mock: dict[str, Any] | None = None,
+        test_credentials: Optional[Credentials | dict[str, Credentials]] = None,
+        disabled: bool = False,
+        static_output: bool = False,
+        block_type: BlockType = BlockType.STANDARD,
+        webhook_config: Optional[BlockWebhookConfig | BlockManualWebhookConfig] = None,
+        is_sensitive_action: bool = False,
+    ):
+        """
+        Initialize the block with the given schema.
+
+        Args:
+            id: The unique identifier for the block, this value will be persisted in the
+                DB. So it should be a unique and constant across the application run.
+                Use the UUID format for the ID.
+            description: The description of the block, explaining what the block does.
+            contributors: The list of contributors who contributed to the block.
+            input_schema: The schema, defined as a Pydantic model, for the input data.
+            output_schema: The schema, defined as a Pydantic model, for the output data.
+            test_input: The list or single sample input data for the block, for testing.
+            test_output: The list or single expected output if the test_input is run.
+            test_mock: function names on the block implementation to mock on test run.
+            disabled: If the block is disabled, it will not be available for execution.
+            static_output: Whether the output links of the block are static by default.
+        """
+        from backend.data.model import NodeExecutionStats
+
+        self.id = id
+        self.input_schema = input_schema
+        self.output_schema = output_schema
+        self.test_input = test_input
+        self.test_output = test_output
+        self.test_mock = test_mock
+        self.test_credentials = test_credentials
+        self.description = description
+        self.categories = categories or set()
+        self.contributors = contributors or set()
+        self.disabled = disabled
+        self.static_output = static_output
+        self.block_type = block_type
+        self.webhook_config = webhook_config
+        self.is_sensitive_action = is_sensitive_action
+        self.execution_stats: "NodeExecutionStats" = NodeExecutionStats()
+
+        if self.webhook_config:
+            if isinstance(self.webhook_config, BlockWebhookConfig):
+                # Enforce presence of credentials field on auto-setup webhook blocks
+                if not (cred_fields := self.input_schema.get_credentials_fields()):
+                    raise TypeError(
+                        "credentials field is required on auto-setup webhook blocks"
+                    )
+                # Disallow multiple credentials inputs on webhook blocks
+                elif len(cred_fields) > 1:
+                    raise ValueError(
+                        "Multiple credentials inputs not supported on webhook blocks"
+                    )
+
+                self.block_type = BlockType.WEBHOOK
+            else:
+                self.block_type = BlockType.WEBHOOK_MANUAL
+
+            # Enforce shape of webhook event filter, if present
+            if self.webhook_config.event_filter_input:
+                event_filter_field = self.input_schema.model_fields[
+                    self.webhook_config.event_filter_input
+                ]
+                if not (
+                    isinstance(event_filter_field.annotation, type)
+                    and issubclass(event_filter_field.annotation, BaseModel)
+                    and all(
+                        field.annotation is bool
+                        for field in event_filter_field.annotation.model_fields.values()
+                    )
+                ):
+                    raise NotImplementedError(
+                        f"{self.name} has an invalid webhook event selector: "
+                        "field must be a BaseModel and all its fields must be boolean"
+                    )
+
+            # Enforce presence of 'payload' input
+            if "payload" not in self.input_schema.model_fields:
+                raise TypeError(
+                    f"{self.name} is webhook-triggered but has no 'payload' input"
+                )
+
+            # Disable webhook-triggered block if webhook functionality not available
+            if not app_config.platform_base_url:
+                self.disabled = True
+
+    @abstractmethod
+    async def run(self, input_data: BlockSchemaInputType, **kwargs) -> BlockOutput:
+        """
+        Run the block with the given input data.
+        Args:
+            input_data: The input data with the structure of input_schema.
+
+        Kwargs: Currently 14/02/2025 these include
+            graph_id: The ID of the graph.
+            node_id: The ID of the node.
+            graph_exec_id: The ID of the graph execution.
+            node_exec_id: The ID of the node execution.
+            user_id: The ID of the user.
+
+        Returns:
+            A Generator that yields (output_name, output_data).
+            output_name: One of the output name defined in Block's output_schema.
+            output_data: The data for the output_name, matching the defined schema.
+        """
+        # --- satisfy the type checker, never executed -------------
+        if False:  # noqa: SIM115
+            yield "name", "value"  # pyright: ignore[reportMissingYield]
+        raise NotImplementedError(f"{self.name} does not implement the run method.")
+
+    async def run_once(
+        self, input_data: BlockSchemaInputType, output: str, **kwargs
+    ) -> Any:
+        async for item in self.run(input_data, **kwargs):
+            name, data = item
+            if name == output:
+                return data
+        raise ValueError(f"{self.name} did not produce any output for {output}")
+
+    def merge_stats(self, stats: "NodeExecutionStats") -> "NodeExecutionStats":
+        self.execution_stats += stats
+        return self.execution_stats
+
+    @property
+    def name(self):
+        return self.__class__.__name__
+
+    def to_dict(self):
+        return {
+            "id": self.id,
+            "name": self.name,
+            "inputSchema": self.input_schema.jsonschema(),
+            "outputSchema": self.output_schema.jsonschema(),
+            "description": self.description,
+            "categories": [category.dict() for category in self.categories],
+            "contributors": [
+                contributor.model_dump() for contributor in self.contributors
+            ],
+            "staticOutput": self.static_output,
+            "uiType": self.block_type.value,
+        }
+
+    def get_info(self) -> BlockInfo:
+        from backend.data.credit import get_block_cost
+
+        return BlockInfo(
+            id=self.id,
+            name=self.name,
+            inputSchema=self.input_schema.jsonschema(),
+            outputSchema=self.output_schema.jsonschema(),
+            costs=get_block_cost(self),
+            description=self.description,
+            categories=[category.dict() for category in self.categories],
+            contributors=[
+                contributor.model_dump() for contributor in self.contributors
+            ],
+            staticOutput=self.static_output,
+            uiType=self.block_type.value,
+        )
+
+    async def execute(self, input_data: BlockInput, **kwargs) -> BlockOutput:
+        try:
+            async for output_name, output_data in self._execute(input_data, **kwargs):
+                yield output_name, output_data
+        except Exception as ex:
+            if isinstance(ex, BlockError):
+                raise ex
+            else:
+                raise (
+                    BlockExecutionError
+                    if isinstance(ex, ValueError)
+                    else BlockUnknownError
+                )(
+                    message=str(ex),
+                    block_name=self.name,
+                    block_id=self.id,
+                ) from ex
+
+    async def is_block_exec_need_review(
+        self,
+        input_data: BlockInput,
+        *,
+        user_id: str,
+        node_id: str,
+        node_exec_id: str,
+        graph_exec_id: str,
+        graph_id: str,
+        graph_version: int,
+        execution_context: "ExecutionContext",
+        **kwargs,
+    ) -> tuple[bool, BlockInput]:
+        """
+        Check if this block execution needs human review and handle the review process.
+
+        Returns:
+            Tuple of (should_pause, input_data_to_use)
+            - should_pause: True if execution should be paused for review
+            - input_data_to_use: The input data to use (may be modified by reviewer)
+        """
+        if not (
+            self.is_sensitive_action and execution_context.sensitive_action_safe_mode
+        ):
+            return False, input_data
+
+        from backend.blocks.helpers.review import HITLReviewHelper
+
+        # Handle the review request and get decision
+        decision = await HITLReviewHelper.handle_review_decision(
+            input_data=input_data,
+            user_id=user_id,
+            node_id=node_id,
+            node_exec_id=node_exec_id,
+            graph_exec_id=graph_exec_id,
+            graph_id=graph_id,
+            graph_version=graph_version,
+            block_name=self.name,
+            editable=True,
+        )
+
+        if decision is None:
+            # We're awaiting review - pause execution
+            return True, input_data
+
+        if not decision.should_proceed:
+            # Review was rejected, raise an error to stop execution
+            raise BlockExecutionError(
+                message=f"Block execution rejected by reviewer: {decision.message}",
+                block_name=self.name,
+                block_id=self.id,
+            )
+
+        # Review was approved - use the potentially modified data
+        # ReviewResult.data must be a dict for block inputs
+        reviewed_data = decision.review_result.data
+        if not isinstance(reviewed_data, dict):
+            raise BlockExecutionError(
+                message=f"Review data must be a dict for block input, got {type(reviewed_data).__name__}",
+                block_name=self.name,
+                block_id=self.id,
+            )
+        return False, reviewed_data
+
+    async def _execute(self, input_data: BlockInput, **kwargs) -> BlockOutput:
+        # Check for review requirement only if running within a graph execution context
+        # Direct block execution (e.g., from chat) skips the review process
+        has_graph_context = all(
+            key in kwargs
+            for key in (
+                "node_exec_id",
+                "graph_exec_id",
+                "graph_id",
+                "execution_context",
+            )
+        )
+        if has_graph_context:
+            should_pause, input_data = await self.is_block_exec_need_review(
+                input_data, **kwargs
+            )
+            if should_pause:
+                return
+
+        # Validate the input data (original or reviewer-modified) once
+        if error := self.input_schema.validate_data(input_data):
+            raise BlockInputError(
+                message=f"Unable to execute block with invalid input data: {error}",
+                block_name=self.name,
+                block_id=self.id,
+            )
+
+        # Use the validated input data
+        async for output_name, output_data in self.run(
+            self.input_schema(**{k: v for k, v in input_data.items() if v is not None}),
+            **kwargs,
+        ):
+            if output_name == "error":
+                raise BlockExecutionError(
+                    message=output_data, block_name=self.name, block_id=self.id
+                )
+            if self.block_type == BlockType.STANDARD and (
+                error := self.output_schema.validate_field(output_name, output_data)
+            ):
+                raise BlockOutputError(
+                    message=f"Block produced an invalid output data: {error}",
+                    block_name=self.name,
+                    block_id=self.id,
+                )
+            yield output_name, output_data
+
+    def is_triggered_by_event_type(
+        self, trigger_config: dict[str, Any], event_type: str
+    ) -> bool:
+        if not self.webhook_config:
+            raise TypeError("This method can't be used on non-trigger blocks")
+        if not self.webhook_config.event_filter_input:
+            return True
+        event_filter = trigger_config.get(self.webhook_config.event_filter_input)
+        if not event_filter:
+            raise ValueError("Event filter is not configured on trigger")
+        return event_type in [
+            self.webhook_config.event_format.format(event=k)
+            for k in event_filter
+            if event_filter[k] is True
+        ]
+
+
+# Type alias for any block with standard input/output schemas
+AnyBlockSchema: TypeAlias = Block[BlockSchemaInput, BlockSchemaOutput]

autogpt_platform/backend/backend/blocks/_utils.py

@@ -0,0 +1,122 @@
+import logging
+import os
+
+from backend.integrations.providers import ProviderName
+
+from ._base import AnyBlockSchema
+
+logger = logging.getLogger(__name__)
+
+
+def is_block_auth_configured(
+    block_cls: type[AnyBlockSchema],
+) -> bool:
+    """
+    Check if a block has a valid authentication method configured at runtime.
+
+    For example if a block is an OAuth-only block and there env vars are not set,
+    do not show it in the UI.
+
+    """
+    from backend.sdk.registry import AutoRegistry
+
+    # Create an instance to access input_schema
+    try:
+        block = block_cls()
+    except Exception as e:
+        # If we can't create a block instance, assume it's not OAuth-only
+        logger.error(f"Error creating block instance for {block_cls.__name__}: {e}")
+        return True
+    logger.debug(
+        f"Checking if block {block_cls.__name__} has a valid provider configured"
+    )
+
+    # Get all credential inputs from input schema
+    credential_inputs = block.input_schema.get_credentials_fields_info()
+    required_inputs = block.input_schema.get_required_fields()
+    if not credential_inputs:
+        logger.debug(
+            f"Block {block_cls.__name__} has no credential inputs - Treating as valid"
+        )
+        return True
+
+    # Check credential inputs
+    if len(required_inputs.intersection(credential_inputs.keys())) == 0:
+        logger.debug(
+            f"Block {block_cls.__name__} has only optional credential inputs"
+            " - will work without credentials configured"
+        )
+
+    # Check if the credential inputs for this block are correctly configured
+    for field_name, field_info in credential_inputs.items():
+        provider_names = field_info.provider
+        if not provider_names:
+            logger.warning(
+                f"Block {block_cls.__name__} "
+                f"has credential input '{field_name}' with no provider options"
+                " - Disabling"
+            )
+            return False
+
+        # If a field has multiple possible providers, each one needs to be usable to
+        # prevent breaking the UX
+        for _provider_name in provider_names:
+            provider_name = _provider_name.value
+            if provider_name in ProviderName.__members__.values():
+                logger.debug(
+                    f"Block {block_cls.__name__} credential input '{field_name}' "
+                    f"provider '{provider_name}' is part of the legacy provider system"
+                    " - Treating as valid"
+                )
+                break
+
+            provider = AutoRegistry.get_provider(provider_name)
+            if not provider:
+                logger.warning(
+                    f"Block {block_cls.__name__} credential input '{field_name}' "
+                    f"refers to unknown provider '{provider_name}' - Disabling"
+                )
+                return False
+
+            # Check the provider's supported auth types
+            if field_info.supported_types != provider.supported_auth_types:
+                logger.warning(
+                    f"Block {block_cls.__name__} credential input '{field_name}' "
+                    f"has mismatched supported auth types (field <> Provider): "
+                    f"{field_info.supported_types} != {provider.supported_auth_types}"
+                )
+
+            if not (supported_auth_types := provider.supported_auth_types):
+                # No auth methods are been configured for this provider
+                logger.warning(
+                    f"Block {block_cls.__name__} credential input '{field_name}' "
+                    f"provider '{provider_name}' "
+                    "has no authentication methods configured - Disabling"
+                )
+                return False
+
+            # Check if provider supports OAuth
+            if "oauth2" in supported_auth_types:
+                # Check if OAuth environment variables are set
+                if (oauth_config := provider.oauth_config) and bool(
+                    os.getenv(oauth_config.client_id_env_var)
+                    and os.getenv(oauth_config.client_secret_env_var)
+                ):
+                    logger.debug(
+                        f"Block {block_cls.__name__} credential input '{field_name}' "
+                        f"provider '{provider_name}' is configured for OAuth"
+                    )
+                else:
+                    logger.error(
+                        f"Block {block_cls.__name__} credential input '{field_name}' "
+                        f"provider '{provider_name}' "
+                        "is missing OAuth client ID or secret - Disabling"
+                    )
+                    return False
+
+        logger.debug(
+            f"Block {block_cls.__name__} credential input '{field_name}' is valid; "
+            f"supported credential types: {', '.join(field_info.supported_types)}"
+        )
+
+    return True

autogpt_platform/backend/backend/blocks/agent.py

@@ -1,7 +1,7 @@
 import logging
-from typing import Any, Optional
+from typing import TYPE_CHECKING, Any, Optional
 
-from backend.data.block import (
+from backend.blocks._base import (
     Block,
     BlockCategory,
     BlockInput,
@@ -9,13 +9,15 @@ from backend.data.block import (
     BlockSchema,
     BlockSchemaInput,
     BlockType,
-    get_block,
 )
 from backend.data.execution import ExecutionContext, ExecutionStatus, NodesInputMasks
 from backend.data.model import NodeExecutionStats, SchemaField
 from backend.util.json import validate_with_jsonschema
 from backend.util.retry import func_retry
 
+if TYPE_CHECKING:
+    from backend.executor.utils import LogMetadata
+
 _logger = logging.getLogger(__name__)
 
 
@@ -124,9 +126,10 @@ class AgentExecutorBlock(Block):
         graph_version: int,
         graph_exec_id: str,
         user_id: str,
-        logger,
+        logger: "LogMetadata",
     ) -> BlockOutput:
 
+        from backend.blocks import get_block
         from backend.data.execution import ExecutionEventType
         from backend.executor import utils as execution_utils
 
@@ -198,7 +201,7 @@ class AgentExecutorBlock(Block):
         self,
         graph_exec_id: str,
         user_id: str,
-        logger,
+        logger: "LogMetadata",
     ) -> None:
         from backend.executor import utils as execution_utils
 

autogpt_platform/backend/backend/blocks/ai_condition.py

@@ -1,5 +1,11 @@
 from typing import Any
 
+from backend.blocks._base import (
+    BlockCategory,
+    BlockOutput,
+    BlockSchemaInput,
+    BlockSchemaOutput,
+)
 from backend.blocks.llm import (
     DEFAULT_LLM_MODEL,
     TEST_CREDENTIALS,
@@ -11,12 +17,6 @@ from backend.blocks.llm import (
     LLMResponse,
     llm_call,
 )
-from backend.data.block import (
-    BlockCategory,
-    BlockOutput,
-    BlockSchemaInput,
-    BlockSchemaOutput,
-)
 from backend.data.model import APIKeyCredentials, NodeExecutionStats, SchemaField
 
 

autogpt_platform/backend/backend/blocks/ai_image_customizer.py

@@ -6,13 +6,14 @@ from pydantic import SecretStr
 from replicate.client import Client as ReplicateClient
 from replicate.helpers import FileOutput
 
-from backend.data.block import (
+from backend.blocks._base import (
     Block,
     BlockCategory,
     BlockOutput,
     BlockSchemaInput,
     BlockSchemaOutput,
 )
+from backend.data.execution import ExecutionContext
 from backend.data.model import (
     APIKeyCredentials,
     CredentialsField,
@@ -117,11 +118,13 @@ class AIImageCustomizerBlock(Block):
                 "credentials": TEST_CREDENTIALS_INPUT,
             },
             test_output=[
-                ("image_url", "https://replicate.delivery/generated-image.jpg"),
+                # Output will be a workspace ref or data URI depending on context
+                ("image_url", lambda x: x.startswith(("workspace://", "data:"))),
             ],
             test_mock={
+                # Use data URI to avoid HTTP requests during tests
                 "run_model": lambda *args, **kwargs: MediaFileType(
-                    "https://replicate.delivery/generated-image.jpg"
+                    "data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwD3+iiigD//2Q=="
                 ),
             },
             test_credentials=TEST_CREDENTIALS,
@@ -132,8 +135,7 @@ class AIImageCustomizerBlock(Block):
         input_data: Input,
         *,
         credentials: APIKeyCredentials,
-        graph_exec_id: str,
-        user_id: str,
+        execution_context: ExecutionContext,
         **kwargs,
     ) -> BlockOutput:
         try:
@@ -141,10 +143,9 @@ class AIImageCustomizerBlock(Block):
             processed_images = await asyncio.gather(
                 *(
                     store_media_file(
-                        graph_exec_id=graph_exec_id,
                         file=img,
-                        user_id=user_id,
-                        return_content=True,
+                        execution_context=execution_context,
+                        return_format="for_external_api",  # Get content for Replicate API
                     )
                     for img in input_data.images
                 )
@@ -158,7 +159,14 @@ class AIImageCustomizerBlock(Block):
                 aspect_ratio=input_data.aspect_ratio.value,
                 output_format=input_data.output_format.value,
             )
-            yield "image_url", result
+
+            # Store the generated image to the user's workspace for persistence
+            stored_url = await store_media_file(
+                file=result,
+                execution_context=execution_context,
+                return_format="for_block_output",
+            )
+            yield "image_url", stored_url
         except Exception as e:
             yield "error", str(e)
 

autogpt_platform/backend/backend/blocks/ai_image_generator_block.py

@@ -5,7 +5,13 @@ from pydantic import SecretStr
 from replicate.client import Client as ReplicateClient
 from replicate.helpers import FileOutput
 
-from backend.data.block import Block, BlockCategory, BlockSchemaInput, BlockSchemaOutput
+from backend.blocks._base import (
+    Block,
+    BlockCategory,
+    BlockSchemaInput,
+    BlockSchemaOutput,
+)
+from backend.data.execution import ExecutionContext
 from backend.data.model import (
     APIKeyCredentials,
     CredentialsField,
@@ -13,6 +19,8 @@ from backend.data.model import (
     SchemaField,
 )
 from backend.integrations.providers import ProviderName
+from backend.util.file import store_media_file
+from backend.util.type import MediaFileType
 
 
 class ImageSize(str, Enum):
@@ -165,11 +173,13 @@ class AIImageGeneratorBlock(Block):
             test_output=[
                 (
                     "image_url",
-                    "https://replicate.delivery/generated-image.webp",
+                    # Test output is a data URI since we now store images
+                    lambda x: x.startswith("data:image/"),
                 ),
             ],
             test_mock={
-                "_run_client": lambda *args, **kwargs: "https://replicate.delivery/generated-image.webp"
+                # Return a data URI directly so store_media_file doesn't need to download
+                "_run_client": lambda *args, **kwargs: "data:image/webp;base64,UklGRiQAAABXRUJQVlA4IBgAAAAwAQCdASoBAAEAAQAcJYgCdAEO"
             },
         )
 
@@ -318,11 +328,24 @@ class AIImageGeneratorBlock(Block):
         style_text = style_map.get(style, "")
         return f"{style_text} of" if style_text else ""
 
-    async def run(self, input_data: Input, *, credentials: APIKeyCredentials, **kwargs):
+    async def run(
+        self,
+        input_data: Input,
+        *,
+        credentials: APIKeyCredentials,
+        execution_context: ExecutionContext,
+        **kwargs,
+    ):
         try:
             url = await self.generate_image(input_data, credentials)
             if url:
-                yield "image_url", url
+                # Store the generated image to the user's workspace/execution folder
+                stored_url = await store_media_file(
+                    file=MediaFileType(url),
+                    execution_context=execution_context,
+                    return_format="for_block_output",
+                )
+                yield "image_url", stored_url
             else:
                 yield "error", "Image generation returned an empty result."
         except Exception as e:

autogpt_platform/backend/backend/blocks/ai_music_generator.py

@@ -6,7 +6,7 @@ from typing import Literal
 from pydantic import SecretStr
 from replicate.client import Client as ReplicateClient
 
-from backend.data.block import (
+from backend.blocks._base import (
     Block,
     BlockCategory,
     BlockOutput,

autogpt_platform/backend/backend/blocks/ai_shortform_video_block.py

@@ -6,13 +6,14 @@ from typing import Literal
 
 from pydantic import SecretStr
 
-from backend.data.block import (
+from backend.blocks._base import (
     Block,
     BlockCategory,
     BlockOutput,
     BlockSchemaInput,
     BlockSchemaOutput,
 )
+from backend.data.execution import ExecutionContext
 from backend.data.model import (
     APIKeyCredentials,
     CredentialsField,
@@ -21,7 +22,9 @@ from backend.data.model import (
 )
 from backend.integrations.providers import ProviderName
 from backend.util.exceptions import BlockExecutionError
+from backend.util.file import store_media_file
 from backend.util.request import Requests
+from backend.util.type import MediaFileType
 
 TEST_CREDENTIALS = APIKeyCredentials(
     id="01234567-89ab-cdef-0123-456789abcdef",
@@ -271,7 +274,10 @@ class AIShortformVideoCreatorBlock(Block):
                 "voice": Voice.LILY,
                 "video_style": VisualMediaType.STOCK_VIDEOS,
             },
-            test_output=("video_url", "https://example.com/video.mp4"),
+            test_output=(
+                "video_url",
+                lambda x: x.startswith(("workspace://", "data:")),
+            ),
             test_mock={
                 "create_webhook": lambda *args, **kwargs: (
                     "test_uuid",
@@ -280,15 +286,21 @@ class AIShortformVideoCreatorBlock(Block):
                 "create_video": lambda *args, **kwargs: {"pid": "test_pid"},
                 "check_video_status": lambda *args, **kwargs: {
                     "status": "ready",
-                    "videoUrl": "https://example.com/video.mp4",
+                    "videoUrl": "data:video/mp4;base64,AAAA",
                 },
-                "wait_for_video": lambda *args, **kwargs: "https://example.com/video.mp4",
+                # Use data URI to avoid HTTP requests during tests
+                "wait_for_video": lambda *args, **kwargs: "data:video/mp4;base64,AAAA",
             },
             test_credentials=TEST_CREDENTIALS,
         )
 
     async def run(
-        self, input_data: Input, *, credentials: APIKeyCredentials, **kwargs
+        self,
+        input_data: Input,
+        *,
+        credentials: APIKeyCredentials,
+        execution_context: ExecutionContext,
+        **kwargs,
     ) -> BlockOutput:
         # Create a new Webhook.site URL
         webhook_token, webhook_url = await self.create_webhook()
@@ -340,7 +352,13 @@ class AIShortformVideoCreatorBlock(Block):
             )
             video_url = await self.wait_for_video(credentials.api_key, pid)
             logger.debug(f"Video ready: {video_url}")
-            yield "video_url", video_url
+            # Store the generated video to the user's workspace for persistence
+            stored_url = await store_media_file(
+                file=MediaFileType(video_url),
+                execution_context=execution_context,
+                return_format="for_block_output",
+            )
+            yield "video_url", stored_url
 
 
 class AIAdMakerVideoCreatorBlock(Block):
@@ -447,7 +465,10 @@ class AIAdMakerVideoCreatorBlock(Block):
                     "https://cdn.revid.ai/uploads/1747076315114-image.png",
                 ],
             },
-            test_output=("video_url", "https://example.com/ad.mp4"),
+            test_output=(
+                "video_url",
+                lambda x: x.startswith(("workspace://", "data:")),
+            ),
             test_mock={
                 "create_webhook": lambda *args, **kwargs: (
                     "test_uuid",
@@ -456,14 +477,21 @@ class AIAdMakerVideoCreatorBlock(Block):
                 "create_video": lambda *args, **kwargs: {"pid": "test_pid"},
                 "check_video_status": lambda *args, **kwargs: {
                     "status": "ready",
-                    "videoUrl": "https://example.com/ad.mp4",
+                    "videoUrl": "data:video/mp4;base64,AAAA",
                 },
-                "wait_for_video": lambda *args, **kwargs: "https://example.com/ad.mp4",
+                "wait_for_video": lambda *args, **kwargs: "data:video/mp4;base64,AAAA",
             },
             test_credentials=TEST_CREDENTIALS,
         )
 
-    async def run(self, input_data: Input, *, credentials: APIKeyCredentials, **kwargs):
+    async def run(
+        self,
+        input_data: Input,
+        *,
+        credentials: APIKeyCredentials,
+        execution_context: ExecutionContext,
+        **kwargs,
+    ):
         webhook_token, webhook_url = await self.create_webhook()
 
         payload = {
@@ -531,7 +559,13 @@ class AIAdMakerVideoCreatorBlock(Block):
             raise RuntimeError("Failed to create video: No project ID returned")
 
         video_url = await self.wait_for_video(credentials.api_key, pid)
-        yield "video_url", video_url
+        # Store the generated video to the user's workspace for persistence
+        stored_url = await store_media_file(
+            file=MediaFileType(video_url),
+            execution_context=execution_context,
+            return_format="for_block_output",
+        )
+        yield "video_url", stored_url
 
 
 class AIScreenshotToVideoAdBlock(Block):
@@ -626,7 +660,10 @@ class AIScreenshotToVideoAdBlock(Block):
                 "script": "Amazing numbers!",
                 "screenshot_url": "https://cdn.revid.ai/uploads/1747080376028-image.png",
             },
-            test_output=("video_url", "https://example.com/screenshot.mp4"),
+            test_output=(
+                "video_url",
+                lambda x: x.startswith(("workspace://", "data:")),
+            ),
             test_mock={
                 "create_webhook": lambda *args, **kwargs: (
                     "test_uuid",
@@ -635,14 +672,21 @@ class AIScreenshotToVideoAdBlock(Block):
                 "create_video": lambda *args, **kwargs: {"pid": "test_pid"},
                 "check_video_status": lambda *args, **kwargs: {
                     "status": "ready",
-                    "videoUrl": "https://example.com/screenshot.mp4",
+                    "videoUrl": "data:video/mp4;base64,AAAA",
                 },
-                "wait_for_video": lambda *args, **kwargs: "https://example.com/screenshot.mp4",
+                "wait_for_video": lambda *args, **kwargs: "data:video/mp4;base64,AAAA",
             },
             test_credentials=TEST_CREDENTIALS,
         )
 
-    async def run(self, input_data: Input, *, credentials: APIKeyCredentials, **kwargs):
+    async def run(
+        self,
+        input_data: Input,
+        *,
+        credentials: APIKeyCredentials,
+        execution_context: ExecutionContext,
+        **kwargs,
+    ):
         webhook_token, webhook_url = await self.create_webhook()
 
         payload = {
@@ -710,4 +754,10 @@ class AIScreenshotToVideoAdBlock(Block):
             raise RuntimeError("Failed to create video: No project ID returned")
 
         video_url = await self.wait_for_video(credentials.api_key, pid)
-        yield "video_url", video_url
+        # Store the generated video to the user's workspace for persistence
+        stored_url = await store_media_file(
+            file=MediaFileType(video_url),
+            execution_context=execution_context,
+            return_format="for_block_output",
+        )
+        yield "video_url", stored_url

autogpt_platform/backend/backend/blocks/apollo/organization.py

@@ -1,3 +1,10 @@
+from backend.blocks._base import (
+    Block,
+    BlockCategory,
+    BlockOutput,
+    BlockSchemaInput,
+    BlockSchemaOutput,
+)
 from backend.blocks.apollo._api import ApolloClient
 from backend.blocks.apollo._auth import (
     TEST_CREDENTIALS,
@@ -10,13 +17,6 @@ from backend.blocks.apollo.models import (
     PrimaryPhone,
     SearchOrganizationsRequest,
 )
-from backend.data.block import (
-    Block,
-    BlockCategory,
-    BlockOutput,
-    BlockSchemaInput,
-    BlockSchemaOutput,
-)
 from backend.data.model import CredentialsField, SchemaField
 
 

autogpt_platform/backend/backend/blocks/apollo/people.py

@@ -1,5 +1,12 @@
 import asyncio
 
+from backend.blocks._base import (
+    Block,
+    BlockCategory,
+    BlockOutput,
+    BlockSchemaInput,
+    BlockSchemaOutput,
+)
 from backend.blocks.apollo._api import ApolloClient
 from backend.blocks.apollo._auth import (
     TEST_CREDENTIALS,
@@ -14,13 +21,6 @@ from backend.blocks.apollo.models import (
     SearchPeopleRequest,
     SenorityLevels,
 )
-from backend.data.block import (
-    Block,
-    BlockCategory,
-    BlockOutput,
-    BlockSchemaInput,
-    BlockSchemaOutput,
-)
 from backend.data.model import CredentialsField, SchemaField
 
 

autogpt_platform/backend/backend/blocks/apollo/person.py

@@ -1,3 +1,10 @@
+from backend.blocks._base import (
+    Block,
+    BlockCategory,
+    BlockOutput,
+    BlockSchemaInput,
+    BlockSchemaOutput,
+)
 from backend.blocks.apollo._api import ApolloClient
 from backend.blocks.apollo._auth import (
     TEST_CREDENTIALS,
@@ -6,13 +13,6 @@ from backend.blocks.apollo._auth import (
     ApolloCredentialsInput,
 )
 from backend.blocks.apollo.models import Contact, EnrichPersonRequest
-from backend.data.block import (
-    Block,
-    BlockCategory,
-    BlockOutput,
-    BlockSchemaInput,
-    BlockSchemaOutput,
-)
 from backend.data.model import CredentialsField, SchemaField
 
 

autogpt_platform/backend/backend/blocks/ayrshare/_util.py

@@ -3,7 +3,7 @@ from typing import Optional
 
 from pydantic import BaseModel, Field
 
-from backend.data.block import BlockSchemaInput
+from backend.blocks._base import BlockSchemaInput
 from backend.data.model import SchemaField, UserIntegrations
 from backend.integrations.ayrshare import AyrshareClient
 from backend.util.clients import get_database_manager_async_client

autogpt_platform/backend/backend/blocks/bannerbear/text_overlay.py

@@ -6,6 +6,7 @@ if TYPE_CHECKING:
 
 from pydantic import SecretStr
 
+from backend.data.execution import ExecutionContext
 from backend.sdk import (
     APIKeyCredentials,
     Block,
@@ -17,6 +18,8 @@ from backend.sdk import (
     Requests,
     SchemaField,
 )
+from backend.util.file import store_media_file
+from backend.util.type import MediaFileType
 
 from ._config import bannerbear
 
@@ -135,15 +138,17 @@ class BannerbearTextOverlayBlock(Block):
             },
             test_output=[
                 ("success", True),
-                ("image_url", "https://cdn.bannerbear.com/test-image.jpg"),
+                # Output will be a workspace ref or data URI depending on context
+                ("image_url", lambda x: x.startswith(("workspace://", "data:"))),
                 ("uid", "test-uid-123"),
                 ("status", "completed"),
             ],
             test_mock={
+                # Use data URI to avoid HTTP requests during tests
                 "_make_api_request": lambda *args, **kwargs: {
                     "uid": "test-uid-123",
                     "status": "completed",
-                    "image_url": "https://cdn.bannerbear.com/test-image.jpg",
+                    "image_url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAABAAEBAREA/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEBAAA/APn+v//Z",
                 }
             },
             test_credentials=TEST_CREDENTIALS,
@@ -177,7 +182,12 @@ class BannerbearTextOverlayBlock(Block):
             raise Exception(error_msg)
 
     async def run(
-        self, input_data: Input, *, credentials: APIKeyCredentials, **kwargs
+        self,
+        input_data: Input,
+        *,
+        credentials: APIKeyCredentials,
+        execution_context: ExecutionContext,
+        **kwargs,
     ) -> BlockOutput:
         # Build the modifications array
         modifications = []
@@ -234,6 +244,18 @@ class BannerbearTextOverlayBlock(Block):
 
         # Synchronous request - image should be ready
         yield "success", True
-        yield "image_url", data.get("image_url", "")
+
+        # Store the generated image to workspace for persistence
+        image_url = data.get("image_url", "")
+        if image_url:
+            stored_url = await store_media_file(
+                file=MediaFileType(image_url),
+                execution_context=execution_context,
+                return_format="for_block_output",
+            )
+            yield "image_url", stored_url
+        else:
+            yield "image_url", ""
+
         yield "uid", data.get("uid", "")
         yield "status", data.get("status", "completed")

autogpt_platform/backend/backend/blocks/basic.py

@@ -1,7 +1,7 @@
 import enum
 from typing import Any
 
-from backend.data.block import (
+from backend.blocks._base import (
     Block,
     BlockCategory,
     BlockOutput,
@@ -9,6 +9,7 @@ from backend.data.block import (
     BlockSchemaOutput,
     BlockType,
 )
+from backend.data.execution import ExecutionContext
 from backend.data.model import SchemaField
 from backend.util.file import store_media_file
 from backend.util.type import MediaFileType, convert
@@ -17,10 +18,10 @@ from backend.util.type import MediaFileType, convert
 class FileStoreBlock(Block):
     class Input(BlockSchemaInput):
         file_in: MediaFileType = SchemaField(
-            description="The file to store in the temporary directory, it can be a URL, data URI, or local path."
+            description="The file to download and store. Can be a URL (https://...), data URI, or local path."
         )
         base_64: bool = SchemaField(
-            description="Whether produce an output in base64 format (not recommended, you can pass the string path just fine accross blocks).",
+            description="Whether to produce output in base64 format (not recommended, you can pass the file reference across blocks).",
             default=False,
             advanced=True,
             title="Produce Base64 Output",
@@ -28,13 +29,18 @@ class FileStoreBlock(Block):
 
     class Output(BlockSchemaOutput):
         file_out: MediaFileType = SchemaField(
-            description="The relative path to the stored file in the temporary directory."
+            description="Reference to the stored file. In CoPilot: workspace:// URI (visible in list_workspace_files). In graphs: data URI for passing to other blocks."
         )
 
     def __init__(self):
         super().__init__(
             id="cbb50872-625b-42f0-8203-a2ae78242d8a",
-            description="Stores the input file in the temporary directory.",
+            description=(
+                "Downloads and stores a file from a URL, data URI, or local path. "
+                "Use this to fetch images, documents, or other files for processing. "
+                "In CoPilot: saves to workspace (use list_workspace_files to see it). "
+                "In graphs: outputs a data URI to pass to other blocks."
+            ),
             categories={BlockCategory.BASIC, BlockCategory.MULTIMEDIA},
             input_schema=FileStoreBlock.Input,
             output_schema=FileStoreBlock.Output,
@@ -45,15 +51,18 @@ class FileStoreBlock(Block):
         self,
         input_data: Input,
         *,
-        graph_exec_id: str,
-        user_id: str,
+        execution_context: ExecutionContext,
         **kwargs,
     ) -> BlockOutput:
+        # Determine return format based on user preference
+        # for_external_api: always returns data URI (base64) - honors "Produce Base64 Output"
+        # for_block_output: smart format - workspace:// in CoPilot, data URI in graphs
+        return_format = "for_external_api" if input_data.base_64 else "for_block_output"
+
         yield "file_out", await store_media_file(
-            graph_exec_id=graph_exec_id,
             file=input_data.file_in,
-            user_id=user_id,
-            return_content=input_data.base_64,
+            execution_context=execution_context,
+            return_format=return_format,
         )
 
 
@@ -117,6 +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)
             test_output=[
                 ("output", "Hello, World!"),
                 ("status", "printed"),

autogpt_platform/backend/backend/blocks/block.py

@@ -2,7 +2,7 @@ import os
 import re
 from typing import Type
 
-from backend.data.block import (
+from backend.blocks._base import (
     Block,
     BlockCategory,
     BlockOutput,

autogpt_platform/backend/backend/blocks/branching.py

@@ -1,7 +1,7 @@
 from enum import Enum
 from typing import Any
 
-from backend.data.block import (
+from backend.blocks._base import (
     Block,
     BlockCategory,
     BlockOutput,

autogpt_platform/backend/backend/blocks/claude_code.py

@@ -1,12 +1,12 @@
 import json
 import shlex
 import uuid
-from typing import Literal, Optional
+from typing import TYPE_CHECKING, Literal, Optional
 
 from e2b import AsyncSandbox as BaseAsyncSandbox
-from pydantic import BaseModel, SecretStr
+from pydantic import SecretStr
 
-from backend.data.block import (
+from backend.blocks._base import (
     Block,
     BlockCategory,
     BlockOutput,
@@ -20,6 +20,13 @@ from backend.data.model import (
     SchemaField,
 )
 from backend.integrations.providers import ProviderName
+from backend.util.sandbox_files import (
+    SandboxFileOutput,
+    extract_and_store_sandbox_files,
+)
+
+if TYPE_CHECKING:
+    from backend.executor.utils import ExecutionContext
 
 
 class ClaudeCodeExecutionError(Exception):
@@ -174,22 +181,15 @@ class ClaudeCodeBlock(Block):
             advanced=True,
         )
 
-    class FileOutput(BaseModel):
-        """A file extracted from the sandbox."""
-
-        path: str
-        relative_path: str  # Path relative to working directory (for GitHub, etc.)
-        name: str
-        content: str
-
     class Output(BlockSchemaOutput):
         response: str = SchemaField(
             description="The output/response from Claude Code execution"
         )
-        files: list["ClaudeCodeBlock.FileOutput"] = SchemaField(
+        files: list[SandboxFileOutput] = SchemaField(
             description=(
                 "List of text files created/modified by Claude Code during this execution. "
-                "Each file has 'path', 'relative_path', 'name', and 'content' fields."
+                "Each file has 'path', 'relative_path', 'name', 'content', and 'workspace_ref' fields. "
+                "workspace_ref contains a workspace:// URI if the file was stored to workspace."
             )
         )
         conversation_history: str = SchemaField(
@@ -252,6 +252,7 @@ class ClaudeCodeBlock(Block):
                             "relative_path": "index.html",
                             "name": "index.html",
                             "content": "<html>Hello World</html>",
+                            "workspace_ref": None,
                         }
                     ],
                 ),
@@ -267,11 +268,12 @@ class ClaudeCodeBlock(Block):
                 "execute_claude_code": lambda *args, **kwargs: (
                     "Created index.html with hello world content",  # response
                     [
-                        ClaudeCodeBlock.FileOutput(
+                        SandboxFileOutput(
                             path="/home/user/index.html",
                             relative_path="index.html",
                             name="index.html",
                             content="<html>Hello World</html>",
+                            workspace_ref=None,
                         )
                     ],  # files
                     "User: Create a hello world HTML file\n"
@@ -294,7 +296,8 @@ class ClaudeCodeBlock(Block):
         existing_sandbox_id: str,
         conversation_history: str,
         dispose_sandbox: bool,
-    ) -> tuple[str, list["ClaudeCodeBlock.FileOutput"], str, str, str]:
+        execution_context: "ExecutionContext",
+    ) -> tuple[str, list[SandboxFileOutput], str, str, str]:
         """
         Execute Claude Code in an E2B sandbox.
 
@@ -449,14 +452,18 @@ class ClaudeCodeBlock(Block):
                 else:
                     new_conversation_history = turn_entry
 
-            # Extract files created/modified during this run
-            files = await self._extract_files(
-                sandbox, working_directory, start_timestamp
+            # Extract files created/modified during this run and store to workspace
+            sandbox_files = await extract_and_store_sandbox_files(
+                sandbox=sandbox,
+                working_directory=working_directory,
+                execution_context=execution_context,
+                since_timestamp=start_timestamp,
+                text_only=True,
             )
 
             return (
                 response,
-                files,
+                sandbox_files,  # Already SandboxFileOutput objects
                 new_conversation_history,
                 current_session_id,
                 sandbox_id,
@@ -471,140 +478,6 @@ class ClaudeCodeBlock(Block):
             if dispose_sandbox and sandbox:
                 await sandbox.kill()
 
-    async def _extract_files(
-        self,
-        sandbox: BaseAsyncSandbox,
-        working_directory: str,
-        since_timestamp: str | None = None,
-    ) -> list["ClaudeCodeBlock.FileOutput"]:
-        """
-        Extract text files created/modified during this Claude Code execution.
-
-        Args:
-            sandbox: The E2B sandbox instance
-            working_directory: Directory to search for files
-            since_timestamp: ISO timestamp - only return files modified after this time
-
-        Returns:
-            List of FileOutput objects with path, relative_path, name, and content
-        """
-        files: list[ClaudeCodeBlock.FileOutput] = []
-
-        # Text file extensions we can safely read as text
-        text_extensions = {
-            ".txt",
-            ".md",
-            ".html",
-            ".htm",
-            ".css",
-            ".js",
-            ".ts",
-            ".jsx",
-            ".tsx",
-            ".json",
-            ".xml",
-            ".yaml",
-            ".yml",
-            ".toml",
-            ".ini",
-            ".cfg",
-            ".conf",
-            ".py",
-            ".rb",
-            ".php",
-            ".java",
-            ".c",
-            ".cpp",
-            ".h",
-            ".hpp",
-            ".cs",
-            ".go",
-            ".rs",
-            ".swift",
-            ".kt",
-            ".scala",
-            ".sh",
-            ".bash",
-            ".zsh",
-            ".sql",
-            ".graphql",
-            ".env",
-            ".gitignore",
-            ".dockerfile",
-            "Dockerfile",
-            ".vue",
-            ".svelte",
-            ".astro",
-            ".mdx",
-            ".rst",
-            ".tex",
-            ".csv",
-            ".log",
-        }
-
-        try:
-            # List files recursively using find command
-            # Exclude node_modules and .git directories, but allow hidden files
-            # like .env and .gitignore (they're filtered by text_extensions later)
-            # Filter by timestamp to only get files created/modified during this run
-            safe_working_dir = shlex.quote(working_directory)
-            timestamp_filter = ""
-            if since_timestamp:
-                timestamp_filter = f"-newermt {shlex.quote(since_timestamp)} "
-            find_result = await sandbox.commands.run(
-                f"find {safe_working_dir} -type f "
-                f"{timestamp_filter}"
-                f"-not -path '*/node_modules/*' "
-                f"-not -path '*/.git/*' "
-                f"2>/dev/null"
-            )
-
-            if find_result.stdout:
-                for file_path in find_result.stdout.strip().split("\n"):
-                    if not file_path:
-                        continue
-
-                    # Check if it's a text file we can read
-                    is_text = any(
-                        file_path.endswith(ext) for ext in text_extensions
-                    ) or file_path.endswith("Dockerfile")
-
-                    if is_text:
-                        try:
-                            content = await sandbox.files.read(file_path)
-                            # Handle bytes or string
-                            if isinstance(content, bytes):
-                                content = content.decode("utf-8", errors="replace")
-
-                            # Extract filename from path
-                            file_name = file_path.split("/")[-1]
-
-                            # Calculate relative path by stripping working directory
-                            relative_path = file_path
-                            if file_path.startswith(working_directory):
-                                relative_path = file_path[len(working_directory) :]
-                                # Remove leading slash if present
-                                if relative_path.startswith("/"):
-                                    relative_path = relative_path[1:]
-
-                            files.append(
-                                ClaudeCodeBlock.FileOutput(
-                                    path=file_path,
-                                    relative_path=relative_path,
-                                    name=file_name,
-                                    content=content,
-                                )
-                            )
-                        except Exception:
-                            # Skip files that can't be read
-                            pass
-
-        except Exception:
-            # If file extraction fails, return empty results
-            pass
-
-        return files
-
     def _escape_prompt(self, prompt: str) -> str:
         """Escape the prompt for safe shell execution."""
         # Use single quotes and escape any single quotes in the prompt
@@ -617,6 +490,7 @@ class ClaudeCodeBlock(Block):
         *,
         e2b_credentials: APIKeyCredentials,
         anthropic_credentials: APIKeyCredentials,
+        execution_context: "ExecutionContext",
         **kwargs,
     ) -> BlockOutput:
         try:
@@ -637,6 +511,7 @@ class ClaudeCodeBlock(Block):
                 existing_sandbox_id=input_data.sandbox_id,
                 conversation_history=input_data.conversation_history,
                 dispose_sandbox=input_data.dispose_sandbox,
+                execution_context=execution_context,
             )
 
             yield "response", response

autogpt_platform/backend/backend/blocks/code_executor.py

@@ -1,12 +1,12 @@
 from enum import Enum
-from typing import Any, Literal, Optional
+from typing import TYPE_CHECKING, Any, Literal, Optional
 
 from e2b_code_interpreter import AsyncSandbox
 from e2b_code_interpreter import Result as E2BExecutionResult
 from e2b_code_interpreter.charts import Chart as E2BExecutionResultChart
 from pydantic import BaseModel, Field, JsonValue, SecretStr
 
-from backend.data.block import (
+from backend.blocks._base import (
     Block,
     BlockCategory,
     BlockOutput,
@@ -20,6 +20,13 @@ from backend.data.model import (
     SchemaField,
 )
 from backend.integrations.providers import ProviderName
+from backend.util.sandbox_files import (
+    SandboxFileOutput,
+    extract_and_store_sandbox_files,
+)
+
+if TYPE_CHECKING:
+    from backend.executor.utils import ExecutionContext
 
 TEST_CREDENTIALS = APIKeyCredentials(
     id="01234567-89ab-cdef-0123-456789abcdef",
@@ -85,6 +92,9 @@ class CodeExecutionResult(MainCodeExecutionResult):
 class BaseE2BExecutorMixin:
     """Shared implementation methods for E2B executor blocks."""
 
+    # Default working directory in E2B sandboxes
+    WORKING_DIR = "/home/user"
+
     async def execute_code(
         self,
         api_key: str,
@@ -95,14 +105,21 @@ class BaseE2BExecutorMixin:
         timeout: Optional[int] = None,
         sandbox_id: Optional[str] = None,
         dispose_sandbox: bool = False,
+        execution_context: Optional["ExecutionContext"] = None,
+        extract_files: bool = False,
     ):
         """
         Unified code execution method that handles all three use cases:
         1. Create new sandbox and execute (ExecuteCodeBlock)
         2. Create new sandbox, execute, and return sandbox_id (InstantiateCodeSandboxBlock)
         3. Connect to existing sandbox and execute (ExecuteCodeStepBlock)
+
+        Args:
+            extract_files: If True and execution_context provided, extract files
+                           created/modified during execution and store to workspace.
         """  # noqa
         sandbox = None
+        files: list[SandboxFileOutput] = []
         try:
             if sandbox_id:
                 # Connect to existing sandbox (ExecuteCodeStepBlock case)
@@ -118,6 +135,12 @@ class BaseE2BExecutorMixin:
                     for cmd in setup_commands:
                         await sandbox.commands.run(cmd)
 
+            # Capture timestamp before execution to scope file extraction
+            start_timestamp = None
+            if extract_files:
+                ts_result = await sandbox.commands.run("date -u +%Y-%m-%dT%H:%M:%S")
+                start_timestamp = ts_result.stdout.strip() if ts_result.stdout else None
+
             # Execute the code
             execution = await sandbox.run_code(
                 code,
@@ -133,7 +156,24 @@ class BaseE2BExecutorMixin:
             stdout_logs = "".join(execution.logs.stdout)
             stderr_logs = "".join(execution.logs.stderr)
 
-            return results, text_output, stdout_logs, stderr_logs, sandbox.sandbox_id
+            # Extract files created/modified during this execution
+            if extract_files and execution_context:
+                files = await extract_and_store_sandbox_files(
+                    sandbox=sandbox,
+                    working_directory=self.WORKING_DIR,
+                    execution_context=execution_context,
+                    since_timestamp=start_timestamp,
+                    text_only=False,  # Include binary files too
+                )
+
+            return (
+                results,
+                text_output,
+                stdout_logs,
+                stderr_logs,
+                sandbox.sandbox_id,
+                files,
+            )
         finally:
             # Dispose of sandbox if requested to reduce usage costs
             if dispose_sandbox and sandbox:
@@ -238,6 +278,12 @@ class ExecuteCodeBlock(Block, BaseE2BExecutorMixin):
             description="Standard output logs from execution"
         )
         stderr_logs: str = SchemaField(description="Standard error logs from execution")
+        files: list[SandboxFileOutput] = SchemaField(
+            description=(
+                "Files created or modified during execution. "
+                "Each file has path, name, content, and workspace_ref (if stored)."
+            ),
+        )
 
     def __init__(self):
         super().__init__(
@@ -259,23 +305,30 @@ class ExecuteCodeBlock(Block, BaseE2BExecutorMixin):
                 ("results", []),
                 ("response", "Hello World"),
                 ("stdout_logs", "Hello World\n"),
+                ("files", []),
             ],
             test_mock={
-                "execute_code": lambda api_key, code, language, template_id, setup_commands, timeout, dispose_sandbox: (  # noqa
+                "execute_code": lambda api_key, code, language, template_id, setup_commands, timeout, dispose_sandbox, execution_context, extract_files: (  # noqa
                     [],  # results
                     "Hello World",  # text_output
                     "Hello World\n",  # stdout_logs
                     "",  # stderr_logs
                     "sandbox_id",  # sandbox_id
+                    [],  # files
                 ),
             },
         )
 
     async def run(
-        self, input_data: Input, *, credentials: APIKeyCredentials, **kwargs
+        self,
+        input_data: Input,
+        *,
+        credentials: APIKeyCredentials,
+        execution_context: "ExecutionContext",
+        **kwargs,
     ) -> BlockOutput:
         try:
-            results, text_output, stdout, stderr, _ = await self.execute_code(
+            results, text_output, stdout, stderr, _, files = await self.execute_code(
                 api_key=credentials.api_key.get_secret_value(),
                 code=input_data.code,
                 language=input_data.language,
@@ -283,6 +336,8 @@ class ExecuteCodeBlock(Block, BaseE2BExecutorMixin):
                 setup_commands=input_data.setup_commands,
                 timeout=input_data.timeout,
                 dispose_sandbox=input_data.dispose_sandbox,
+                execution_context=execution_context,
+                extract_files=True,
             )
 
             # Determine result object shape & filter out empty formats
@@ -296,6 +351,8 @@ class ExecuteCodeBlock(Block, BaseE2BExecutorMixin):
                 yield "stdout_logs", stdout
             if stderr:
                 yield "stderr_logs", stderr
+            # Always yield files (empty list if none)
+            yield "files", [f.model_dump() for f in files]
         except Exception as e:
             yield "error", str(e)
 
@@ -393,6 +450,7 @@ class InstantiateCodeSandboxBlock(Block, BaseE2BExecutorMixin):
                     "Hello World\n",  # stdout_logs
                     "",  # stderr_logs
                     "sandbox_id",  # sandbox_id
+                    [],  # files
                 ),
             },
         )
@@ -401,7 +459,7 @@ class InstantiateCodeSandboxBlock(Block, BaseE2BExecutorMixin):
         self, input_data: Input, *, credentials: APIKeyCredentials, **kwargs
     ) -> BlockOutput:
         try:
-            _, text_output, stdout, stderr, sandbox_id = await self.execute_code(
+            _, text_output, stdout, stderr, sandbox_id, _ = await self.execute_code(
                 api_key=credentials.api_key.get_secret_value(),
                 code=input_data.setup_code,
                 language=input_data.language,
@@ -500,6 +558,7 @@ class ExecuteCodeStepBlock(Block, BaseE2BExecutorMixin):
                     "Hello World\n",  # stdout_logs
                     "",  # stderr_logs
                     sandbox_id,  # sandbox_id
+                    [],  # files
                 ),
             },
         )
@@ -508,7 +567,7 @@ class ExecuteCodeStepBlock(Block, BaseE2BExecutorMixin):
         self, input_data: Input, *, credentials: APIKeyCredentials, **kwargs
     ) -> BlockOutput:
         try:
-            results, text_output, stdout, stderr, _ = await self.execute_code(
+            results, text_output, stdout, stderr, _, _ = await self.execute_code(
                 api_key=credentials.api_key.get_secret_value(),
                 code=input_data.step_code,
                 language=input_data.language,

autogpt_platform/backend/backend/blocks/code_extraction_block.py

@@ -1,6 +1,6 @@
 import re
 
-from backend.data.block import (
+from backend.blocks._base import (
     Block,
     BlockCategory,
     BlockOutput,

autogpt_platform/backend/backend/blocks/codex.py

@@ -6,7 +6,7 @@ from openai import AsyncOpenAI
 from openai.types.responses import Response as OpenAIResponse
 from pydantic import SecretStr
 
-from backend.data.block import (
+from backend.blocks._base import (
     Block,
     BlockCategory,
     BlockOutput,

autogpt_platform/backend/backend/blocks/compass/triggers.py

@@ -1,6 +1,6 @@
 from pydantic import BaseModel
 
-from backend.data.block import (
+from backend.blocks._base import (
     Block,
     BlockCategory,
     BlockManualWebhookConfig,

autogpt_platform/backend/backend/blocks/count_words_and_char_block.py

@@ -1,4 +1,4 @@
-from backend.data.block import (
+from backend.blocks._base import (
     Block,
     BlockCategory,
     BlockOutput,

autogpt_platform/backend/backend/blocks/data_manipulation.py

@@ -1,6 +1,6 @@
 from typing import Any, List
 
-from backend.data.block import (
+from backend.blocks._base import (
     Block,
     BlockCategory,
     BlockOutput,
@@ -682,17 +682,219 @@ class ListIsEmptyBlock(Block):
         yield "is_empty", len(input_data.list) == 0
 
 
+# =============================================================================
+# List Concatenation Helpers
+# =============================================================================
+
+
+def _validate_list_input(item: Any, index: int) -> str | None:
+    """Validate that an item is a list. Returns error message or None."""
+    if item is None:
+        return None  # None is acceptable, will be skipped
+    if not isinstance(item, list):
+        return (
+            f"Invalid input at index {index}: expected a list, "
+            f"got {type(item).__name__}. "
+            f"All items in 'lists' must be lists (e.g., [[1, 2], [3, 4]])."
+        )
+    return None
+
+
+def _validate_all_lists(lists: List[Any]) -> str | None:
+    """Validate that all items in a sequence are lists. Returns first error or None."""
+    for idx, item in enumerate(lists):
+        error = _validate_list_input(item, idx)
+        if error is not None and item is not None:
+            return error
+    return None
+
+
+def _concatenate_lists_simple(lists: List[List[Any]]) -> List[Any]:
+    """Concatenate a sequence of lists into a single list, skipping None values."""
+    result: List[Any] = []
+    for lst in lists:
+        if lst is None:
+            continue
+        result.extend(lst)
+    return result
+
+
+def _flatten_nested_list(nested: List[Any], max_depth: int = -1) -> List[Any]:
+    """
+    Recursively flatten a nested list structure.
+
+    Args:
+        nested: The list to flatten.
+        max_depth: Maximum recursion depth. -1 means unlimited.
+
+    Returns:
+        A flat list with all nested elements extracted.
+    """
+    result: List[Any] = []
+    _flatten_recursive(nested, result, current_depth=0, max_depth=max_depth)
+    return result
+
+
+_MAX_FLATTEN_DEPTH = 1000
+
+
+def _flatten_recursive(
+    items: List[Any],
+    result: List[Any],
+    current_depth: int,
+    max_depth: int,
+) -> None:
+    """Internal recursive helper for flattening nested lists."""
+    if current_depth > _MAX_FLATTEN_DEPTH:
+        raise RecursionError(
+            f"Flattening exceeded maximum depth of {_MAX_FLATTEN_DEPTH} levels. "
+            "Input may be too deeply nested."
+        )
+    for item in items:
+        if isinstance(item, list) and (max_depth == -1 or current_depth < max_depth):
+            _flatten_recursive(item, result, current_depth + 1, max_depth)
+        else:
+            result.append(item)
+
+
+def _deduplicate_list(items: List[Any]) -> List[Any]:
+    """
+    Remove duplicate elements from a list, preserving order of first occurrences.
+
+    Args:
+        items: The list to deduplicate.
+
+    Returns:
+        A list with duplicates removed, maintaining original order.
+    """
+    seen: set = set()
+    result: List[Any] = []
+    for item in items:
+        item_id = _make_hashable(item)
+        if item_id not in seen:
+            seen.add(item_id)
+            result.append(item)
+    return result
+
+
+def _make_hashable(item: Any):
+    """
+    Create a hashable representation of any item for deduplication.
+    Converts unhashable types (dicts, lists) into deterministic tuple structures.
+    """
+    if isinstance(item, dict):
+        return tuple(
+            sorted(
+                ((_make_hashable(k), _make_hashable(v)) for k, v in item.items()),
+                key=lambda x: (str(type(x[0])), str(x[0])),
+            )
+        )
+    if isinstance(item, (list, tuple)):
+        return tuple(_make_hashable(i) for i in item)
+    if isinstance(item, set):
+        return frozenset(_make_hashable(i) for i in item)
+    return item
+
+
+def _filter_none_values(items: List[Any]) -> List[Any]:
+    """Remove None values from a list."""
+    return [item for item in items if item is not None]
+
+
+def _compute_nesting_depth(
+    items: Any, current: int = 0, max_depth: int = _MAX_FLATTEN_DEPTH
+) -> int:
+    """
+    Compute the maximum nesting depth of a list structure using iteration to avoid RecursionError.
+
+    Uses a stack-based approach to handle deeply nested structures without hitting Python's
+    recursion limit (~1000 levels).
+    """
+    if not isinstance(items, list):
+        return current
+
+    # Stack contains tuples of (item, depth)
+    stack = [(items, current)]
+    max_observed_depth = current
+
+    while stack:
+        item, depth = stack.pop()
+
+        if depth > max_depth:
+            return depth
+
+        if not isinstance(item, list):
+            max_observed_depth = max(max_observed_depth, depth)
+            continue
+
+        if len(item) == 0:
+            max_observed_depth = max(max_observed_depth, depth + 1)
+            continue
+
+        # Add all children to stack with incremented depth
+        for child in item:
+            stack.append((child, depth + 1))
+
+    return max_observed_depth
+
+
+def _interleave_lists(lists: List[List[Any]]) -> List[Any]:
+    """
+    Interleave elements from multiple lists in round-robin fashion.
+    Example: [[1,2,3], [a,b], [x,y,z]] -> [1, a, x, 2, b, y, 3, z]
+    """
+    if not lists:
+        return []
+    filtered = [lst for lst in lists if lst is not None]
+    if not filtered:
+        return []
+    result: List[Any] = []
+    max_len = max(len(lst) for lst in filtered)
+    for i in range(max_len):
+        for lst in filtered:
+            if i < len(lst):
+                result.append(lst[i])
+    return result
+
+
+# =============================================================================
+# List Concatenation Blocks
+# =============================================================================
+
+
 class ConcatenateListsBlock(Block):
+    """
+    Concatenates two or more lists into a single list.
+
+    This block accepts a list of lists and combines all their elements
+    in order into one flat output list. It supports options for
+    deduplication and None-filtering to provide flexible list merging
+    capabilities for workflow pipelines.
+    """
+
     class Input(BlockSchemaInput):
         lists: List[List[Any]] = SchemaField(
             description="A list of lists to concatenate together. All lists will be combined in order into a single list.",
             placeholder="e.g., [[1, 2], [3, 4], [5, 6]]",
         )
+        deduplicate: bool = SchemaField(
+            description="If True, remove duplicate elements from the concatenated result while preserving order.",
+            default=False,
+            advanced=True,
+        )
+        remove_none: bool = SchemaField(
+            description="If True, remove None values from the concatenated result.",
+            default=False,
+            advanced=True,
+        )
 
     class Output(BlockSchemaOutput):
         concatenated_list: List[Any] = SchemaField(
             description="The concatenated list containing all elements from all input lists in order."
         )
+        length: int = SchemaField(
+            description="The total number of elements in the concatenated list."
+        )
         error: str = SchemaField(
             description="Error message if concatenation failed due to invalid input types."
         )
@@ -700,7 +902,7 @@ class ConcatenateListsBlock(Block):
     def __init__(self):
         super().__init__(
             id="3cf9298b-5817-4141-9d80-7c2cc5199c8e",
-            description="Concatenates multiple lists into a single list. All elements from all input lists are combined in order.",
+            description="Concatenates multiple lists into a single list. All elements from all input lists are combined in order. Supports optional deduplication and None removal.",
             categories={BlockCategory.BASIC},
             input_schema=ConcatenateListsBlock.Input,
             output_schema=ConcatenateListsBlock.Output,
@@ -709,29 +911,497 @@ class ConcatenateListsBlock(Block):
                 {"lists": [["a", "b"], ["c"], ["d", "e", "f"]]},
                 {"lists": [[1, 2], []]},
                 {"lists": []},
+                {"lists": [[1, 2, 2, 3], [3, 4]], "deduplicate": True},
+                {"lists": [[1, None, 2], [None, 3]], "remove_none": True},
             ],
             test_output=[
                 ("concatenated_list", [1, 2, 3, 4, 5, 6]),
+                ("length", 6),
                 ("concatenated_list", ["a", "b", "c", "d", "e", "f"]),
+                ("length", 6),
                 ("concatenated_list", [1, 2]),
+                ("length", 2),
                 ("concatenated_list", []),
+                ("length", 0),
+                ("concatenated_list", [1, 2, 3, 4]),
+                ("length", 4),
+                ("concatenated_list", [1, 2, 3]),
+                ("length", 3),
             ],
         )
 
+    def _validate_inputs(self, lists: List[Any]) -> str | None:
+        return _validate_all_lists(lists)
+
+    def _perform_concatenation(self, lists: List[List[Any]]) -> List[Any]:
+        return _concatenate_lists_simple(lists)
+
+    def _apply_deduplication(self, items: List[Any]) -> List[Any]:
+        return _deduplicate_list(items)
+
+    def _apply_none_removal(self, items: List[Any]) -> List[Any]:
+        return _filter_none_values(items)
+
+    def _post_process(
+        self, items: List[Any], deduplicate: bool, remove_none: bool
+    ) -> List[Any]:
+        """Apply all post-processing steps to the concatenated result."""
+        result = items
+        if remove_none:
+            result = self._apply_none_removal(result)
+        if deduplicate:
+            result = self._apply_deduplication(result)
+        return result
+
     async def run(self, input_data: Input, **kwargs) -> BlockOutput:
-        concatenated = []
-        for idx, lst in enumerate(input_data.lists):
-            if lst is None:
-                # Skip None values to avoid errors
-                continue
-            if not isinstance(lst, list):
-                # Type validation: each item must be a list
-                # Strings are iterable and would cause extend() to iterate character-by-character
-                # Non-iterable types would raise TypeError
-                yield "error", (
-                    f"Invalid input at index {idx}: expected a list, got {type(lst).__name__}. "
-                    f"All items in 'lists' must be lists (e.g., [[1, 2], [3, 4]])."
-                )
-                return
-            concatenated.extend(lst)
-        yield "concatenated_list", concatenated
+        # Validate all inputs are lists
+        validation_error = self._validate_inputs(input_data.lists)
+        if validation_error is not None:
+            yield "error", validation_error
+            return
+
+        # Perform concatenation
+        concatenated = self._perform_concatenation(input_data.lists)
+
+        # Apply post-processing
+        result = self._post_process(
+            concatenated, input_data.deduplicate, input_data.remove_none
+        )
+
+        yield "concatenated_list", result
+        yield "length", len(result)
+
+
+class FlattenListBlock(Block):
+    """
+    Flattens a nested list structure into a single flat list.
+
+    This block takes a list that may contain nested lists at any depth
+    and produces a single-level list with all leaf elements. Useful
+    for normalizing data structures from multiple sources that may
+    have varying levels of nesting.
+    """
+
+    class Input(BlockSchemaInput):
+        nested_list: List[Any] = SchemaField(
+            description="A potentially nested list to flatten into a single-level list.",
+            placeholder="e.g., [[1, [2, 3]], [4, [5, [6]]]]",
+        )
+        max_depth: int = SchemaField(
+            description="Maximum depth to flatten. -1 means flatten completely. 1 means flatten only one level.",
+            default=-1,
+            advanced=True,
+        )
+
+    class Output(BlockSchemaOutput):
+        flattened_list: List[Any] = SchemaField(
+            description="The flattened list with all nested elements extracted."
+        )
+        length: int = SchemaField(
+            description="The number of elements in the flattened list."
+        )
+        original_depth: int = SchemaField(
+            description="The maximum nesting depth of the original input list."
+        )
+        error: str = SchemaField(description="Error message if flattening failed.")
+
+    def __init__(self):
+        super().__init__(
+            id="cc45bb0f-d035-4756-96a7-fe3e36254b4d",
+            description="Flattens a nested list structure into a single flat list. Supports configurable maximum flattening depth.",
+            categories={BlockCategory.BASIC},
+            input_schema=FlattenListBlock.Input,
+            output_schema=FlattenListBlock.Output,
+            test_input=[
+                {"nested_list": [[1, 2], [3, [4, 5]]]},
+                {"nested_list": [1, [2, [3, [4]]]]},
+                {"nested_list": [1, [2, [3, [4]]], 5], "max_depth": 1},
+                {"nested_list": []},
+                {"nested_list": [1, 2, 3]},
+            ],
+            test_output=[
+                ("flattened_list", [1, 2, 3, 4, 5]),
+                ("length", 5),
+                ("original_depth", 3),
+                ("flattened_list", [1, 2, 3, 4]),
+                ("length", 4),
+                ("original_depth", 4),
+                ("flattened_list", [1, 2, [3, [4]], 5]),
+                ("length", 4),
+                ("original_depth", 4),
+                ("flattened_list", []),
+                ("length", 0),
+                ("original_depth", 1),
+                ("flattened_list", [1, 2, 3]),
+                ("length", 3),
+                ("original_depth", 1),
+            ],
+        )
+
+    def _compute_depth(self, items: List[Any]) -> int:
+        """Compute the nesting depth of the input list."""
+        return _compute_nesting_depth(items)
+
+    def _flatten(self, items: List[Any], max_depth: int) -> List[Any]:
+        """Flatten the list to the specified depth."""
+        return _flatten_nested_list(items, max_depth=max_depth)
+
+    def _validate_max_depth(self, max_depth: int) -> str | None:
+        """Validate the max_depth parameter."""
+        if max_depth < -1:
+            return f"max_depth must be -1 (unlimited) or a non-negative integer, got {max_depth}"
+        return None
+
+    async def run(self, input_data: Input, **kwargs) -> BlockOutput:
+        # Validate max_depth
+        depth_error = self._validate_max_depth(input_data.max_depth)
+        if depth_error is not None:
+            yield "error", depth_error
+            return
+
+        original_depth = self._compute_depth(input_data.nested_list)
+        flattened = self._flatten(input_data.nested_list, input_data.max_depth)
+
+        yield "flattened_list", flattened
+        yield "length", len(flattened)
+        yield "original_depth", original_depth
+
+
+class InterleaveListsBlock(Block):
+    """
+    Interleaves elements from multiple lists in round-robin fashion.
+
+    Given multiple input lists, this block takes one element from each
+    list in turn, producing an output where elements alternate between
+    sources. Lists of different lengths are handled gracefully - shorter
+    lists simply stop contributing once exhausted.
+    """
+
+    class Input(BlockSchemaInput):
+        lists: List[List[Any]] = SchemaField(
+            description="A list of lists to interleave. Elements will be taken in round-robin order.",
+            placeholder="e.g., [[1, 2, 3], ['a', 'b', 'c']]",
+        )
+
+    class Output(BlockSchemaOutput):
+        interleaved_list: List[Any] = SchemaField(
+            description="The interleaved list with elements alternating from each input list."
+        )
+        length: int = SchemaField(
+            description="The total number of elements in the interleaved list."
+        )
+        error: str = SchemaField(description="Error message if interleaving failed.")
+
+    def __init__(self):
+        super().__init__(
+            id="9f616084-1d9f-4f8e-bc00-5b9d2a75cd75",
+            description="Interleaves elements from multiple lists in round-robin fashion, alternating between sources.",
+            categories={BlockCategory.BASIC},
+            input_schema=InterleaveListsBlock.Input,
+            output_schema=InterleaveListsBlock.Output,
+            test_input=[
+                {"lists": [[1, 2, 3], ["a", "b", "c"]]},
+                {"lists": [[1, 2, 3], ["a", "b"], ["x", "y", "z"]]},
+                {"lists": [[1], [2], [3]]},
+                {"lists": []},
+            ],
+            test_output=[
+                ("interleaved_list", [1, "a", 2, "b", 3, "c"]),
+                ("length", 6),
+                ("interleaved_list", [1, "a", "x", 2, "b", "y", 3, "z"]),
+                ("length", 8),
+                ("interleaved_list", [1, 2, 3]),
+                ("length", 3),
+                ("interleaved_list", []),
+                ("length", 0),
+            ],
+        )
+
+    def _validate_inputs(self, lists: List[Any]) -> str | None:
+        return _validate_all_lists(lists)
+
+    def _interleave(self, lists: List[List[Any]]) -> List[Any]:
+        return _interleave_lists(lists)
+
+    async def run(self, input_data: Input, **kwargs) -> BlockOutput:
+        validation_error = self._validate_inputs(input_data.lists)
+        if validation_error is not None:
+            yield "error", validation_error
+            return
+
+        result = self._interleave(input_data.lists)
+        yield "interleaved_list", result
+        yield "length", len(result)
+
+
+class ZipListsBlock(Block):
+    """
+    Zips multiple lists together into a list of grouped tuples/lists.
+
+    Takes two or more input lists and combines corresponding elements
+    into sub-lists. For example, zipping [1,2,3] and ['a','b','c']
+    produces [[1,'a'], [2,'b'], [3,'c']]. Supports both truncating
+    to shortest list and padding to longest list with a fill value.
+    """
+
+    class Input(BlockSchemaInput):
+        lists: List[List[Any]] = SchemaField(
+            description="A list of lists to zip together. Corresponding elements will be grouped.",
+            placeholder="e.g., [[1, 2, 3], ['a', 'b', 'c']]",
+        )
+        pad_to_longest: bool = SchemaField(
+            description="If True, pad shorter lists with fill_value to match the longest list. If False, truncate to shortest.",
+            default=False,
+            advanced=True,
+        )
+        fill_value: Any = SchemaField(
+            description="Value to use for padding when pad_to_longest is True.",
+            default=None,
+            advanced=True,
+        )
+
+    class Output(BlockSchemaOutput):
+        zipped_list: List[List[Any]] = SchemaField(
+            description="The zipped list of grouped elements."
+        )
+        length: int = SchemaField(
+            description="The number of groups in the zipped result."
+        )
+        error: str = SchemaField(description="Error message if zipping failed.")
+
+    def __init__(self):
+        super().__init__(
+            id="0d0e684f-5cb9-4c4b-b8d1-47a0860e0c07",
+            description="Zips multiple lists together into a list of grouped elements. Supports padding to longest or truncating to shortest.",
+            categories={BlockCategory.BASIC},
+            input_schema=ZipListsBlock.Input,
+            output_schema=ZipListsBlock.Output,
+            test_input=[
+                {"lists": [[1, 2, 3], ["a", "b", "c"]]},
+                {"lists": [[1, 2, 3], ["a", "b"]]},
+                {
+                    "lists": [[1, 2], ["a", "b", "c"]],
+                    "pad_to_longest": True,
+                    "fill_value": 0,
+                },
+                {"lists": []},
+            ],
+            test_output=[
+                ("zipped_list", [[1, "a"], [2, "b"], [3, "c"]]),
+                ("length", 3),
+                ("zipped_list", [[1, "a"], [2, "b"]]),
+                ("length", 2),
+                ("zipped_list", [[1, "a"], [2, "b"], [0, "c"]]),
+                ("length", 3),
+                ("zipped_list", []),
+                ("length", 0),
+            ],
+        )
+
+    def _validate_inputs(self, lists: List[Any]) -> str | None:
+        return _validate_all_lists(lists)
+
+    def _zip_truncate(self, lists: List[List[Any]]) -> List[List[Any]]:
+        """Zip lists, truncating to shortest."""
+        filtered = [lst for lst in lists if lst is not None]
+        if not filtered:
+            return []
+        return [list(group) for group in zip(*filtered)]
+
+    def _zip_pad(self, lists: List[List[Any]], fill_value: Any) -> List[List[Any]]:
+        """Zip lists, padding shorter ones with fill_value."""
+        if not lists:
+            return []
+        lists = [lst for lst in lists if lst is not None]
+        if not lists:
+            return []
+        max_len = max(len(lst) for lst in lists)
+        result: List[List[Any]] = []
+        for i in range(max_len):
+            group: List[Any] = []
+            for lst in lists:
+                if i < len(lst):
+                    group.append(lst[i])
+                else:
+                    group.append(fill_value)
+            result.append(group)
+        return result
+
+    async def run(self, input_data: Input, **kwargs) -> BlockOutput:
+        validation_error = self._validate_inputs(input_data.lists)
+        if validation_error is not None:
+            yield "error", validation_error
+            return
+
+        if not input_data.lists:
+            yield "zipped_list", []
+            yield "length", 0
+            return
+
+        if input_data.pad_to_longest:
+            result = self._zip_pad(input_data.lists, input_data.fill_value)
+        else:
+            result = self._zip_truncate(input_data.lists)
+
+        yield "zipped_list", result
+        yield "length", len(result)
+
+
+class ListDifferenceBlock(Block):
+    """
+    Computes the difference between two lists (elements in the first
+    list that are not in the second list).
+
+    This is useful for finding items that exist in one dataset but
+    not in another, such as finding new items, missing items, or
+    items that need to be processed.
+    """
+
+    class Input(BlockSchemaInput):
+        list_a: List[Any] = SchemaField(
+            description="The primary list to check elements from.",
+            placeholder="e.g., [1, 2, 3, 4, 5]",
+        )
+        list_b: List[Any] = SchemaField(
+            description="The list to subtract. Elements found here will be removed from list_a.",
+            placeholder="e.g., [3, 4, 5, 6]",
+        )
+        symmetric: bool = SchemaField(
+            description="If True, compute symmetric difference (elements in either list but not both).",
+            default=False,
+            advanced=True,
+        )
+
+    class Output(BlockSchemaOutput):
+        difference: List[Any] = SchemaField(
+            description="Elements from list_a not found in list_b (or symmetric difference if enabled)."
+        )
+        length: int = SchemaField(
+            description="The number of elements in the difference result."
+        )
+        error: str = SchemaField(description="Error message if the operation failed.")
+
+    def __init__(self):
+        super().__init__(
+            id="05309873-9d61-447e-96b5-b804e2511829",
+            description="Computes the difference between two lists. Returns elements in the first list not found in the second, or symmetric difference.",
+            categories={BlockCategory.BASIC},
+            input_schema=ListDifferenceBlock.Input,
+            output_schema=ListDifferenceBlock.Output,
+            test_input=[
+                {"list_a": [1, 2, 3, 4, 5], "list_b": [3, 4, 5, 6, 7]},
+                {
+                    "list_a": [1, 2, 3, 4, 5],
+                    "list_b": [3, 4, 5, 6, 7],
+                    "symmetric": True,
+                },
+                {"list_a": ["a", "b", "c"], "list_b": ["b"]},
+                {"list_a": [], "list_b": [1, 2, 3]},
+            ],
+            test_output=[
+                ("difference", [1, 2]),
+                ("length", 2),
+                ("difference", [1, 2, 6, 7]),
+                ("length", 4),
+                ("difference", ["a", "c"]),
+                ("length", 2),
+                ("difference", []),
+                ("length", 0),
+            ],
+        )
+
+    def _compute_difference(self, list_a: List[Any], list_b: List[Any]) -> List[Any]:
+        """Compute elements in list_a not in list_b."""
+        b_hashes = {_make_hashable(item) for item in list_b}
+        return [item for item in list_a if _make_hashable(item) not in b_hashes]
+
+    def _compute_symmetric_difference(
+        self, list_a: List[Any], list_b: List[Any]
+    ) -> List[Any]:
+        """Compute elements in either list but not both."""
+        a_hashes = {_make_hashable(item) for item in list_a}
+        b_hashes = {_make_hashable(item) for item in list_b}
+        only_in_a = [item for item in list_a if _make_hashable(item) not in b_hashes]
+        only_in_b = [item for item in list_b if _make_hashable(item) not in a_hashes]
+        return only_in_a + only_in_b
+
+    async def run(self, input_data: Input, **kwargs) -> BlockOutput:
+        if input_data.symmetric:
+            result = self._compute_symmetric_difference(
+                input_data.list_a, input_data.list_b
+            )
+        else:
+            result = self._compute_difference(input_data.list_a, input_data.list_b)
+
+        yield "difference", result
+        yield "length", len(result)
+
+
+class ListIntersectionBlock(Block):
+    """
+    Computes the intersection of two lists (elements present in both lists).
+
+    This is useful for finding common items between two datasets,
+    such as shared tags, mutual connections, or overlapping categories.
+    """
+
+    class Input(BlockSchemaInput):
+        list_a: List[Any] = SchemaField(
+            description="The first list to intersect.",
+            placeholder="e.g., [1, 2, 3, 4, 5]",
+        )
+        list_b: List[Any] = SchemaField(
+            description="The second list to intersect.",
+            placeholder="e.g., [3, 4, 5, 6, 7]",
+        )
+
+    class Output(BlockSchemaOutput):
+        intersection: List[Any] = SchemaField(
+            description="Elements present in both list_a and list_b."
+        )
+        length: int = SchemaField(
+            description="The number of elements in the intersection."
+        )
+        error: str = SchemaField(description="Error message if the operation failed.")
+
+    def __init__(self):
+        super().__init__(
+            id="b6eb08b6-dbe3-411b-b9b4-2508cb311a1f",
+            description="Computes the intersection of two lists, returning only elements present in both.",
+            categories={BlockCategory.BASIC},
+            input_schema=ListIntersectionBlock.Input,
+            output_schema=ListIntersectionBlock.Output,
+            test_input=[
+                {"list_a": [1, 2, 3, 4, 5], "list_b": [3, 4, 5, 6, 7]},
+                {"list_a": ["a", "b", "c"], "list_b": ["c", "d", "e"]},
+                {"list_a": [1, 2], "list_b": [3, 4]},
+                {"list_a": [], "list_b": [1, 2, 3]},
+            ],
+            test_output=[
+                ("intersection", [3, 4, 5]),
+                ("length", 3),
+                ("intersection", ["c"]),
+                ("length", 1),
+                ("intersection", []),
+                ("length", 0),
+                ("intersection", []),
+                ("length", 0),
+            ],
+        )
+
+    def _compute_intersection(self, list_a: List[Any], list_b: List[Any]) -> List[Any]:
+        """Compute elements present in both lists, preserving order from list_a."""
+        b_hashes = {_make_hashable(item) for item in list_b}
+        seen: set = set()
+        result: List[Any] = []
+        for item in list_a:
+            h = _make_hashable(item)
+            if h in b_hashes and h not in seen:
+                result.append(item)
+                seen.add(h)
+        return result
+
+    async def run(self, input_data: Input, **kwargs) -> BlockOutput:
+        result = self._compute_intersection(input_data.list_a, input_data.list_b)
+        yield "intersection", result
+        yield "length", len(result)

autogpt_platform/backend/backend/blocks/decoder_block.py

@@ -1,6 +1,6 @@
 import codecs
 
-from backend.data.block import (
+from backend.blocks._base import (
     Block,
     BlockCategory,
     BlockOutput,

autogpt_platform/backend/backend/blocks/discord/bot_blocks.py

@@ -8,13 +8,14 @@ from typing import Any, Literal, cast
 import discord
 from pydantic import SecretStr
 
-from backend.data.block import (
+from backend.blocks._base import (
     Block,
     BlockCategory,
     BlockOutput,
     BlockSchemaInput,
     BlockSchemaOutput,
 )
+from backend.data.execution import ExecutionContext
 from backend.data.model import APIKeyCredentials, SchemaField
 from backend.util.file import store_media_file
 from backend.util.request import Requests
@@ -666,8 +667,7 @@ class SendDiscordFileBlock(Block):
         file: MediaFileType,
         filename: str,
         message_content: str,
-        graph_exec_id: str,
-        user_id: str,
+        execution_context: ExecutionContext,
     ) -> dict:
         intents = discord.Intents.default()
         intents.guilds = True
@@ -731,10 +731,9 @@ class SendDiscordFileBlock(Block):
                     # Local file path - read from stored media file
                     # This would be a path from a previous block's output
                     stored_file = await store_media_file(
-                        graph_exec_id=graph_exec_id,
                         file=file,
-                        user_id=user_id,
-                        return_content=True,  # Get as data URI
+                        execution_context=execution_context,
+                        return_format="for_external_api",  # Get content to send to Discord
                     )
                     # Now process as data URI
                     header, encoded = stored_file.split(",", 1)
@@ -781,8 +780,7 @@ class SendDiscordFileBlock(Block):
         input_data: Input,
         *,
         credentials: APIKeyCredentials,
-        graph_exec_id: str,
-        user_id: str,
+        execution_context: ExecutionContext,
         **kwargs,
     ) -> BlockOutput:
         try:
@@ -793,8 +791,7 @@ class SendDiscordFileBlock(Block):
                 file=input_data.file,
                 filename=input_data.filename,
                 message_content=input_data.message_content,
-                graph_exec_id=graph_exec_id,
-                user_id=user_id,
+                execution_context=execution_context,
             )
 
             yield "status", result.get("status", "Unknown error")

autogpt_platform/backend/backend/blocks/discord/oauth_blocks.py

@@ -2,7 +2,7 @@
 Discord OAuth-based blocks.
 """
 
-from backend.data.block import (
+from backend.blocks._base import (
     Block,
     BlockCategory,
     BlockOutput,

autogpt_platform/backend/backend/blocks/elevenlabs/_auth.py

@@ -0,0 +1,28 @@
+"""ElevenLabs integration blocks - test credentials and shared utilities."""
+
+from typing import Literal
+
+from pydantic import SecretStr
+
+from backend.data.model import APIKeyCredentials, CredentialsMetaInput
+from backend.integrations.providers import ProviderName
+
+TEST_CREDENTIALS = APIKeyCredentials(
+    id="01234567-89ab-cdef-0123-456789abcdef",
+    provider="elevenlabs",
+    api_key=SecretStr("mock-elevenlabs-api-key"),
+    title="Mock ElevenLabs API key",
+    expires_at=None,
+)
+
+TEST_CREDENTIALS_INPUT = {
+    "provider": TEST_CREDENTIALS.provider,
+    "id": TEST_CREDENTIALS.id,
+    "type": TEST_CREDENTIALS.type,
+    "title": TEST_CREDENTIALS.title,
+}
+
+ElevenLabsCredentials = APIKeyCredentials
+ElevenLabsCredentialsInput = CredentialsMetaInput[
+    Literal[ProviderName.ELEVENLABS], Literal["api_key"]
+]