tests(LLM): add concurrency and provider-mapping reinit tests; fix style

Co-authored-by: openhands <openhands@all-hands.dev>

.github/CODEOWNERS

@@ -2,7 +2,8 @@
 # See https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
 
 # Frontend code owners
-/frontend/ @rbren @amanape
+/frontend/ @amanape
+/openhands-ui/ @amanape
 
 # Evaluation code owners
 /evaluation/ @xingyaoww @neubig

.github/scripts/update_pr_description.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+
+set -euxo pipefail
+
+# This script updates the PR description with commands to run the PR locally
+# It adds both Docker and uvx commands
+
+# Get the branch name for the PR
+BRANCH_NAME=$(gh pr view "$PR_NUMBER" --json headRefName --jq .headRefName)
+
+# Define the Docker command
+DOCKER_RUN_COMMAND="docker run -it --rm \
+  -p 3000:3000 \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  --add-host host.docker.internal:host-gateway \
+  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:${SHORT_SHA}-nikolaik \
+  --name openhands-app-${SHORT_SHA} \
+  docker.all-hands.dev/all-hands-ai/openhands:${SHORT_SHA}"
+
+# Define the uvx command
+UVX_RUN_COMMAND="uvx --python 3.12 --from git+https://github.com/All-Hands-AI/OpenHands@${BRANCH_NAME} openhands"
+
+# Get the current PR body
+PR_BODY=$(gh pr view "$PR_NUMBER" --json body --jq .body)
+
+# Prepare the new PR body with both commands
+if echo "$PR_BODY" | grep -q "To run this PR locally, use the following command:"; then
+  # For existing PR descriptions, use a more robust approach
+  # Split the PR body at the "To run this PR locally" section and replace everything after it
+  BEFORE_SECTION=$(echo "$PR_BODY" | sed '/To run this PR locally, use the following command:/,$d')
+  NEW_PR_BODY=$(cat <<EOF
+${BEFORE_SECTION}
+
+To run this PR locally, use the following command:
+
+GUI with Docker:
+\`\`\`
+${DOCKER_RUN_COMMAND}
+\`\`\`
+
+CLI with uvx:
+\`\`\`
+${UVX_RUN_COMMAND}
+\`\`\`
+EOF
+)
+else
+  # For new PR descriptions: use heredoc safely without indentation
+  NEW_PR_BODY=$(cat <<EOF
+$PR_BODY
+
+---
+
+To run this PR locally, use the following command:
+
+GUI with Docker:
+\`\`\`
+${DOCKER_RUN_COMMAND}
+\`\`\`
+
+CLI with uvx:
+\`\`\`
+${UVX_RUN_COMMAND}
+\`\`\`
+EOF
+)
+fi
+
+# Update the PR description
+echo "Updating PR description with Docker and uvx commands"
+gh pr edit "$PR_NUMBER" --body "$NEW_PR_BODY"

.github/workflows/fe-unit-tests.yml

@@ -9,8 +9,8 @@ on:
       - main
   pull_request:
     paths:
-      - 'frontend/**'
-      -  '.github/workflows/fe-unit-tests.yml'
+      - "frontend/**"
+      - ".github/workflows/fe-unit-tests.yml"
 
 # If triggered by a PR, it will be in the same group. However, each commit on main will be in its own unique group
 concurrency:
@@ -24,7 +24,7 @@ jobs:
     runs-on: blacksmith-4vcpu-ubuntu-2204
     strategy:
       matrix:
-        node-version: [20, 22]
+        node-version: [22]
       fail-fast: true
     steps:
       - name: Checkout
@@ -38,7 +38,7 @@ jobs:
         run: npm ci
       - name: Run TypeScript compilation
         working-directory: ./frontend
-        run: npm run make-i18n && tsc
+        run: npm run build
       - name: Run tests and collect coverage
         working-directory: ./frontend
         run: npm run test:coverage

.github/workflows/ghcr-build.yml

@@ -40,7 +40,8 @@ jobs:
           # Only build nikolaik on PRs, otherwise build both nikolaik and ubuntu.
           if [[ "$GITHUB_EVENT_NAME" == "pull_request" ]]; then
             json=$(jq -n -c '[
-                { image: "nikolaik/python-nodejs:python3.12-nodejs22", tag: "nikolaik" }
+                { image: "nikolaik/python-nodejs:python3.12-nodejs22", tag: "nikolaik" },
+                { image: "ubuntu:24.04", tag: "ubuntu" }
               ]')
           else
             json=$(jq -n -c '[
@@ -54,12 +55,10 @@ jobs:
   ghcr_build_app:
     name: Build App Image
     runs-on: blacksmith-4vcpu-ubuntu-2204
+    if: "!(github.event_name == 'push' && startsWith(github.ref, 'refs/tags/ext-v'))"
     permissions:
       contents: read
       packages: write
-    outputs:
-      # Since this job uses outputs it cannot use matrix
-      hash_from_app_image: ${{ steps.get_hash_in_app_image.outputs.hash_from_app_image }}
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -85,24 +84,12 @@ jobs:
         if: "!github.event.pull_request.head.repo.fork"
         run: |
           ./containers/build.sh -i openhands -o ${{ env.REPO_OWNER }} --push
-      - name: Build app image
-        if: "github.event.pull_request.head.repo.fork"
-        run: |
-          ./containers/build.sh -i openhands -o ${{ env.REPO_OWNER }} --load
-      - name: Get hash in App Image
-        id: get_hash_in_app_image
-        run: |
-          # Run the build script in the app image
-          docker run -e SANDBOX_USER_ID=0 -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/${{ env.REPO_OWNER }}/openhands:${{ env.RELEVANT_SHA }} /bin/bash -c "mkdir -p containers/runtime; python3 openhands/runtime/utils/runtime_build.py --base_image ${{ env.BASE_IMAGE_FOR_HASH_EQUIVALENCE_TEST }} --build_folder containers/runtime --force_rebuild" 2>&1 | tee docker-outputs.txt
-          # Get the hash from the build script
-          hash_from_app_image=$(cat docker-outputs.txt | grep "Hash for docker build directory" | awk -F "): " '{print $2}' | uniq | head -n1)
-          echo "hash_from_app_image=$hash_from_app_image" >> $GITHUB_OUTPUT
-          echo "Hash from app image: $hash_from_app_image"
 
   # Builds the runtime Docker images
   ghcr_build_runtime:
     name: Build Image
-    runs-on: blacksmith-4vcpu-ubuntu-2204
+    runs-on: blacksmith-8vcpu-ubuntu-2204
+    if: "!(github.event_name == 'push' && startsWith(github.ref, 'refs/tags/ext-v'))"
     permissions:
       contents: read
       packages: write
@@ -128,22 +115,13 @@ jobs:
       - name: Set up Docker Buildx
         id: buildx
         uses: docker/setup-buildx-action@v3
+      - name: Install poetry via pipx
+        run: pipx install poetry
       - name: Set up Python
         uses: useblacksmith/setup-python@v6
         with:
           python-version: '3.12'
-      - name: Cache Poetry dependencies
-        uses: useblacksmith/cache@v5
-        with:
-          path: |
-            ~/.cache/pypoetry
-            ~/.virtualenvs
-          key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
-          # This is the one that saves the cache, the others set 'lookup-only: true'
-          restore-keys: |
-            ${{ runner.os }}-poetry-
-      - name: Install poetry via pipx
-        run: pipx install poetry
+          cache: poetry
       - name: Install Python dependencies using Poetry
         run: make install-python-dependencies POETRY_GROUP=main INSTALL_PLAYWRIGHT=0
       - name: Create source distribution and Dockerfile
@@ -188,61 +166,6 @@ jobs:
           name: runtime-src-${{ matrix.base_image.tag }}
           path: containers/runtime
 
-  verify_hash_equivalence_in_runtime_and_app:
-    name: Verify Hash Equivalence in Runtime and Docker images
-    runs-on: blacksmith-4vcpu-ubuntu-2204
-    needs: [ghcr_build_runtime, ghcr_build_app]
-    strategy:
-      fail-fast: false
-      matrix:
-        base_image: ['nikolaik']
-    env:
-      BASE_IMAGE_FOR_HASH_EQUIVALENCE_TEST: nikolaik/python-nodejs:python3.12-nodejs22
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          ref: ${{ github.event.pull_request.head.sha }}
-      - name: Cache Poetry dependencies
-        uses: useblacksmith/cache@v5
-        with:
-          path: |
-            ~/.cache/pypoetry
-            ~/.virtualenvs
-          key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
-          lookup-only: true
-          restore-keys: |
-            ${{ runner.os }}-poetry-
-      - name: Set up Python
-        uses: useblacksmith/setup-python@v6
-        with:
-          python-version: '3.12'
-      - name: Install poetry via pipx
-        run: pipx install poetry
-      - name: Install Python dependencies using Poetry
-        run: make install-python-dependencies POETRY_GROUP=main INSTALL_PLAYWRIGHT=0
-      - name: Get hash in App Image
-        run: |
-          echo "Hash from app image: ${{ needs.ghcr_build_app.outputs.hash_from_app_image }}"
-          echo "hash_from_app_image=${{ needs.ghcr_build_app.outputs.hash_from_app_image }}" >> $GITHUB_ENV
-
-      - name: Get hash using code (development mode)
-        run: |
-          mkdir -p containers/runtime
-          poetry run python3 openhands/runtime/utils/runtime_build.py --base_image ${{ env.BASE_IMAGE_FOR_HASH_EQUIVALENCE_TEST }} --build_folder containers/runtime --force_rebuild > output.txt 2>&1
-          hash_from_code=$(cat output.txt | grep "Hash for docker build directory" | awk -F "): " '{print $2}' | uniq | head -n1)
-          echo "hash_from_code=$hash_from_code" >> $GITHUB_ENV
-
-      - name: Compare hashes
-        run: |
-          echo "Hash from App Image: ${{ env.hash_from_app_image }}"
-          echo "Hash from Code: ${{ env.hash_from_code }}"
-          if [ "${{ env.hash_from_app_image }}" = "${{ env.hash_from_code }}" ]; then
-            echo "Hashes match!"
-          else
-            echo "Hashes do not match!"
-            exit 1
-          fi
-
   # Run unit tests with the Docker runtime Docker images as root
   test_runtime_root:
     name: RT Unit Tests (Root)
@@ -274,25 +197,17 @@ jobs:
           load: true
           tags: ghcr.io/${{ env.REPO_OWNER }}/runtime:${{ env.RELEVANT_SHA }}-${{ matrix.base_image.tag }}
           context: containers/runtime
-      - name: Cache Poetry dependencies
-        uses: useblacksmith/cache@v5
-        with:
-          path: |
-            ~/.cache/pypoetry
-            ~/.virtualenvs
-          key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
-          lookup-only: true
-          restore-keys: |
-            ${{ runner.os }}-poetry-
+      - name: Install poetry via pipx
+        run: pipx install poetry
       - name: Set up Python
         uses: useblacksmith/setup-python@v6
         with:
           python-version: '3.12'
-      - name: Install poetry via pipx
-        run: pipx install poetry
+          cache: poetry
       - name: Install Python dependencies using Poetry
         run: make install-python-dependencies INSTALL_PLAYWRIGHT=0
       - name: Run docker runtime tests
+        shell: bash
         run: |
           # We install pytest-xdist in order to run tests across CPUs
           poetry run pip install pytest-xdist
@@ -344,25 +259,17 @@ jobs:
           load: true
           tags: ghcr.io/${{ env.REPO_OWNER }}/runtime:${{ env.RELEVANT_SHA }}-${{ matrix.base_image.tag }}
           context: containers/runtime
-      - name: Cache Poetry dependencies
-        uses: useblacksmith/cache@v5
-        with:
-          path: |
-            ~/.cache/pypoetry
-            ~/.virtualenvs
-          key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
-          lookup-only: true
-          restore-keys: |
-            ${{ runner.os }}-poetry-
+      - name: Install poetry via pipx
+        run: pipx install poetry
       - name: Set up Python
         uses: useblacksmith/setup-python@v6
         with:
           python-version: '3.12'
-      - name: Install poetry via pipx
-        run: pipx install poetry
+          cache: poetry
       - name: Install Python dependencies using Poetry
         run: make install-python-dependencies POETRY_GROUP=main,test,runtime INSTALL_PLAYWRIGHT=0
       - name: Run runtime tests
+        shell: bash
         run: |
           # We install pytest-xdist in order to run tests across CPUs
           poetry run pip install pytest-xdist
@@ -389,7 +296,7 @@ jobs:
     name: All Runtime Tests Passed
     if: ${{ !cancelled() && !contains(needs.*.result, 'failure') && !contains(needs.*.result, 'cancelled') }}
     runs-on: blacksmith-4vcpu-ubuntu-2204
-    needs: [test_runtime_root, test_runtime_oh, verify_hash_equivalence_in_runtime_and_app]
+    needs: [test_runtime_root, test_runtime_oh]
     steps:
       - name: All tests passed
         run: echo "All runtime tests have passed successfully!"
@@ -398,7 +305,7 @@ jobs:
     name: All Runtime Tests Passed
     if: ${{ cancelled() || contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}
     runs-on: blacksmith-4vcpu-ubuntu-2204
-    needs: [test_runtime_root, test_runtime_oh, verify_hash_equivalence_in_runtime_and_app]
+    needs: [test_runtime_root, test_runtime_oh]
     steps:
       - name: Some tests failed
         run: |
@@ -423,30 +330,7 @@ jobs:
           PR_NUMBER: ${{ github.event.pull_request.number }}
           REPO: ${{ github.repository }}
           SHORT_SHA: ${{ steps.short_sha.outputs.SHORT_SHA }}
+        shell: bash
         run: |
-          echo "updating PR description"
-          DOCKER_RUN_COMMAND="docker run -it --rm \
-            -p 3000:3000 \
-            -v /var/run/docker.sock:/var/run/docker.sock \
-            --add-host host.docker.internal:host-gateway \
-            -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:$SHORT_SHA-nikolaik \
-            --name openhands-app-$SHORT_SHA \
-            docker.all-hands.dev/all-hands-ai/openhands:$SHORT_SHA"
-
-          PR_BODY=$(gh pr view $PR_NUMBER --json body --jq .body)
-
-          if echo "$PR_BODY" | grep -q "To run this PR locally, use the following command:"; then
-            UPDATED_PR_BODY=$(echo "${PR_BODY}" | sed -E "s|docker run -it --rm.*|$DOCKER_RUN_COMMAND|")
-          else
-            UPDATED_PR_BODY="${PR_BODY}
-
-          ---
-
-          To run this PR locally, use the following command:
-          \`\`\`
-          $DOCKER_RUN_COMMAND
-          \`\`\`"
-          fi
-
-          echo "updated body: $UPDATED_PR_BODY"
-          gh pr edit $PR_NUMBER --body "$UPDATED_PR_BODY"
+          echo "Updating PR description with Docker and uvx commands"
+          bash ${GITHUB_WORKSPACE}/.github/scripts/update_pr_description.sh

.github/workflows/integration-runner.yml

@@ -54,7 +54,7 @@ jobs:
             Hi! I started running the integration tests on your PR. You will receive a comment with the results shortly.
 
       - name: Install Python dependencies using Poetry
-        run: poetry install --with dev,test,runtime
+        run: poetry install --with dev,test,runtime,evaluation
 
       - name: Configure config.toml for testing with Haiku
         env:
@@ -179,8 +179,8 @@ jobs:
         id: create_comment
         uses: KeisukeYamashita/create-comment@v1
         with:
-          # if triggered by PR, use PR number, otherwise use 5318 as fallback issue number for manual triggers
-          number: ${{ github.event_name == 'pull_request' && github.event.pull_request.number || 5318 }}
+          # if triggered by PR, use PR number, otherwise use 9745 as fallback issue number for manual triggers
+          number: ${{ github.event_name == 'pull_request' && github.event.pull_request.number || 9745 }}
           unique: false
           comment: |
               Trigger by: ${{ github.event_name == 'pull_request' && format('Pull Request (integration-test label on PR #{0})', github.event.pull_request.number) || (github.event_name == 'workflow_dispatch' && format('Manual Trigger: {0}', github.event.inputs.reason)) || 'Nightly Scheduled Run' }}

.github/workflows/lint-fix.yml

@@ -21,10 +21,10 @@ jobs:
           fetch-depth: 0
           token: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Install Node.js 20
+      - name: Install Node.js 22
         uses: useblacksmith/setup-node@v5
         with:
-          node-version: 20
+          node-version: 22
       - name: Install frontend dependencies
         run: |
           cd frontend
@@ -68,7 +68,7 @@ jobs:
         uses: useblacksmith/setup-python@v6
         with:
           python-version: 3.12
-          cache: 'pip'
+          cache: "pip"
       - name: Install pre-commit
         run: pip install pre-commit==3.7.0
       - name: Fix python lint issues

.github/workflows/lint.yml

@@ -7,7 +7,7 @@ name: Lint
 on:
   push:
     branches:
-    - main
+      - main
   pull_request:
 
 # If triggered by a PR, it will be in the same group. However, each commit on main will be in its own unique group
@@ -22,10 +22,10 @@ jobs:
     runs-on: blacksmith-4vcpu-ubuntu-2204
     steps:
       - uses: actions/checkout@v4
-      - name: Install Node.js 20
+      - name: Install Node.js 22
         uses: useblacksmith/setup-node@v5
         with:
-          node-version: 20
+          node-version: 22
       - name: Install dependencies
         run: |
           cd frontend
@@ -49,7 +49,7 @@ jobs:
         uses: useblacksmith/setup-python@v6
         with:
           python-version: 3.12
-          cache: 'pip'
+          cache: "pip"
       - name: Install pre-commit
         run: pip install pre-commit==3.7.0
       - name: Run pre-commit hooks

.github/workflows/npm-publish-ui.yml

@@ -0,0 +1,108 @@
+name: Publish OpenHands UI Package
+
+# * Always run on "main"
+# * Run on PRs that have changes in the "openhands-ui" folder or this workflow
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "openhands-ui/**"
+      - ".github/workflows/npm-publish-ui.yml"
+
+# If triggered by a PR, it will be in the same group. However, each commit on main will be in its own unique group
+concurrency:
+  group: npm-publish-ui
+  cancel-in-progress: false
+
+jobs:
+  check-version:
+    name: Check if version has changed
+    runs-on: blacksmith-4vcpu-ubuntu-2204
+    defaults:
+      run:
+        shell: bash
+    outputs:
+      should-publish: ${{ steps.version-check.outputs.should-publish }}
+      current-version: ${{ steps.version-check.outputs.current-version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2 # Need previous commit to compare
+
+      - name: Check if version changed
+        id: version-check
+        run: |
+          # Get current version from package.json
+          CURRENT_VERSION=$(jq -r .version openhands-ui/package.json)
+          echo "current-version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+
+          # Check if package.json version changed in this commit
+          if git diff HEAD~1 HEAD --name-only | grep -q "openhands-ui/package.json"; then
+            # Check if the version field specifically changed
+            if git diff HEAD~1 HEAD openhands-ui/package.json | grep -q '"version"'; then
+              echo "Version changed in package.json, will publish"
+              echo "should-publish=true" >> $GITHUB_OUTPUT
+            else
+              echo "package.json changed but version did not change, skipping publish"
+              echo "should-publish=false" >> $GITHUB_OUTPUT
+            fi
+          else
+            echo "package.json did not change, skipping publish"
+            echo "should-publish=false" >> $GITHUB_OUTPUT
+          fi
+
+  publish:
+    name: Publish to npm
+    runs-on: blacksmith-4vcpu-ubuntu-2204
+    needs: check-version
+    if: needs.check-version.outputs.should-publish == 'true'
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: "openhands-ui/.bun-version"
+
+      - name: Install dependencies
+        working-directory: ./openhands-ui
+        run: bun install --frozen-lockfile
+
+      - name: Build package
+        working-directory: ./openhands-ui
+        run: bun run build
+
+      - name: Check if package already exists on npm
+        id: npm-check
+        working-directory: ./openhands-ui
+        run: |
+          PACKAGE_NAME=$(jq -r .name package.json)
+          VERSION="${{ needs.check-version.outputs.current-version }}"
+
+          # Check if this version already exists on npm
+          if npm view "$PACKAGE_NAME@$VERSION" version 2>/dev/null; then
+            echo "Version $VERSION already exists on npm, skipping publish"
+            echo "already-exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "Version $VERSION does not exist on npm, proceeding with publish"
+            echo "already-exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Setup npm authentication
+        if: steps.npm-check.outputs.already-exists == 'false'
+        run: |
+          echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > ~/.npmrc
+
+      - name: Publish to npm
+        if: steps.npm-check.outputs.already-exists == 'false'
+        working-directory: ./openhands-ui
+        run: |
+          # The prepublishOnly script will run automatically and build the package
+          npm publish
+          echo "✅ Successfully published @openhands/ui@${{ needs.check-version.outputs.current-version }} to npm"

.github/workflows/py-tests.yml

@@ -1,5 +1,5 @@
-# Workflow that runs python unit tests
-name: Run Python Unit Tests
+# Workflow that runs python tests
+name: Run Python Tests
 
 # The jobs in this workflow are required, so they must run at all times
 # * Always run on "main"
@@ -16,9 +16,9 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  # Run python unit tests on Linux
+  # Run python tests on Linux
   test-on-linux:
-    name: Python Unit Tests on Linux
+    name: Python Tests on Linux
     runs-on: blacksmith-4vcpu-ubuntu-2204
     env:
       INSTALL_DOCKER: '0' # Set to '0' to skip Docker installation
@@ -48,9 +48,11 @@ jobs:
       - name: Build Environment
         run: make build
       - name: Run Unit Tests
-        run: poetry run pytest --forked -n auto -svv ./tests/unit
+        run: PYTHONPATH=".:$PYTHONPATH" poetry run pytest --forked -n auto -svv ./tests/unit
       - name: Run Runtime Tests with CLIRuntime
-        run: TEST_RUNTIME=cli poetry run pytest -svv tests/runtime/test_bash.py
+        run: PYTHONPATH=".:$PYTHONPATH" TEST_RUNTIME=cli poetry run pytest -svv tests/runtime/test_bash.py
+      - name: Run E2E Tests
+        run: PYTHONPATH=".:$PYTHONPATH" poetry run pytest -svv tests/e2e
 
   # Run specific Windows python tests
   test-on-windows:
@@ -75,9 +77,11 @@ jobs:
       - name: Run Windows unit tests
         run: poetry run pytest -svv tests/unit/test_windows_bash.py
         env:
+          PYTHONPATH: ".;$env:PYTHONPATH"
           DEBUG: "1"
       - name: Run Windows runtime tests with LocalRuntime
         run: $env:TEST_RUNTIME="local"; poetry run pytest -svv tests/runtime/test_bash.py
         env:
+          PYTHONPATH: ".;$env:PYTHONPATH"
           TEST_RUNTIME: local
           DEBUG: "1"

.github/workflows/run-eval.yml

@@ -1,56 +1,135 @@
-# Run evaluation on a PR
+# Run evaluation on a PR, after releases, or manually
 name: Run Eval
 
-# Runs when a PR is labeled with one of the "run-eval-" labels
+# Runs when a PR is labeled with one of the "run-eval-" labels, after releases, or manually triggered
 on:
   pull_request:
     types: [labeled]
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: 'Branch to evaluate'
+        required: true
+        default: 'main'
+      eval_instances:
+        description: 'Number of evaluation instances'
+        required: true
+        default: '50'
+        type: choice
+        options:
+          - '1'
+          - '2'
+          - '50'
+          - '100'
+      reason:
+        description: 'Reason for manual trigger'
+        required: false
+        default: ''
+
+env:
+  # Environment variable for the master GitHub issue number where all evaluation results will be commented
+  # This should be set to the issue number where you want all evaluation results to be posted
+  MASTER_EVAL_ISSUE_NUMBER: ${{ vars.MASTER_EVAL_ISSUE_NUMBER || '0' }}
 
 jobs:
   trigger-job:
     name: Trigger remote eval job
-    if: ${{ github.event.label.name == 'run-eval-1' || github.event.label.name == 'run-eval-2' || github.event.label.name == 'run-eval-50' || github.event.label.name == 'run-eval-100' }}
+    if: ${{ (github.event_name == 'pull_request' && (github.event.label.name == 'run-eval-1' || github.event.label.name == 'run-eval-2' || github.event.label.name == 'run-eval-50' || github.event.label.name == 'run-eval-100')) || github.event_name == 'release' || github.event_name == 'workflow_dispatch' }}
     runs-on: blacksmith-4vcpu-ubuntu-2204
 
     steps:
-      - name: Checkout PR branch
+      - name: Checkout branch
         uses: actions/checkout@v4
         with:
-          ref: ${{ github.head_ref }}
+          ref: ${{ github.event_name == 'pull_request' && github.head_ref || (github.event_name == 'workflow_dispatch' && github.event.inputs.branch) || github.ref }}
 
-      - name: Trigger remote job
-        env:
-          PR_BRANCH: ${{ github.head_ref }}
+      - name: Set evaluation parameters
+        id: eval_params
         run: |
           REPO_URL="https://github.com/${{ github.repository }}"
           echo "Repository URL: $REPO_URL"
-          echo "PR Branch: $PR_BRANCH"
 
-          if [[ "${{ github.event.label.name }}" == "run-eval-1" ]]; then
-            EVAL_INSTANCES="1"
-          elif [[ "${{ github.event.label.name }}" == "run-eval-2" ]]; then
-            EVAL_INSTANCES="2"
-          elif [[ "${{ github.event.label.name }}" == "run-eval-50" ]]; then
+          # Determine branch based on trigger type
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            EVAL_BRANCH="${{ github.head_ref }}"
+            echo "PR Branch: $EVAL_BRANCH"
+          elif [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
+            EVAL_BRANCH="${{ github.event.inputs.branch }}"
+            echo "Manual Branch: $EVAL_BRANCH"
+          else
+            # For release events, use the tag name or main branch
+            EVAL_BRANCH="${{ github.ref_name }}"
+            echo "Release Branch/Tag: $EVAL_BRANCH"
+          fi
+
+          # Determine evaluation instances based on trigger type
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            if [[ "${{ github.event.label.name }}" == "run-eval-1" ]]; then
+              EVAL_INSTANCES="1"
+            elif [[ "${{ github.event.label.name }}" == "run-eval-2" ]]; then
+              EVAL_INSTANCES="2"
+            elif [[ "${{ github.event.label.name }}" == "run-eval-50" ]]; then
+              EVAL_INSTANCES="50"
+            elif [[ "${{ github.event.label.name }}" == "run-eval-100" ]]; then
+              EVAL_INSTANCES="100"
+            fi
+          elif [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
+            EVAL_INSTANCES="${{ github.event.inputs.eval_instances }}"
+          else
+            # For release events, default to 50 instances
             EVAL_INSTANCES="50"
-          elif [[ "${{ github.event.label.name }}" == "run-eval-100" ]]; then
-            EVAL_INSTANCES="100"
+          fi
+
+          echo "Evaluation instances: $EVAL_INSTANCES"
+          echo "repo_url=$REPO_URL" >> $GITHUB_OUTPUT
+          echo "eval_branch=$EVAL_BRANCH" >> $GITHUB_OUTPUT
+          echo "eval_instances=$EVAL_INSTANCES" >> $GITHUB_OUTPUT
+
+      - name: Trigger remote job
+        run: |
+          # Determine PR number for the remote evaluation system
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            PR_NUMBER="${{ github.event.pull_request.number }}"
+          else
+            # For non-PR triggers, use the master issue number as PR number
+            PR_NUMBER="${{ env.MASTER_EVAL_ISSUE_NUMBER }}"
           fi
 
           curl -X POST \
             -H "Authorization: Bearer ${{ secrets.PAT_TOKEN }}" \
             -H "Accept: application/vnd.github+json" \
-            -d "{\"ref\": \"main\", \"inputs\": {\"github-repo\": \"${REPO_URL}\", \"github-branch\": \"${PR_BRANCH}\", \"pr-number\": \"${{ github.event.pull_request.number }}\", \"eval-instances\": \"${EVAL_INSTANCES}\"}}" \
+            -d "{\"ref\": \"main\", \"inputs\": {\"github-repo\": \"${{ steps.eval_params.outputs.repo_url }}\", \"github-branch\": \"${{ steps.eval_params.outputs.eval_branch }}\", \"pr-number\": \"${PR_NUMBER}\", \"eval-instances\": \"${{ steps.eval_params.outputs.eval_instances }}\"}}" \
             https://api.github.com/repos/All-Hands-AI/evaluation/actions/workflows/create-branch.yml/dispatches
 
           # Send Slack message
-          PR_URL="https://github.com/${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
-          slack_text="PR $PR_URL has triggered evaluation on $EVAL_INSTANCES instances..."
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            TRIGGER_URL="https://github.com/${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
+            slack_text="PR $TRIGGER_URL has triggered evaluation on ${{ steps.eval_params.outputs.eval_instances }} instances..."
+          elif [[ "${{ github.event_name }}" == "release" ]]; then
+            TRIGGER_URL="https://github.com/${{ github.repository }}/releases/tag/${{ github.ref_name }}"
+            slack_text="Release $TRIGGER_URL has triggered evaluation on ${{ steps.eval_params.outputs.eval_instances }} instances..."
+          else
+            TRIGGER_URL="https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+            slack_text="Manual trigger (${{ github.event.inputs.reason || 'No reason provided' }}) has triggered evaluation on ${{ steps.eval_params.outputs.eval_instances }} instances for branch ${{ steps.eval_params.outputs.eval_branch }}..."
+          fi
+
           curl -X POST -H 'Content-type: application/json' --data '{"text":"'"$slack_text"'"}' \
             https://hooks.slack.com/services/${{ secrets.SLACK_TOKEN }}
 
-      - name: Comment on PR
+      - name: Comment on issue/PR
         uses: KeisukeYamashita/create-comment@v1
         with:
+          # For PR triggers, comment on the PR. For other triggers, comment on the master issue
+          number: ${{ github.event_name == 'pull_request' && github.event.pull_request.number || env.MASTER_EVAL_ISSUE_NUMBER }}
           unique: false
           comment: |
-            Running evaluation on the PR. Once eval is done, the results will be posted.
+            **Evaluation Triggered**
+
+            **Trigger:** ${{ github.event_name == 'pull_request' && format('Pull Request #{0}', github.event.pull_request.number) || (github.event_name == 'release' && 'Release') || format('Manual Trigger: {0}', github.event.inputs.reason || 'No reason provided') }}
+            **Branch:** ${{ steps.eval_params.outputs.eval_branch }}
+            **Instances:** ${{ steps.eval_params.outputs.eval_instances }}
+            **Commit:** ${{ github.sha }}
+
+            Running evaluation on the specified branch. Once eval is done, the results will be posted here.

.github/workflows/stale.yml

@@ -12,11 +12,11 @@ jobs:
     steps:
       - uses: actions/stale@v9
         with:
-          stale-issue-message: 'This issue is stale because it has been open for 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.'
-          stale-pr-message: 'This PR is stale because it has been open for 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.'
-          days-before-stale: 30
-          exempt-issue-labels: 'tracked'
-          close-issue-message: 'This issue was closed because it has been stalled for over 30 days with no activity.'
-          close-pr-message: 'This PR was closed because it has been stalled for over 30 days with no activity.'
-          days-before-close: 7
+          stale-issue-message: 'This issue is stale because it has been open for 40 days with no activity. Remove the stale label or leave a comment, otherwise it will be closed in 10 days.'
+          stale-pr-message: 'This PR is stale because it has been open for 40 days with no activity. Remove the stale label or leave a comment, otherwise it will be closed in 10 days.'
+          days-before-stale: 40
+          exempt-issue-labels: 'roadmap'
+          close-issue-message: 'This issue was automatically closed due to 50 days of inactivity. We do this to help keep the issues somewhat manageable and focus on active issues.'
+          close-pr-message: 'This PR was closed because it had no activity for 50 days. If you feel this was closed in error, and you would like to continue the PR, please resubmit or let us know.'
+          days-before-close: 10
           operations-per-run: 150

.github/workflows/ui-build.yml

@@ -0,0 +1,34 @@
+name: Run UI Component Build
+
+# * Always run on "main"
+# * Run on PRs that have changes in the "openhands-ui" folder or this workflow
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    paths:
+      - 'openhands-ui/**'
+      -  '.github/workflows/ui-build.yml'
+
+# If triggered by a PR, it will be in the same group. However, each commit on main will be in its own unique group
+concurrency:
+  group: ${{ github.workflow }}-${{ (github.head_ref && github.ref) || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  ui-build:
+    name: Build openhands-ui
+    runs-on: blacksmith-4vcpu-ubuntu-2204
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: "openhands-ui/.bun-version"
+      - name: Install dependencies
+        working-directory: ./openhands-ui
+        run: bun install --frozen-lockfile
+      - name: Build package
+        working-directory:  ./openhands-ui
+        run: bun run build

.github/workflows/vscode-extension-build.yml

@@ -0,0 +1,156 @@
+# Workflow that validates the VSCode extension builds correctly
+name: VSCode Extension CI
+
+# * Always run on "main"
+# * Run on PRs that have changes in the VSCode extension folder or this workflow
+# * Run on tags that start with "ext-v"
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'ext-v*'
+  pull_request:
+    paths:
+      - 'openhands/integrations/vscode/**'
+      - 'build_vscode.py'
+      - '.github/workflows/vscode-extension-build.yml'
+
+# If triggered by a PR, it will be in the same group. However, each commit on main will be in its own unique group
+concurrency:
+  group: ${{ github.workflow }}-${{ (github.head_ref && github.ref) || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  # Validate VSCode extension builds correctly
+  validate-vscode-extension:
+    name: Validate VSCode Extension Build
+    runs-on: blacksmith-4vcpu-ubuntu-2204
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: useblacksmith/setup-node@v5
+        with:
+          node-version: '22'
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install VSCode extension dependencies
+        working-directory: ./openhands/integrations/vscode
+        run: npm ci
+
+      - name: Build VSCode extension via build_vscode.py
+        run: python build_vscode.py
+        env:
+          # Ensure we don't skip the build
+          SKIP_VSCODE_BUILD: ""
+
+      - name: Validate .vsix file
+        run: |
+          # Verify the .vsix was created and is valid
+          if [ -f "openhands/integrations/vscode/openhands-vscode-0.0.1.vsix" ]; then
+            echo "✅ VSCode extension built successfully"
+            ls -la openhands/integrations/vscode/openhands-vscode-0.0.1.vsix
+
+            # Basic validation that the .vsix is a valid zip file
+            echo "🔍 Validating .vsix structure..."
+            file openhands/integrations/vscode/openhands-vscode-0.0.1.vsix
+            unzip -t openhands/integrations/vscode/openhands-vscode-0.0.1.vsix
+
+            echo "✅ VSCode extension validation passed"
+          else
+            echo "❌ VSCode extension build failed - .vsix not found"
+            exit 1
+          fi
+
+      - name: Upload VSCode extension artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: vscode-extension
+          path: openhands/integrations/vscode/openhands-vscode-0.0.1.vsix
+          retention-days: 7
+
+      - name: Comment on PR with artifact link
+        if: github.event_name == 'pull_request'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const path = require('path');
+
+            // Get file size for display
+            const vsixPath = 'openhands/integrations/vscode/openhands-vscode-0.0.1.vsix';
+            const stats = fs.statSync(vsixPath);
+            const fileSizeKB = Math.round(stats.size / 1024);
+
+            const comment = `## 🔧 VSCode Extension Built Successfully!
+
+            The VSCode extension has been built and is ready for testing.
+
+            **📦 Download**: [openhands-vscode-0.0.1.vsix](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}) (${fileSizeKB} KB)
+
+            **🚀 To install**:
+            1. Download the artifact from the workflow run above
+            2. In VSCode: \`Ctrl+Shift+P\` → "Extensions: Install from VSIX..."
+            3. Select the downloaded \`.vsix\` file
+
+            **✅ Tested with**: Node.js 22
+            **🔍 Validation**: File structure and integrity verified
+
+            ---
+            *Built from commit ${{ github.sha }}*`;
+
+            // Check if we already commented on this PR and delete it
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const botComment = comments.find(comment =>
+              comment.user.login === 'github-actions[bot]' &&
+              comment.body.includes('VSCode Extension Built Successfully')
+            );
+
+            if (botComment) {
+              await github.rest.issues.deleteComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+              });
+            }
+
+            // Create a new comment
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: comment
+            });
+
+  release:
+    name: Create GitHub Release
+    runs-on: blacksmith-4vcpu-ubuntu-2204
+    needs: validate-vscode-extension
+    if: startsWith(github.ref, 'refs/tags/ext-v')
+
+    steps:
+      - name: Download .vsix artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: vscode-extension
+          path: ./
+
+      - name: Create Release
+        uses: ncipollo/release-action@v1.16.0
+        with:
+          artifacts: "*.vsix"
+          token: ${{ secrets.GITHUB_TOKEN }}
+          draft: true
+          allowUpdates: true

.gitignore

@@ -182,6 +182,8 @@ cython_debug/
 .roo/rules
 .cline/rules
 .windsurf/rules
+.repomix
+repomix-output.txt
 
 # evaluation
 evaluation/evaluation_outputs

.openhands/microagents/repo.md

@@ -19,6 +19,7 @@ Before pushing any changes, you MUST ensure that any lint errors or simple test
 
 * If you've made changes to the backend, you should run `pre-commit run --config ./dev_config/python/.pre-commit-config.yaml` (this will run on staged files).
 * If you've made changes to the frontend, you should run `cd frontend && npm run lint:fix && npm run build ; cd ..`
+* If you've made changes to the VSCode extension, you should run `cd openhands/integrations/vscode && npm run lint:fix && npm run compile ; cd ../../..`
 
 The pre-commit hooks MUST pass successfully before pushing any changes to the repository. This is a mandatory requirement to maintain code quality and consistency.
 
@@ -29,6 +30,12 @@ then re-run the command to ensure it passes. Common issues include:
 - Trailing whitespace
 - Missing newlines at end of files
 
+## Git Best Practices
+
+- Prefer specific `git add <filename>` instead of `git add .` to avoid accidentally staging unintended files
+- Be especially careful with `git reset --hard` after staging files, as it will remove accidentally staged files
+- When remote has new changes, use `git fetch upstream && git rebase upstream/<branch>` on the same branch
+
 ## Repository Structure
 Backend:
 - Located in the `openhands` directory
@@ -60,6 +67,22 @@ Frontend:
   - Mutation hooks should follow the pattern use[Action] (e.g., `useDeleteConversation`)
   - Architecture rule: UI components → TanStack Query hooks → Data Access Layer (`frontend/src/api`) → API endpoints
 
+VSCode Extension:
+- Located in the `openhands/integrations/vscode` directory
+- Setup: Run `npm install` in the extension directory
+- Linting:
+  - Run linting with fixes: `npm run lint:fix`
+  - Check only: `npm run lint`
+  - Type checking: `npm run typecheck`
+- Building:
+  - Compile TypeScript: `npm run compile`
+  - Package extension: `npm run package-vsix`
+- Testing:
+  - Run tests: `npm run test`
+- Development Best Practices:
+  - Use `vscode.window.createOutputChannel()` for debug logging instead of `showErrorMessage()` popups
+  - Pre-commit process runs both frontend and backend checks when committing extension changes
+
 ## Template for Github Pull Request
 
 If you are starting a pull request (PR), please follow the template in `.github/pull_request_template.md`.
@@ -118,3 +141,65 @@ Your specialized knowledge and instructions here...
   2. Add the setting to the backend:
      - Add the setting to the `Settings` model in `openhands/storage/data_models/settings.py`
      - Update any relevant backend code to apply the setting (e.g., in session creation)
+
+### Adding New LLM Models
+
+To add a new LLM model to OpenHands, you need to update multiple files across both frontend and backend:
+
+#### Model Configuration Procedure:
+
+1. **Frontend Model Arrays** (`frontend/src/utils/verified-models.ts`):
+   - Add the model to `VERIFIED_MODELS` array (main list of all verified models)
+   - Add to provider-specific arrays based on the model's provider:
+     - `VERIFIED_OPENAI_MODELS` for OpenAI models
+     - `VERIFIED_ANTHROPIC_MODELS` for Anthropic models
+     - `VERIFIED_MISTRAL_MODELS` for Mistral models
+     - `VERIFIED_OPENHANDS_MODELS` for models available through OpenHands provider
+
+2. **Backend CLI Integration** (`openhands/cli/utils.py`):
+   - Add the model to the appropriate `VERIFIED_*_MODELS` arrays
+   - This ensures the model appears in CLI model selection
+
+3. **Backend Model List** (`openhands/utils/llm.py`):
+   - **CRITICAL**: Add the model to the `openhands_models` list (lines 57-66) if using OpenHands provider
+   - This is required for the model to appear in the frontend model selector
+   - Format: `'openhands/model-name'` (e.g., `'openhands/o3'`)
+
+4. **Backend LLM Configuration** (`openhands/llm/llm.py`):
+   - Add to feature-specific arrays based on model capabilities:
+     - `FUNCTION_CALLING_SUPPORTED_MODELS` if the model supports function calling
+     - `REASONING_EFFORT_SUPPORTED_MODELS` if the model supports reasoning effort parameters
+     - `CACHE_PROMPT_SUPPORTED_MODELS` if the model supports prompt caching
+     - `MODELS_WITHOUT_STOP_WORDS` if the model doesn't support stop words
+
+5. **Validation**:
+   - Run backend linting: `pre-commit run --config ./dev_config/python/.pre-commit-config.yaml`
+   - Run frontend linting: `cd frontend && npm run lint:fix`
+   - Run frontend build: `cd frontend && npm run build`
+
+#### Model Verification Arrays:
+
+- **VERIFIED_MODELS**: Main array of all verified models shown in the UI
+- **VERIFIED_OPENAI_MODELS**: OpenAI models (LiteLLM doesn't return provider prefix)
+- **VERIFIED_ANTHROPIC_MODELS**: Anthropic models (LiteLLM doesn't return provider prefix)
+- **VERIFIED_MISTRAL_MODELS**: Mistral models (LiteLLM doesn't return provider prefix)
+- **VERIFIED_OPENHANDS_MODELS**: Models available through OpenHands managed provider
+
+#### Model Feature Support Arrays:
+
+- **FUNCTION_CALLING_SUPPORTED_MODELS**: Models that support structured function calling
+- **REASONING_EFFORT_SUPPORTED_MODELS**: Models that support reasoning effort parameters (like o1, o3)
+- **CACHE_PROMPT_SUPPORTED_MODELS**: Models that support prompt caching for efficiency
+- **MODELS_WITHOUT_STOP_WORDS**: Models that don't support stop word parameters
+
+#### Frontend Model Integration:
+
+- Models are automatically available in the model selector UI once added to verified arrays
+- The `extractModelAndProvider` utility automatically detects provider from model arrays
+- Provider-specific models are grouped and prioritized in the UI selection
+
+#### CLI Model Integration:
+
+- Models appear in CLI provider selection based on the verified arrays
+- The `organize_models_and_providers` function groups models by provider
+- Default model selection prioritizes verified models for each provider

.openhands/pre-commit.sh

@@ -1,56 +1,158 @@
 #!/bin/bash
 
 echo "Running OpenHands pre-commit hook..."
+echo "This hook runs selective linting based on changed files."
 
 # Store the exit code to return at the end
 # This allows us to be additive to existing pre-commit hooks
 EXIT_CODE=0
 
-# Check if frontend directory has changed
-frontend_changes=$(git diff --cached --name-only | grep "^frontend/")
-if [ -n "$frontend_changes" ]; then
-    echo "Frontend changes detected. Running frontend checks..."
+# Get the list of staged files
+STAGED_FILES=$(git diff --cached --name-only)
 
-    # Check if frontend directory exists
-    if [ -d "frontend" ]; then
-        # Change to frontend directory
-        cd frontend || exit 1
+# Check if any files match specific patterns
+has_frontend_changes=false
+has_backend_changes=false
+has_vscode_changes=false
 
-        # Run lint:fix
-        echo "Running npm lint:fix..."
-        npm run lint:fix
+# Check each file individually to avoid issues with grep
+for file in $STAGED_FILES; do
+    if [[ $file == frontend/* ]]; then
+        has_frontend_changes=true
+    elif [[ $file == openhands/* || $file == evaluation/* || $file == tests/* ]]; then
+        has_backend_changes=true
+        # Check for VSCode extension changes (subset of backend changes)
+        if [[ $file == openhands/integrations/vscode/* ]]; then
+            has_vscode_changes=true
+        fi
+    fi
+done
+
+echo "Analyzing changes..."
+echo "- Frontend changes: $has_frontend_changes"
+echo "- Backend changes: $has_backend_changes"
+echo "- VSCode extension changes: $has_vscode_changes"
+
+# Run frontend linting if needed
+if [ "$has_frontend_changes" = true ]; then
+    # Check if we're in a CI environment or if frontend dependencies are missing
+    if [ -n "$CI" ] || ! command -v react-router &> /dev/null || ! command -v vitest &> /dev/null; then
+        echo "Skipping frontend checks (CI environment or missing dependencies detected)."
+        echo "WARNING: Frontend files have changed but frontend checks are being skipped."
+        echo "Please run 'make lint-frontend' manually before submitting your PR."
+    else
+        echo "Running frontend linting..."
+        make lint-frontend
         if [ $? -ne 0 ]; then
             echo "Frontend linting failed. Please fix the issues before committing."
             EXIT_CODE=1
+        else
+            echo "Frontend linting checks passed!"
         fi
 
-        # Run build
-        echo "Running npm build..."
-        npm run build
-        if [ $? -ne 0 ]; then
-            echo "Frontend build failed. Please fix the issues before committing."
-            EXIT_CODE=1
-        fi
+        # Run additional frontend checks
+        if [ -d "frontend" ]; then
+            echo "Running additional frontend checks..."
+            cd frontend || exit 1
 
-        # Run tests
-        echo "Running npm test..."
-        npm test
-        if [ $? -ne 0 ]; then
-            echo "Frontend tests failed. Please fix the failing tests before committing."
-            EXIT_CODE=1
-        fi
+            # Run build
+            echo "Running npm build..."
+            npm run build
+            if [ $? -ne 0 ]; then
+                echo "Frontend build failed. Please fix the issues before committing."
+                EXIT_CODE=1
+            fi
 
-        # Return to the original directory
-        cd ..
+            # Run tests
+            echo "Running npm test..."
+            npm test
+            if [ $? -ne 0 ]; then
+                echo "Frontend tests failed. Please fix the failing tests before committing."
+                EXIT_CODE=1
+            fi
 
-        if [ $EXIT_CODE -eq 0 ]; then
-            echo "Frontend checks passed!"
+            cd ..
         fi
-    else
-        echo "Frontend directory not found. Skipping frontend checks."
     fi
 else
-    echo "No frontend changes detected. Skipping frontend checks."
+    echo "Skipping frontend checks (no frontend changes detected)."
+fi
+
+# Run backend linting if needed
+if [ "$has_backend_changes" = true ]; then
+    echo "Running backend linting..."
+    make lint-backend
+    if [ $? -ne 0 ]; then
+        echo "Backend linting failed. Please fix the issues before committing."
+        EXIT_CODE=1
+    else
+        echo "Backend linting checks passed!"
+    fi
+else
+    echo "Skipping backend checks (no backend changes detected)."
+fi
+
+# Run VSCode extension checks if needed
+if [ "$has_vscode_changes" = true ]; then
+    # Check if we're in a CI environment
+    if [ -n "$CI" ]; then
+        echo "Skipping VSCode extension checks (CI environment detected)."
+        echo "WARNING: VSCode extension files have changed but checks are being skipped."
+        echo "Please run VSCode extension checks manually before submitting your PR."
+    else
+        echo "Running VSCode extension checks..."
+        if [ -d "openhands/integrations/vscode" ]; then
+            cd openhands/integrations/vscode || exit 1
+
+            echo "Running npm lint:fix..."
+            npm run lint:fix
+            if [ $? -ne 0 ]; then
+                echo "VSCode extension linting failed. Please fix the issues before committing."
+                EXIT_CODE=1
+            else
+                echo "VSCode extension linting passed!"
+            fi
+
+            echo "Running npm typecheck..."
+            npm run typecheck
+            if [ $? -ne 0 ]; then
+                echo "VSCode extension type checking failed. Please fix the issues before committing."
+                EXIT_CODE=1
+            else
+                echo "VSCode extension type checking passed!"
+            fi
+
+            echo "Running npm compile..."
+            npm run compile
+            if [ $? -ne 0 ]; then
+                echo "VSCode extension compilation failed. Please fix the issues before committing."
+                EXIT_CODE=1
+            else
+                echo "VSCode extension compilation passed!"
+            fi
+
+            cd ../../..
+        fi
+    fi
+else
+    echo "Skipping VSCode extension checks (no VSCode extension changes detected)."
+fi
+
+# If no specific code changes detected, run basic checks
+if [ "$has_frontend_changes" = false ] && [ "$has_backend_changes" = false ]; then
+    echo "No specific code changes detected. Running basic checks..."
+    if [ -n "$STAGED_FILES" ]; then
+        # Run only basic pre-commit hooks for non-code files
+        poetry run pre-commit run --files $(echo "$STAGED_FILES" | tr '\n' ' ') --hook-stage commit --config ./dev_config/python/.pre-commit-config.yaml
+        if [ $? -ne 0 ]; then
+            echo "Basic checks failed. Please fix the issues before committing."
+            EXIT_CODE=1
+        else
+            echo "Basic checks passed!"
+        fi
+    else
+        echo "No files changed. Skipping basic checks."
+    fi
 fi
 
 # Run any existing pre-commit hooks that might have been installed by the user

CONTRIBUTING.md

@@ -31,7 +31,7 @@ We're always looking to improve the look and feel of the application. If you've
 for something that's bugging you, feel free to open up a PR that changes the [`./frontend`](./frontend) directory.
 
 If you're looking to make a bigger change, add a new UI element, or significantly alter the style
-of the application, please open an issue first, or better, join the #frontend channel in our Slack
+of the application, please open an issue first, or better, join the #eng-ui-ux channel in our Slack
 to gather consensus from our design team first.
 
 #### Improving the agent

Development.md

@@ -34,7 +34,7 @@ _Dev Container: Reopen in Container_ command from the Command Palette
 
 #### Develop without sudo access
 
-If you want to develop without system admin/sudo access to upgrade/install `Python` and/or `NodeJs`, you can use
+If you want to develop without system admin/sudo access to upgrade/install `Python` and/or `NodeJS`, you can use
 `conda` or `mamba` to manage the packages for you:
 
 ```bash
@@ -71,7 +71,7 @@ This command will prompt you to enter the LLM API key, model name, and other var
 tailored to your specific needs. Note that the model name will apply only when you run headless. If you use the UI,
 please set the model in the UI.
 
-Note: If you have previously run OpenHands using the docker command, you may have already set some environmental
+Note: If you have previously run OpenHands using the docker command, you may have already set some environment
 variables in your terminal. The final configurations are set from highest to lowest priority:
 Environment variables > config.toml variables > default variables
 
@@ -154,12 +154,12 @@ poetry run pytest ./tests/unit/test_*.py
 1. Add your dependency in `pyproject.toml` or use `poetry add xxx`.
 2. Update the poetry.lock file via `poetry lock --no-update`.
 
-### 9. Use existing Docker image
+### 10. Use existing Docker image
 
 To reduce build time (e.g., if no changes were made to the client-runtime component), you can use an existing Docker
 container image by setting the SANDBOX_RUNTIME_CONTAINER_IMAGE environment variable to the desired Docker image.
 
-Example: `export SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.47-nikolaik`
+Example: `export SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.52-nikolaik`
 
 ## Develop inside Docker container
 

Makefile

@@ -3,10 +3,10 @@ SHELL=/usr/bin/env bash
 
 # Variables
 BACKEND_HOST ?= "127.0.0.1"
-BACKEND_PORT = 3000
+BACKEND_PORT ?= 3000
 BACKEND_HOST_PORT = "$(BACKEND_HOST):$(BACKEND_PORT)"
 FRONTEND_HOST ?= "127.0.0.1"
-FRONTEND_PORT = 3001
+FRONTEND_PORT ?= 3001
 DEFAULT_WORKSPACE_DIR = "./workspace"
 DEFAULT_MODEL = "gpt-4o"
 CONFIG_FILE = config.toml
@@ -174,7 +174,7 @@ install-python-dependencies:
 	fi
 	@echo "$(GREEN)Python dependencies installed successfully.$(RESET)"
 
-install-frontend-dependencies:
+install-frontend-dependencies: check-npm check-nodejs
 	@echo "$(YELLOW)Setting up frontend environment...$(RESET)"
 	@echo "$(YELLOW)Detect Node.js version...$(RESET)"
 	@cd frontend && node ./scripts/detect-node-version.js
@@ -182,17 +182,17 @@ install-frontend-dependencies:
 	@cd frontend && npm install
 	@echo "$(GREEN)Frontend dependencies installed successfully.$(RESET)"
 
-install-pre-commit-hooks:
+install-pre-commit-hooks: check-python check-poetry install-python-dependencies
 	@echo "$(YELLOW)Installing pre-commit hooks...$(RESET)"
 	@git config --unset-all core.hooksPath || true
 	@poetry run pre-commit install --config $(PRE_COMMIT_CONFIG_PATH)
 	@echo "$(GREEN)Pre-commit hooks installed successfully.$(RESET)"
 
-lint-backend:
+lint-backend: install-pre-commit-hooks
 	@echo "$(YELLOW)Running linters...$(RESET)"
 	@poetry run pre-commit run --all-files --show-diff-on-failure --config $(PRE_COMMIT_CONFIG_PATH)
 
-lint-frontend:
+lint-frontend: install-frontend-dependencies
 	@echo "$(YELLOW)Running linters for frontend...$(RESET)"
 	@cd frontend && npm run lint
 

README.md

@@ -52,37 +52,63 @@ which comes with $20 in free credits for new users.
 
 ## 💻 Running OpenHands Locally
 
-OpenHands can also run on your local system using Docker.
-See the [Running OpenHands](https://docs.all-hands.dev/usage/installation) guide for
-system requirements and more information.
+### Option 1: CLI Launcher (Recommended)
 
-> [!WARNING]
-> On a public network? See our [Hardened Docker Installation Guide](https://docs.all-hands.dev/usage/runtimes/docker#hardened-docker-installation)
-> to secure your deployment by restricting network binding and implementing additional security measures.
+The easiest way to run OpenHands locally is using the CLI launcher with [uv](https://docs.astral.sh/uv/). This provides better isolation from your current project's virtual environment and is required for OpenHands' default MCP servers.
 
+**Install uv** (if you haven't already):
+
+See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for the latest installation instructions for your platform.
+
+**Launch OpenHands**:
+```bash
+# Launch the GUI server
+uvx --python 3.12 --from openhands-ai openhands serve
+
+# Or launch the CLI
+uvx --python 3.12 --from openhands-ai openhands
+```
+
+You'll find OpenHands running at [http://localhost:3000](http://localhost:3000) (for GUI mode)!
+
+### Option 2: Docker
+
+<details>
+<summary>Click to expand Docker command</summary>
+
+You can also run OpenHands directly with Docker:
 
 ```bash
-docker pull docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik
+docker pull docker.all-hands.dev/all-hands-ai/runtime:0.52-nikolaik
 
 docker run -it --rm --pull=always \
-    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.52-nikolaik \
     -e LOG_ALL_EVENTS=true \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v ~/.openhands:/.openhands \
     -p 3000:3000 \
     --add-host host.docker.internal:host-gateway \
     --name openhands-app \
-    docker.all-hands.dev/all-hands-ai/openhands:0.47
+    docker.all-hands.dev/all-hands-ai/openhands:0.52
 ```
 
+</details>
+
 > **Note**: If you used OpenHands before version 0.44, you may want to run `mv ~/.openhands-state ~/.openhands` to migrate your conversation history to the new location.
 
-You'll find OpenHands running at [http://localhost:3000](http://localhost:3000)!
+> [!WARNING]
+> On a public network? See our [Hardened Docker Installation Guide](https://docs.all-hands.dev/usage/runtimes/docker#hardened-docker-installation)
+> to secure your deployment by restricting network binding and implementing additional security measures.
+
+### Getting Started
 
 When you open the application, you'll be asked to choose an LLM provider and add an API key.
 [Anthropic's Claude Sonnet 4](https://www.anthropic.com/api) (`anthropic/claude-sonnet-4-20250514`)
 works best, but you have [many options](https://docs.all-hands.dev/usage/llms).
 
+See the [Running OpenHands](https://docs.all-hands.dev/usage/installation) guide for
+system requirements and more information.
+
 ## 💡 Other ways to run OpenHands
 
 > [!WARNING]
@@ -93,8 +119,8 @@ works best, but you have [many options](https://docs.all-hands.dev/usage/llms).
 > [OpenHands Cloud Helm Chart](https://github.com/all-Hands-AI/OpenHands-cloud)
 
 You can [connect OpenHands to your local filesystem](https://docs.all-hands.dev/usage/runtimes/docker#connecting-to-your-filesystem),
-run OpenHands in a scriptable [headless mode](https://docs.all-hands.dev/usage/how-to/headless-mode),
 interact with it via a [friendly CLI](https://docs.all-hands.dev/usage/how-to/cli-mode),
+run OpenHands in a scriptable [headless mode](https://docs.all-hands.dev/usage/how-to/headless-mode),
 or run it on tagged issues with [a github action](https://docs.all-hands.dev/usage/how-to/github-action).
 
 Visit [Running OpenHands](https://docs.all-hands.dev/usage/installation) for more information and setup instructions.

README_CN.md

@@ -51,17 +51,17 @@ OpenHands也可以使用Docker在本地系统上运行。
 
 
 ```bash
-docker pull docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik
+docker pull docker.all-hands.dev/all-hands-ai/runtime:0.52-nikolaik
 
 docker run -it --rm --pull=always \
-    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.52-nikolaik \
     -e LOG_ALL_EVENTS=true \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v ~/.openhands:/.openhands \
     -p 3000:3000 \
     --add-host host.docker.internal:host-gateway \
     --name openhands-app \
-    docker.all-hands.dev/all-hands-ai/openhands:0.47
+    docker.all-hands.dev/all-hands-ai/openhands:0.52
 ```
 
 > **注意**: 如果您在0.44版本之前使用过OpenHands，您可能需要运行 `mv ~/.openhands-state ~/.openhands` 来将对话历史迁移到新位置。

README_JA.md

@@ -42,17 +42,17 @@ OpenHandsはDockerを利用してローカル環境でも実行できます。
 > 公共ネットワークで実行していますか？[Hardened Docker Installation Guide](https://docs.all-hands.dev/usage/runtimes/docker#hardened-docker-installation)を参照して、ネットワークバインディングの制限や追加のセキュリティ対策を実施してください。
 
 ```bash
-docker pull docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik
+docker pull docker.all-hands.dev/all-hands-ai/runtime:0.52-nikolaik
 
 docker run -it --rm --pull=always \
-    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.52-nikolaik \
     -e LOG_ALL_EVENTS=true \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v ~/.openhands:/.openhands \
     -p 3000:3000 \
     --add-host host.docker.internal:host-gateway \
     --name openhands-app \
-    docker.all-hands.dev/all-hands-ai/openhands:0.47
+    docker.all-hands.dev/all-hands-ai/openhands:0.52
 ```
 
 **注**: バージョン0.44以前のOpenHandsを使用していた場合は、会話履歴を移行するために `mv ~/.openhands-state ~/.openhands` を実行してください。

build_vscode.py

@@ -0,0 +1,113 @@
+import os
+import pathlib
+import subprocess
+
+# This script is intended to be run by Poetry during the build process.
+
+# Define the expected name of the .vsix file based on the extension's package.json
+# This should match the name and version in openhands-vscode/package.json
+EXTENSION_NAME = 'openhands-vscode'
+EXTENSION_VERSION = '0.0.1'
+VSIX_FILENAME = f'{EXTENSION_NAME}-{EXTENSION_VERSION}.vsix'
+
+# Paths
+ROOT_DIR = pathlib.Path(__file__).parent.resolve()
+VSCODE_EXTENSION_DIR = ROOT_DIR / 'openhands' / 'integrations' / 'vscode'
+
+
+def check_node_version():
+    """Check if Node.js version is sufficient for building the extension."""
+    try:
+        result = subprocess.run(
+            ['node', '--version'], capture_output=True, text=True, check=True
+        )
+        version_str = result.stdout.strip()
+        # Extract major version number (e.g., "v12.22.9" -> 12)
+        major_version = int(version_str.lstrip('v').split('.')[0])
+        return major_version >= 18  # Align with frontend actual usage (18.20.1)
+    except (subprocess.CalledProcessError, FileNotFoundError, ValueError):
+        return False
+
+
+def build_vscode_extension():
+    """Builds the VS Code extension."""
+    vsix_path = VSCODE_EXTENSION_DIR / VSIX_FILENAME
+
+    # Check if VSCode extension build is disabled via environment variable
+    if os.environ.get('SKIP_VSCODE_BUILD', '').lower() in ('1', 'true', 'yes'):
+        print('--- Skipping VS Code extension build (SKIP_VSCODE_BUILD is set) ---')
+        if vsix_path.exists():
+            print(f'--- Using existing VS Code extension: {vsix_path} ---')
+        else:
+            print('--- No pre-built VS Code extension found ---')
+        return
+
+    # Check Node.js version - if insufficient, use pre-built extension as fallback
+    if not check_node_version():
+        print('--- Warning: Node.js version < 18 detected or Node.js not found ---')
+        print('--- Skipping VS Code extension build (requires Node.js >= 18) ---')
+        print('--- Using pre-built extension if available ---')
+
+        if not vsix_path.exists():
+            print('--- Warning: No pre-built VS Code extension found ---')
+            print('--- VS Code extension will not be available ---')
+        else:
+            print(f'--- Using pre-built VS Code extension: {vsix_path} ---')
+        return
+
+    print(f'--- Building VS Code extension in {VSCODE_EXTENSION_DIR} ---')
+
+    try:
+        # Ensure npm dependencies are installed
+        print('--- Running npm install for VS Code extension ---')
+        subprocess.run(
+            ['npm', 'install'],
+            cwd=VSCODE_EXTENSION_DIR,
+            check=True,
+            shell=os.name == 'nt',
+        )
+
+        # Package the extension
+        print(f'--- Packaging VS Code extension ({VSIX_FILENAME}) ---')
+        subprocess.run(
+            ['npm', 'run', 'package-vsix'],
+            cwd=VSCODE_EXTENSION_DIR,
+            check=True,
+            shell=os.name == 'nt',
+        )
+
+        # Verify the generated .vsix file exists
+        if not vsix_path.exists():
+            raise FileNotFoundError(
+                f'VS Code extension package not found after build: {vsix_path}'
+            )
+
+        print(f'--- VS Code extension built successfully: {vsix_path} ---')
+
+    except subprocess.CalledProcessError as e:
+        print(f'--- Warning: Failed to build VS Code extension: {e} ---')
+        print('--- Continuing without building extension ---')
+        if not vsix_path.exists():
+            print('--- Warning: No pre-built VS Code extension found ---')
+            print('--- VS Code extension will not be available ---')
+
+
+def build(setup_kwargs):
+    """This function is called by Poetry during the build process.
+    `setup_kwargs` is a dictionary that will be passed to `setuptools.setup()`.
+    """
+    print('--- Running custom Poetry build script (build_vscode.py) ---')
+
+    # Build the VS Code extension and place the .vsix file
+    build_vscode_extension()
+
+    # Poetry will handle including files based on pyproject.toml `include` patterns.
+    # Ensure openhands/integrations/vscode/*.vsix is included there.
+
+    print('--- Custom Poetry build script (build_vscode.py) finished ---')
+
+
+if __name__ == '__main__':
+    print('Running build_vscode.py directly for testing VS Code extension packaging...')
+    build_vscode_extension()
+    print('Direct execution of build_vscode.py finished.')

config.template.toml

@@ -18,9 +18,6 @@
 # Cache directory path
 #cache_dir = "/tmp/cache"
 
-# Reasoning effort for o1 models (low, medium, high, or not set)
-#reasoning_effort = "medium"
-
 # Debugging enabled
 #debug = false
 
@@ -49,6 +46,9 @@
 # Maximum file size for uploads, in megabytes
 #file_uploads_max_file_size_mb = 0
 
+# Enable the browser environment
+#enable_browser = true
+
 # Maximum budget per task, 0.0 means no limit
 #max_budget_per_task = 0.0
 
@@ -116,6 +116,9 @@ api_key = ""
 # API version
 #api_version = ""
 
+# Reasoning effort for OpenAI o-series models (low, medium, high, or not set)
+#reasoning_effort = "medium"
+
 # Cost per input token
 #input_cost_per_token = 0.0
 
@@ -226,6 +229,7 @@ model = "gpt-4o"
 [agent]
 
 # Whether the browsing tool is enabled
+# Note: when this is set to true, enable_browser in the core config must also be true
 enable_browsing = true
 
 # Whether the LLM draft editor is enabled

containers/app/Dockerfile

@@ -1,5 +1,5 @@
 ARG OPENHANDS_BUILD_VERSION=dev
-FROM node:22.16.0-bookworm-slim AS frontend-builder
+FROM node:24.3.0-bookworm-slim AS frontend-builder
 
 WORKDIR /app
 
@@ -45,6 +45,7 @@ ENV OPENHANDS_BUILD_VERSION=$OPENHANDS_BUILD_VERSION
 ENV SANDBOX_USER_ID=0
 ENV FILE_STORE=local
 ENV FILE_STORE_PATH=/.openhands
+ENV INIT_GIT_IN_EMPTY_WORKSPACE=1
 RUN mkdir -p $FILE_STORE_PATH
 RUN mkdir -p $WORKSPACE_BASE
 
@@ -57,8 +58,8 @@ RUN sed -i 's/^UID_MIN.*/UID_MIN 499/' /etc/login.defs
 # Default is 60000, but we've seen up to 200000
 RUN sed -i 's/^UID_MAX.*/UID_MAX 1000000/' /etc/login.defs
 
-RUN groupadd app
-RUN useradd -l -m -u $OPENHANDS_USER_ID -s /bin/bash openhands && \
+RUN groupadd --gid $OPENHANDS_USER_ID app
+RUN useradd -l -m -u $OPENHANDS_USER_ID --gid $OPENHANDS_USER_ID -s /bin/bash openhands && \
     usermod -aG app openhands && \
     usermod -aG sudo openhands && \
     echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers

containers/app/entrypoint.sh

@@ -23,6 +23,18 @@ if [ -z "$WORKSPACE_MOUNT_PATH" ]; then
   unset WORKSPACE_BASE
 fi
 
+if [[ "$INSTALL_THIRD_PARTY_RUNTIMES" == "true" ]]; then
+  echo "Downloading and installing third_party_runtimes..."
+  echo "Warning: Third-party runtimes are provided as-is, not actively supported and may be removed in future releases."
+
+  if pip install 'openhands-ai[third_party_runtimes]' -qqq 2> >(tee /dev/stderr); then
+    echo "third_party_runtimes installed successfully."
+  else
+    echo "Failed to install third_party_runtimes." >&2
+    exit 1
+  fi
+fi
+
 if [[ "$SANDBOX_USER_ID" -eq 0 ]]; then
   echo "Running OpenHands as root"
   export RUN_AS_OPENHANDS=false

containers/dev/compose.yml

@@ -12,7 +12,7 @@ services:
       - SANDBOX_API_HOSTNAME=host.docker.internal
       - DOCKER_HOST_ADDR=host.docker.internal
       #
-      - SANDBOX_RUNTIME_CONTAINER_IMAGE=${SANDBOX_RUNTIME_CONTAINER_IMAGE:-ghcr.io/all-hands-ai/runtime:0.47-nikolaik}
+      - SANDBOX_RUNTIME_CONTAINER_IMAGE=${SANDBOX_RUNTIME_CONTAINER_IMAGE:-ghcr.io/all-hands-ai/runtime:0.52-nikolaik}
       - SANDBOX_USER_ID=${SANDBOX_USER_ID:-1234}
       - WORKSPACE_MOUNT_PATH=${WORKSPACE_BASE:-$PWD/workspace}
     ports:

dev_config/python/.pre-commit-config.yaml

@@ -40,7 +40,7 @@ repos:
     hooks:
       - id: mypy
         additional_dependencies:
-          [types-requests, types-setuptools, types-pyyaml, types-toml, types-docker, pydantic, lxml]
+          [types-requests, types-setuptools, types-pyyaml, types-toml, types-docker, types-Markdown, pydantic, lxml]
         # To see gaps add `--html-report mypy-report/`
         entry: mypy --config-file dev_config/python/mypy.ini openhands/
         always_run: true

docker-compose.yml

@@ -7,7 +7,7 @@ services:
     image: openhands:latest
     container_name: openhands-app-${DATE:-}
     environment:
-      - SANDBOX_RUNTIME_CONTAINER_IMAGE=${SANDBOX_RUNTIME_CONTAINER_IMAGE:-docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik}
+      - SANDBOX_RUNTIME_CONTAINER_IMAGE=${SANDBOX_RUNTIME_CONTAINER_IMAGE:-docker.all-hands.dev/all-hands-ai/runtime:0.52-nikolaik}
       #- SANDBOX_USER_ID=${SANDBOX_USER_ID:-1234} # enable this only if you want a specific non-root sandbox user but you will have to manually adjust permissions of ~/.openhands for this user
       - WORKSPACE_MOUNT_PATH=${WORKSPACE_BASE:-$PWD/workspace}
     ports:

docs/docs.json

@@ -34,9 +34,19 @@
               {
                 "group": "Integrations",
                 "pages": [
+                  "usage/cloud/bitbucket-installation",
                   "usage/cloud/github-installation",
                   "usage/cloud/gitlab-installation",
-                  "usage/cloud/slack-installation"
+                  "usage/cloud/slack-installation",
+                  {
+                    "group": "Project Management Tools",
+                    "pages": [
+                      "usage/cloud/project-management/overview",
+                      "usage/cloud/project-management/jira-integration",
+                      "usage/cloud/project-management/jira-dc-integration",
+                      "usage/cloud/project-management/linear-integration"
+                    ]
+                  }
                 ]
               },
               "usage/cloud/cloud-ui",
@@ -61,11 +71,13 @@
                     {
                       "group": "Providers",
                       "pages": [
+                        "usage/llms/openhands-llms",
                         "usage/llms/azure-llms",
                         "usage/llms/google-llms",
                         "usage/llms/groq",
                         "usage/llms/local-llms",
                         "usage/llms/litellm-proxy",
+                        "usage/llms/moonshot",
                         "usage/llms/openai-llms",
                         "usage/llms/openrouter"
                       ]

docs/openapi.json

@@ -1827,6 +1827,11 @@
           "updated_at": {
             "type": "string",
             "format": "date-time"
+          },
+          "owner_type": {
+            "type": "string",
+            "enum": ["user", "organization"],
+            "nullable": true
           }
         }
       },

docs/usage/cloud/bitbucket-installation.mdx

@@ -0,0 +1,48 @@
+---
+title: Bitbucket Integration
+description: This guide walks you through the process of installing OpenHands Cloud for your Bitbucket repositories. Once
+  set up, it will allow OpenHands to work with your Bitbucket repository.
+---
+
+## Prerequisites
+
+- Signed in to [OpenHands Cloud](https://app.all-hands.dev) with [a Bitbucket account](/usage/cloud/openhands-cloud).
+
+## IP Whitelisting
+
+If your Bitbucket Cloud instance has IP restrictions, you'll need to whitelist the following IP addresses to allow OpenHands to access your repositories:
+
+### Core App IP
+```
+34.68.58.200
+```
+
+### Runtime IPs
+```
+34.10.175.217
+34.136.162.246
+34.45.0.142
+34.28.69.126
+35.224.240.213
+34.70.174.52
+34.42.4.87
+35.222.133.153
+34.29.175.97
+34.60.55.59
+```
+
+## Adding Bitbucket Repository Access
+
+Upon signing into OpenHands Cloud with a Bitbucket account, OpenHands will have access to your repositories.
+
+## Working With Bitbucket Repos in Openhands Cloud
+
+After signing in with a Bitbucket account, use the `select a repo` and `select a branch` dropdowns to select the
+appropriate repository and branch you'd like OpenHands to work on. Then click on `Launch` to start the conversation!
+
+![Connect Repo](/static/img/connect-repo-no-github.png)
+
+## Next Steps
+
+- [Learn about the Cloud UI](/usage/cloud/cloud-ui).
+- [Use the Cloud API](/usage/cloud/cloud-api) to programmatically interact with OpenHands.

docs/usage/cloud/cloud-ui.mdx

@@ -9,8 +9,9 @@ description: The Cloud UI provides a web interface for interacting with OpenHand
 The landing page is where you can:
 
 - [Add GitHub repository access](/usage/cloud/github-installation#adding-github-repository-access) to OpenHands.
-- [Select a GitHub repo](/usage/cloud/github-installation#working-with-github-repos-in-openhands-cloud) or
-  [a GitLab repo](/usage/cloud/gitlab-installation#working-with-gitlab-repos-in-openhands-cloud) to start working on.
+- [Select a GitHub repo](/usage/cloud/github-installation#working-with-github-repos-in-openhands-cloud),
+  [a GitLab repo](/usage/cloud/gitlab-installation#working-with-gitlab-repos-in-openhands-cloud) or
+  [a Bitbucket repo](/usage/cloud/bitbucket-installation#working-with-bitbucket-repos-in-openhands-cloud) to start working on.
 - See `Suggested Tasks` for repositories that OpenHands has access to.
 - Launch an empty conversation using `Launch from Scratch`.
 

docs/usage/cloud/github-installation.mdx

@@ -51,8 +51,7 @@ Giving GitHub repository access to OpenHands also allows you to work on GitHub i
 
 ### Working with Issues
 
-On your repository, label an issue with `openhands` or add a message starting with
-`@openhands`. OpenHands will:
+On your repository, label an issue with `openhands` or add a message starting with `@openhands`. OpenHands will:
 1. Comment on the issue to let you know it is working on it.
    - You can click on the link to track the progress on OpenHands Cloud.
 2. Open a pull request if it determines that the issue has been successfully resolved.
@@ -65,6 +64,8 @@ To get OpenHands to work on pull requests, mention `@openhands` in the comments
 - Request updates
 - Get code explanations
 
+**Important Note**: The `@openhands` mention functionality in pull requests only works if the pull request is both *to* and *from* a repository that you have added through the interface. This is because OpenHands needs appropriate permissions to access both repositories.
+
 ## Next Steps
 
 - [Learn about the Cloud UI](/usage/cloud/cloud-ui).

docs/usage/cloud/gitlab-installation.mdx

@@ -1,7 +1,7 @@
 ---
 title: GitLab Integration
 description: This guide walks you through the process of installing OpenHands Cloud for your GitLab repositories. Once
-  set up, it will allow OpenHands to work with your GitLab repository.
+  set up, it will allow OpenHands to work with your GitLab repository through the Cloud UI or straight from GitLab!.
 ---
 
 ## Prerequisites
@@ -17,7 +17,7 @@ Upon signing into OpenHands Cloud with a GitLab account, OpenHands will have acc
 After signing in with a Gitlab account, use the `select a repo` and `select a branch` dropdowns to select the
 appropriate repository and branch you'd like OpenHands to work on. Then click on `Launch` to start the conversation!
 
-![Connect Repo](/static/img/connect-repo.png)
+![Connect Repo](/static/img/connect-repo-no-github.png)
 
 ## Using Tokens with Reduced Scopes
 
@@ -25,6 +25,33 @@ OpenHands requests an API-scoped token during OAuth authentication. By default,
 To restrict the agent's permissions, you can define a custom secret `GITLAB_TOKEN`, which will override the default token assigned to the agent.
 While the high-permission API token is still requested and used for other components of the application (e.g. opening merge requests), the agent will not have access to it.
 
+## Working on GitLab Issues and Merge Requests Using Openhands
+
+<Note>
+This feature works for personal projects and is available for group projects with a
+[Premium or Ultimate tier subscription](https://docs.gitlab.com/user/project/integrations/webhooks/#group-webhooks).
+
+A webhook is automatically installed within a few minutes after the owner/maintainer of the project or group logs into
+OpenHands Cloud. If you decide to delete the webhook, then re-installing will require the support of All Hands AI but we are planning to improve this in a future release.
+</Note>
+
+Giving GitLab repository access to OpenHands also allows you to work on GitLab issues and merge requests directly.
+
+### Working with Issues
+
+On your repository, label an issue with `openhands` or add a message starting with `@openhands`. OpenHands will:
+1. Comment on the issue to let you know it is working on it.
+   - You can click on the link to track the progress on OpenHands Cloud.
+2. Open a merge request if it determines that the issue has been successfully resolved.
+3. Comment on the issue with a summary of the performed tasks and a link to the PR.
+
+### Working with Merge Requests
+
+To get OpenHands to work on merge requests, mention `@openhands` in the comments to:
+- Ask questions
+- Request updates
+- Get code explanations
+
 ## Next Steps
 
 - [Learn about the Cloud UI](/usage/cloud/cloud-ui).

docs/usage/cloud/openhands-cloud.mdx

@@ -8,9 +8,9 @@ description: Getting started with OpenHands Cloud.
 OpenHands Cloud is the hosted cloud version of All Hands AI's OpenHands. To get started with OpenHands Cloud,
 visit [app.all-hands.dev](https://app.all-hands.dev).
 
-You'll be prompted to connect with your GitHub or GitLab account:
+You'll be prompted to connect with your GitHub, GitLab or Bitbucket account:
 
-1. Click `Log in with GitHub` or `Log in with GitLab`.
+1. Click `Log in with GitHub`, `Log in with GitLab` or `Log in with Bitbucket`.
 2. Review the permissions requested by OpenHands and authorize the application.
    - OpenHands will require certain permissions from your account. To read more about these permissions,
      you can click the `Learn more` link on the authorization page.
@@ -22,5 +22,6 @@ Once you've connected your account, you can:
 
 - [Install GitHub Integration](/usage/cloud/github-installation) to use OpenHands with your GitHub repositories.
 - [Install GitLab Integration](/usage/cloud/gitlab-installation) to use OpenHands with your GitLab repositories.
+- [Install Bitbucket Integration](/usage/cloud/bitbucket-installation) to use OpenHands with your Bitbucket repositories.
 - [Learn about the Cloud UI](/usage/cloud/cloud-ui).
 - [Use the Cloud API](/usage/cloud/cloud-api) to programmatically interact with OpenHands.

docs/usage/cloud/project-management/jira-dc-integration.mdx

@@ -0,0 +1,118 @@
+---
+title: Jira Data Center Integration (Beta)
+description: Complete guide for setting up Jira Data Center integration with OpenHands Cloud, including service account creation, personal access token generation, webhook configuration, and workspace integration setup.
+---
+
+# Jira Data Center Integration
+
+## Platform Configuration
+
+### Step 1: Create Service Account
+
+1. **Access User Management**
+   - Log in to Jira Data Center as administrator
+   - Go to **Administration** > **User Management**
+
+2. **Create User**
+   - Click **Create User**
+   - Username: `openhands-agent`
+   - Full Name: `OpenHands Agent`
+   - Email: `openhands@yourcompany.com` (replace with your preferred service account email)
+   - Password: Set a secure password
+   - Click **Create**
+
+3. **Assign Permissions**
+   - Add user to appropriate groups
+   - Ensure access to relevant projects
+   - Grant necessary project permissions
+
+### Step 2: Generate API Token
+
+1. **Personal Access Tokens**
+   - Log in as the service account
+   - Go to **Profile** > **Personal Access Tokens**
+   - Click **Create token**
+   - Name: `OpenHands Cloud Integration`
+   - Expiry: Set appropriate expiration (recommend 1 year)
+   - Click **Create**
+   - **Important**: Copy and store the token securely
+
+### Step 3: Configure Webhook
+
+1. **Create Webhook**
+   - Go to **Administration** > **System** > **WebHooks**
+   - Click **Create a WebHook**
+   - **Name**: `OpenHands Cloud Integration`
+   - **URL**: `https://app.all-hands.dev/integration/jira-dc/events`
+   - Set a suitable webhook secret
+   - **Issue related events**: Select the following:
+     - Issue updated
+     - Comment created
+   - **JQL Filter**: Leave empty (or customize as needed)
+   - Click **Create**
+   - **Important**: Copy and store the webhook secret securely (you'll need this for workspace integration)
+
+---
+
+## Workspace Integration
+
+### Step 1: Log in to OpenHands Cloud
+
+1. **Navigate and Authenticate**
+   - Go to [OpenHands Cloud](https://app.all-hands.dev/)
+   - Sign in with your Git provider (GitHub, GitLab, or BitBucket)
+   - **Important:** Make sure you're signing in with the same Git provider account that contains the repositories you want the OpenHands agent to work on.
+
+### Step 2: Configure Jira Data Center Integration
+
+1. **Access Integration Settings**
+   - Navigate to **Settings** > **Integrations**
+   - Locate **Jira Data Center** section
+
+2. **Configure Workspace**
+   - Click **Configure** button
+   - Enter your workspace name and click **Connect**
+      - If no integration exists, you'll be prompted to enter additional credentials required for the workspace integration:
+         - **Webhook Secret**: The webhook secret from Step 3 above
+         - **Service Account Email**: The service account email from Step 1 above
+         - **Service Account API Key**: The personal access token from Step 2 above
+         - Ensure **Active** toggle is enabled
+
+3. **Complete OAuth Flow**
+   - You'll be redirected to Jira Data Center to complete OAuth verification
+   - Grant the necessary permissions to verify your workspace access. If you have access to multiple workspaces, select the correct one that you initially provided
+   - If successful, you will be redirected back to the **Integrations** settings in the OpenHands Cloud UI
+
+### Managing Your Integration
+
+**Edit Configuration:**
+- Click the **Edit** button next to your configured platform
+- Update any necessary credentials or settings
+- Click **Update** to apply changes
+- You will need to repeat the OAuth flow as before
+- **Important:** Only the original user who created the integration can see the edit view
+
+**Unlink Workspace:**
+- In the edit view, click **Unlink** next to the workspace name
+- This will deactivate your workspace link
+- **Important:** If the original user who configured the integration chooses to unlink their integration, any users currently linked to that integration will also be unlinked, and the workspace integration will be deactivated. The integration can only be reactivated by the original user.
+
+### Screenshots
+
+<AccordionGroup>
+<Accordion title="Workspace link flow">
+![workspace-link.png](/static/img/workspace-link.png)
+</Accordion>
+
+<Accordion title="Workspace Configure flow">
+![workspace-link.png](/static/img/workspace-configure.png)
+</Accordion>
+
+<Accordion title="Edit view as a user">
+![workspace-link.png](/static/img/workspace-user-edit.png)
+</Accordion>
+
+<Accordion title="Edit view as the workspace creator">
+![workspace-link.png](/static/img/workspace-admin-edit.png)
+</Accordion>
+</AccordionGroup>

docs/usage/cloud/project-management/jira-integration.mdx

@@ -0,0 +1,123 @@
+---
+title: Jira Cloud Integration
+description: Complete guide for setting up Jira Cloud integration with OpenHands Cloud, including service account creation, API token generation, webhook configuration, and workspace integration setup.
+---
+
+# Jira Cloud Integration
+
+## Platform Configuration
+
+### Step 1: Create Service Account
+
+1. **Navigate to User Management**
+   - Go to [Atlassian Admin](https://admin.atlassian.com/)
+   - Select your organization
+   - Go to **Directory** > **Users**
+
+2. **Create OpenHands Service Account**
+   - Click **Add user**
+   - Email: `openhands@yourcompany.com` (replace with your preferred service account email)
+   - Display name: `OpenHands Agent`
+   - Send invitation: **No** (you'll set password manually)
+   - Click **Add user**
+
+3. **Configure Account**
+   - Locate the created user and click on it
+   - Set a secure password
+   - Add to relevant Jira projects with appropriate permissions
+
+### Step 2: Generate API Token
+
+1. **Access API Token Management**
+   - Log in as the OpenHands service account
+   - Go to [API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
+
+2. **Create API Token**
+   - Click **Create API token**
+   - Label: `OpenHands Cloud Integration`
+   - Expiry: Set appropriate expiration (recommend 1 year)
+   - Click **Create**
+   - **Important**: Copy and securely store the token immediately
+
+### Step 3: Configure Webhook
+
+1. **Navigate to Webhook Settings**
+   - Go to **Jira Settings** > **System** > **WebHooks**
+   - Click **Create a WebHook**
+
+2. **Configure Webhook**
+   - **Name**: `OpenHands Cloud Integration`
+   - **Status**: Enabled
+   - **URL**: `https://app.all-hands.dev/integration/jira/events`
+   - **Issue related events**: Select the following:
+     - Issue updated
+     - Comment created
+   - **JQL Filter**: Leave empty (or customize as needed)
+   - Click **Create**
+   - **Important**: Copy and store the webhook secret securely (you'll need this for workspace integration)
+
+---
+
+## Workspace Integration
+
+### Step 1: Log in to OpenHands Cloud
+
+1. **Navigate and Authenticate**
+   - Go to [OpenHands Cloud](https://app.all-hands.dev/)
+   - Sign in with your Git provider (GitHub, GitLab, or BitBucket)
+   - **Important:** Make sure you're signing in with the same Git provider account that contains the repositories you want the OpenHands agent to work on.
+
+### Step 2: Configure Jira Integration
+
+1. **Access Integration Settings**
+   - Navigate to **Settings** > **Integrations**
+   - Locate **Jira Cloud** section
+
+2. **Configure Workspace**
+   - Click **Configure** button
+   - Enter your workspace name and click **Connect**
+   - **Important:** Make sure you enter the full workspace name, eg: **yourcompany.atlassian.net**
+      - If no integration exists, you'll be prompted to enter additional credentials required for the workspace integration:
+         - **Webhook Secret**: The webhook secret from Step 3 above
+         - **Service Account Email**: The service account email from Step 1 above
+         - **Service Account API Key**: The API token from Step 2 above
+         - Ensure **Active** toggle is enabled
+
+3. **Complete OAuth Flow**
+   - You'll be redirected to Jira Cloud to complete OAuth verification
+   - Grant the necessary permissions to verify your workspace access.
+   - If successful, you will be redirected back to the **Integrations** settings in the OpenHands Cloud UI
+
+### Managing Your Integration
+
+**Edit Configuration:**
+- Click the **Edit** button next to your configured platform
+- Update any necessary credentials or settings
+- Click **Update** to apply changes
+- You will need to repeat the OAuth flow as before
+- **Important:** Only the original user who created the integration can see the edit view
+
+**Unlink Workspace:**
+- In the edit view, click **Unlink** next to the workspace name
+- This will deactivate your workspace link
+- **Important:** If the original user who configured the integration chooses to unlink their integration, any users currently linked to that workspace integration will also be unlinked, and the workspace integration will be deactivated. The integration can only be reactivated by the original user.
+
+### Screenshots
+
+<AccordionGroup>
+<Accordion title="Workspace link flow">
+![workspace-link.png](/static/img/workspace-link.png)
+</Accordion>
+
+<Accordion title="Workspace Configure flow">
+![workspace-link.png](/static/img/workspace-configure.png)
+</Accordion>
+
+<Accordion title="Edit view as a user">
+![workspace-link.png](/static/img/workspace-user-edit.png)
+</Accordion>
+
+<Accordion title="Edit view as the workspace creator">
+![workspace-link.png](/static/img/workspace-admin-edit.png)
+</Accordion>
+</AccordionGroup>

docs/usage/cloud/project-management/linear-integration.mdx

@@ -0,0 +1,122 @@
+---
+title: Linear Integration
+description: Complete guide for setting up Linear integration with OpenHands Cloud, including service account creation, API key generation, webhook configuration, and workspace integration setup.
+---
+
+# Linear Integration
+
+## Platform Configuration
+
+### Step 1: Create Service Account
+
+1. **Access Team Settings**
+   - Log in to Linear as a team admin
+   - Go to **Settings** > **Members**
+
+2. **Invite Service Account**
+   - Click **Invite members**
+   - Email: `openhands@yourcompany.com` (replace with your preferred service account email)
+   - Role: **Member** (with appropriate team access)
+   - Send invitation
+
+3. **Complete Setup**
+   - Accept invitation from the service account email
+   - Complete profile setup
+   - Ensure access to relevant teams/workspaces
+
+### Step 2: Generate API Key
+
+1. **Access API Settings**
+   - Log in as the service account
+   - Go to **Settings** > **API**
+
+2. **Create Personal API Key**
+   - Click **Create new key**
+   - Name: `OpenHands Cloud Integration`
+   - Scopes: Select the following:
+     - `Read` - Read access to issues and comments
+     - `Create comments` - Ability to create or update comments
+   - Select the teams you want to provide access to, or allow access for all teams you have permissions for
+   - Click **Create**
+   - **Important**: Copy and store the API key securely
+
+### Step 3: Configure Webhook
+
+1. **Access Webhook Settings**
+   - Go to **Settings** > **API** > **Webhooks**
+   - Click **New webhook**
+
+2. **Configure Webhook**
+   - **Label**: `OpenHands Cloud Integration`
+   - **URL**: `https://app.all-hands.dev/integration/linear/events`
+   - **Resource types**: Select:
+     - `Comment` - For comment events
+     - `Issue` - For issue updates (label changes)
+   - Select the teams you want to provide access to, or allow access for all public teams
+   - Click **Create webhook**
+   - **Important**: Copy and store the webhook secret securely (you'll need this for workspace integration)
+
+---
+
+## Workspace Integration
+
+### Step 1: Log in to OpenHands Cloud
+
+1. **Navigate and Authenticate**
+   - Go to [OpenHands Cloud](https://app.all-hands.dev/)
+   - Sign in with your Git provider (GitHub, GitLab, or BitBucket)
+   - **Important:** Make sure you're signing in with the same Git provider account that contains the repositories you want the OpenHands agent to work on.
+
+### Step 2: Configure Linear Integration
+
+1. **Access Integration Settings**
+   - Navigate to **Settings** > **Integrations**
+   - Locate **Linear** section
+
+2. **Configure Workspace**
+   - Click **Configure** button
+   - Enter your workspace name and click **Connect**
+      - If no integration exists, you'll be prompted to enter additional credentials required for the workspace integration:
+         - **Webhook Secret**: The webhook secret from Step 3 above
+         - **Service Account Email**: The service account email from Step 1 above
+         - **Service Account API Key**: The API key from Step 2 above
+         - Ensure **Active** toggle is enabled
+
+3. **Complete OAuth Flow**
+   - You'll be redirected to Linear to complete OAuth verification
+   - Grant the necessary permissions to verify your workspace access. If you have access to multiple workspaces, select the correct one that you initially provided
+   - If successful, you will be redirected back to the **Integrations** settings in the OpenHands Cloud UI
+
+### Managing Your Integration
+
+**Edit Configuration:**
+- Click the **Edit** button next to your configured platform
+- Update any necessary credentials or settings
+- Click **Update** to apply changes
+- You will need to repeat the OAuth flow as before
+- **Important:** Only the original user who created the integration can see the edit view
+
+**Unlink Workspace:**
+- In the edit view, click **Unlink** next to the workspace name
+- This will deactivate your workspace link
+- **Important:** If the original user who configured the integration chooses to unlink their integration, any users currently linked to that integration will also be unlinked, and the workspace integration will be deactivated. The integration can only be reactivated by the original user.
+
+### Screenshots
+
+<AccordionGroup>
+<Accordion title="Workspace link flow">
+![workspace-link.png](/static/img/workspace-link.png)
+</Accordion>
+
+<Accordion title="Workspace Configure flow">
+![workspace-link.png](/static/img/workspace-configure.png)
+</Accordion>
+
+<Accordion title="Edit view as a user">
+![workspace-link.png](/static/img/workspace-user-edit.png)
+</Accordion>
+
+<Accordion title="Edit view as the workspace creator">
+![workspace-link.png](/static/img/workspace-admin-edit.png)
+</Accordion>
+</AccordionGroup>

docs/usage/cloud/project-management/overview.mdx

@@ -0,0 +1,79 @@
+---
+title: Project Management Tool Integrations
+description: Overview of OpenHands Cloud integrations with project management platforms including Jira Cloud, Jira Data Center, and Linear. Learn about setup requirements, usage methods, and troubleshooting.
+---
+
+# Project Management Tool Integrations
+
+## Overview
+
+OpenHands Cloud integrates with project management platforms (Jira Cloud, Jira Data Center, and Linear) to enable AI-powered task delegation. Users can invoke the OpenHands agent by:
+- Adding `@openhands` in ticket comments
+- Adding the `openhands` label to tickets
+
+## Prerequisites
+
+Integration requires two levels of setup:
+1. **Platform Configuration** - Administrative setup of service accounts and webhooks on your project management platform (see individual platform documentation below)
+2. **Workspace Integration** - Self-service configuration through the OpenHands Cloud UI to link your OpenHands account to the target workspace
+
+### Platform-Specific Setup Guides:
+- [Jira Cloud Integration](./jira-integration.md)
+- [Jira Data Center Integration](./jira-dc-integration.md)
+- [Linear Integration](./linear-integration.md)
+
+## Usage
+
+Once both the platform configuration and workspace integration are completed, users can trigger the OpenHands agent within their project management platforms using two methods:
+
+### Method 1: Comment Mention
+Add a comment to any issue with `@openhands` followed by your task description:
+```
+@openhands Please implement the user authentication feature described in this ticket
+```
+
+### Method 2: Label-based Delegation
+Add the label `openhands` to any issue. The OpenHands agent will automatically process the issue based on its description and requirements.
+
+### Git Repository Detection
+
+The OpenHands agent needs to identify which Git repository to work with when processing your issues. Here's how to ensure proper repository detection:
+
+#### Specifying the Target Repository
+
+**Required:** Include the target Git repository in your issue description or comment to ensure the agent works with the correct codebase.
+
+**Supported Repository Formats:**
+- Full HTTPS URL: `https://github.com/owner/repository.git`
+- GitHub URL without .git: `https://github.com/owner/repository`
+- Owner/repository format: `owner/repository`
+
+#### Platform-Specific Behavior
+
+**Linear Integration:** When GitHub integration is enabled for your Linear workspace with issue sync activated, the target repository is automatically detected from the linked GitHub issue. Manual specification is not required in this configuration.
+
+**Jira Integrations:** Always include the repository information in your issue description or `@openhands` comment to ensure proper repository detection.
+
+## Troubleshooting
+
+### Platform Configuration Issues
+- **Webhook not triggering**: Verify the webhook URL is correct and the proper event types are selected (Comment, Issue updated)
+- **API authentication failing**: Check API key/token validity and ensure required scopes are granted
+- **Permission errors**: Ensure the service account has access to relevant projects/teams and appropriate permissions
+
+### Workspace Integration Issues
+- **Workspace linking requests credentials**: If there are no active workspace integrations for the workspace you specified, you need to configure it first. Contact your platform administrator that you want to integrate with (eg: Jira, Linear)
+- **OAuth flow fails**: Ensure you're signing in with the same Git provider account that contains the repositories you want OpenHands to work on
+- **Integration not found**: Verify the workspace name matches exactly and that platform configuration was completed first
+
+### General Issues
+- **Agent not responding**: Check webhook logs in your platform settings and verify service account status
+- **Authentication errors**: Verify Git provider permissions and OpenHands Cloud access
+- **Partial functionality**: Ensure both platform configuration and workspace integration are properly completed
+
+### Getting Help
+For additional support, contact OpenHands Cloud support with:
+- Your integration platform (Linear, Jira Cloud, or Jira Data Center)
+- Workspace name
+- Error logs from webhook/integration attempts
+- Screenshots of configuration settings (without sensitive credentials)

docs/usage/cloud/slack-installation.mdx

@@ -12,6 +12,10 @@ description: This guide walks you through installing the OpenHands Slack app.
   allowFullScreen>
 </iframe>
 
+<Info>
+OpenHands utilizes a large language model (LLM), which may generate responses that are inaccurate or incomplete. While we strive for accuracy, OpenHands' outputs are not guaranteed to be correct, and we encourage users to validate critical information independently.
+</Info>
+
 ## Prerequisites
 
 - Access to OpenHands Cloud.
@@ -24,7 +28,7 @@ description: This guide walks you through installing the OpenHands Slack app.
   **This step is for Slack admins/owners**
 
   1. Make sure you have permissions to install Apps to your workspace.
-  2. Click the button below to install OpenHands Slack App <a target="_blank" href="https://slack.com/oauth/v2/authorize?client_id=7477886716822.8729519890534&scope=app_mentions:read,chat:write,users:read,channels:history,groups:history,mpim:history,im:history&user_scope=channels:history,groups:history,im:history,mpim:history"><img alt="Add to Slack" height="40" width="139" src="https://platform.slack-edge.com/img/add_to_slack.png" srcSet="https://platform.slack-edge.com/img/add_to_slack.png 1x, https://platform.slack-edge.com/img/add_to_slack@2x.png 2x" /></a>
+  2. Click the button below to install OpenHands Slack App <a target="_blank" href="https://slack.com/oauth/v2/authorize?client_id=7477886716822.8729519890534&scope=app_mentions:read,channels:history,chat:write,groups:history,im:history,mpim:history,users:read&user_scope="><img alt="Add to Slack" height="40" width="139" src="https://platform.slack-edge.com/img/add_to_slack.png" srcSet="https://platform.slack-edge.com/img/add_to_slack.png 1x, https://platform.slack-edge.com/img/add_to_slack@2x.png 2x" /></a>
   3. In the top right corner, select the workspace to install the OpenHands Slack app.
   4. Review permissions and click allow.
 

docs/usage/configuration-options.mdx

@@ -8,6 +8,12 @@ description: This page outlines all available configuration options for OpenHand
    In GUI Mode, any settings applied through the Settings UI will take precedence.
 </Note>
 
+## Location of the `config.toml` File
+
+When running OpenHands in CLI, headless, or development mode, you can use a project-specific `config.toml` file for configuration, which must be
+located in the same directory from which the command is run. Alternatively, you may use the `--config-file` option to
+specify a different path to the `config.toml` file.
+
 ## Core Configuration
 
 The core configuration options are defined in the `[core]` section of the `config.toml` file.

docs/usage/faqs.mdx

@@ -12,7 +12,8 @@ icon: question
   [GitHub](/usage/cloud/github-installation), [GitLab](/usage/cloud/gitlab-installation),
   and [Slack](/usage/cloud/slack-installation) integrations.
 2. **Run on your own**: If you prefer to run it on your own hardware, follow our [Getting Started guide](/usage/local-setup).
-3. **First steps**: Complete the [start building tutorial](/usage/getting-started) to learn the basics.
+3. **First steps**: Read over the [start building guidelines](/usage/getting-started) and
+  [prompting best practices](/usage/prompting/prompting-best-practices) to learn the basics.
 
 ### Can I use OpenHands for production workloads?
 

docs/usage/how-to/cli-mode.mdx

@@ -20,31 +20,86 @@ for scripting.
 
 ### Running with Python
 
-**Note** - OpenHands requires Python version 3.12 or higher (Python 3.14 is not currently supported)
+**Note** - OpenHands requires Python version 3.12 or higher (Python 3.14 is not currently supported) and `uv` for the default `fetch` MCP server (more details below).
 
-1. Install OpenHands using pip:
-```bash
-pip install openhands-ai
-```
+#### Recommended: Using uv
 
-  Or if you prefer not to manage your own Python environment, you can use `uvx`:
+We recommend using [uv](https://docs.astral.sh/uv/) for the best OpenHands experience. uv provides better isolation from your current project's virtual environment and is required for OpenHands' default MCP servers.
 
+1. **Install uv** (if you haven't already):
+
+   See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for the latest installation instructions for your platform.
+
+2. **Launch OpenHands CLI**:
 ```bash
 uvx --python 3.12 --from openhands-ai openhands
 ```
 
-2. Launch an interactive OpenHands conversation from the command line:
+<AccordionGroup>
+
+<Accordion title="Alternative: Traditional pip installation">
+
+If you prefer to use pip:
+
 ```bash
-openhands
+# Install OpenHands
+pip install openhands-ai
+```
+
+Note that you'll still need `uv` installed for the default MCP servers to work properly.
+
+</Accordion>
+
+<Accordion title="Create shell aliases for easy access across environments">
+
+Add the following to your shell configuration file (`.bashrc`, `.zshrc`, etc.):
+
+```bash
+# Add OpenHands aliases (recommended)
+alias openhands="uvx --python 3.12 --from openhands-ai openhands"
+alias oh="uvx --python 3.12 --from openhands-ai openhands"
+```
+
+After adding these lines, reload your shell configuration with `source ~/.bashrc` or `source ~/.zshrc` (depending on your shell).
+
+</Accordion>
+
+<Accordion title="Install OpenHands in home directory without global installation">
+
+You can install OpenHands in a virtual environment in your home directory using `uv`:
+
+```bash
+# Create a virtual environment in your home directory
+cd ~
+uv venv .openhands-venv --python 3.12
+
+# Install OpenHands in the virtual environment
+uv pip install -t ~/.openhands-venv/lib/python3.12/site-packages openhands-ai
+
+# Add the bin directory to your PATH in your shell configuration file
+echo 'export PATH="$PATH:$HOME/.openhands-venv/bin"' >> ~/.bashrc  # or ~/.zshrc
+
+# Reload your shell configuration
+source ~/.bashrc  # or source ~/.zshrc
+```
+
+</Accordion>
+
+</AccordionGroup>
+
+3. Launch an interactive OpenHands conversation from the command line:
+```bash
+# If using uvx (recommended)
+uvx --python 3.12 --from openhands-ai openhands
 ```
 
 <Note>
   If you have cloned the repository, you can also run the CLI directly using Poetry:
 
-  poetry run python -m openhands.cli.main
+  poetry run openhands
 </Note>
 
-3. Set your model, API key, and other preferences using the UI (or alternatively environment variables, below).
+4. Set your model, API key, and other preferences using the UI (or alternatively environment variables, below).
 
 This command opens an interactive prompt where you can type tasks or commands and get responses from OpenHands.
 The first time you run the CLI, it will take you through configuring the required LLM
@@ -64,7 +119,7 @@ The conversation history will be saved in `~/.openhands/sessions`.
 ```bash
 docker run -it \
     --pull=always \
-    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.52-nikolaik \
     -e SANDBOX_USER_ID=$(id -u) \
     -e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \
     -e LLM_API_KEY=$LLM_API_KEY \
@@ -73,7 +128,7 @@ docker run -it \
     -v ~/.openhands:/.openhands \
     --add-host host.docker.internal:host-gateway \
     --name openhands-app-$(date +%Y%m%d%H%M%S) \
-    docker.all-hands.dev/all-hands-ai/openhands:0.47 \
+    docker.all-hands.dev/all-hands-ai/openhands:0.52 \
     python -m openhands.cli.main --override-cli-mode true
 ```
 
@@ -84,7 +139,8 @@ docker run -it \
 
 This launches the CLI in Docker, allowing you to interact with OpenHands.
 
-The `-e SANDBOX_USER_ID=$(id -u)` ensures files created by the agent in your workspace have the correct permissions.
+The `-e SANDBOX_USER_ID=$(id -u)` is passed to the Docker command to ensure the sandbox user matches the host user’s
+permissions. This prevents the agent from creating root-owned files in the mounted workspace.
 
 The conversation history will be saved in `~/.openhands/sessions`.
 
@@ -113,6 +169,7 @@ You can use the following commands whenever the prompt (`>`) is displayed:
 | `/new`       | Start a new conversation                                       |
 | `/settings`  | View and modify current LLM/agent settings                     |
 | `/resume`    | Resume the agent if paused                                     |
+| `/mcp`       | Manage MCP server configuration and view connection errors    |
 
 #### Settings and Configuration
 
@@ -122,7 +179,7 @@ follow the prompts:
 - **Basic settings**: Choose a model/provider and enter your API key.
 - **Advanced settings**: Set custom endpoints, enable or disable confirmation mode, and configure memory condensation.
 
-Settings can also be managed via the `config.toml` file.
+Settings can also be managed via the `config.toml` file in the current directory or `~/.openhands/config.toml`.
 
 #### Repository Initialization
 
@@ -134,6 +191,41 @@ project details and structure. Use this when onboarding the agent to a new codeb
 You can pause the agent while it is running by pressing `Ctrl-P`. To continue the conversation after pausing, simply
 type `/resume` at the prompt.
 
+#### MCP Server Management
+
+To configure Model Context Protocol (MCP) servers, you can refer to the documentation on [MCP servers](../mcp) and use the `/mcp` command in the CLI. This command provides an interactive interface for managing Model Context Protocol (MCP) servers:
+
+- **List configured servers**: View all currently configured MCP servers (SSE, Stdio, and SHTTP)
+- **Add new server**: Interactively add a new MCP server with guided prompts
+- **Remove server**: Remove an existing MCP server from your configuration
+- **View errors**: Display any connection errors that occurred during MCP server startup
+
+This command modifies your `~/.openhands/config.toml` file and will prompt you to restart OpenHands for changes to take effect.
+
+By default, the [Fetch MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch) will be automatically configured for OpenHands. You can also [enable search engine](../search-engine-setup) via the [Tavily MCP server](https://github.com/tavily-ai/tavily-mcp) by setting the `search_api_key` under the `[core]` section in the `~/.openhands/config.toml` file.
+
+##### Example of the `config.toml` file with MCP server configuration:
+
+```toml
+[core]
+search_api_key = "tvly-your-api-key-here"
+
+[mcp]
+stdio_servers = [
+    {name="fetch", command="uvx", args=["mcp-server-fetch"]},
+]
+
+sse_servers = [
+    # Basic SSE server with just a URL
+    "http://example.com:8080/sse",
+]
+
+shttp_servers = [
+    # Streamable HTTP server with API key authentication
+    {url="https://secure-example.com/mcp", api_key="your-api-key"}
+]
+```
+
 ## Tips and Troubleshooting
 
 - Use `/help` at any time to see the list of available commands.

docs/usage/how-to/gui-mode.mdx

@@ -7,6 +7,67 @@ description: High level overview of the Graphical User Interface (GUI) in OpenHa
 
 - [OpenHands is running](/usage/local-setup)
 
+## Launching the GUI Server
+
+### Using the CLI Command
+
+You can launch the OpenHands GUI server directly from the command line using the `serve` command:
+
+<Callout type="info">
+**Prerequisites**: You need to have the [OpenHands CLI installed](/usage/how-to/cli-mode) first, OR have `uv` installed and run `uvx --python 3.12 --from openhands-ai openhands serve`. Otherwise, you'll need to use Docker directly (see the [Docker section](#using-docker-directly) below).
+</Callout>
+
+```bash
+openhands serve
+```
+
+This command will:
+- Check that Docker is installed and running
+- Pull the required Docker images
+- Launch the OpenHands GUI server at http://localhost:3000
+- Use the same configuration directory (`~/.openhands`) as the CLI mode
+
+#### Mounting Your Current Directory
+
+To mount your current working directory into the GUI server container, use the `--mount-cwd` flag:
+
+```bash
+openhands serve --mount-cwd
+```
+
+This is useful when you want to work on files in your current directory through the GUI. The directory will be mounted at `/workspace` inside the container.
+
+#### Using GPU Support
+
+If you have NVIDIA GPUs and want to make them available to the OpenHands container, use the `--gpu` flag:
+
+```bash
+openhands serve --gpu
+```
+
+This will enable GPU support via nvidia-docker, mounting all available GPUs into the container. You can combine this with other flags:
+
+```bash
+openhands serve --gpu --mount-cwd
+```
+
+**Prerequisites for GPU support:**
+- NVIDIA GPU drivers must be installed on your host system
+- [NVIDIA Container Toolkit (nvidia-docker2)](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) must be installed and configured
+
+#### Requirements
+
+Before using the `openhands serve` command, ensure that:
+- Docker is installed and running on your system
+- You have internet access to pull the required Docker images
+- Port 3000 is available on your system
+
+The CLI will automatically check these requirements and provide helpful error messages if anything is missing.
+
+### Using Docker Directly
+
+Alternatively, you can run the GUI server using Docker directly. See the [local setup guide](/usage/local-setup) for detailed Docker instructions.
+
 ## Overview
 
 ### Initial Setup
@@ -25,7 +86,8 @@ You can use the Settings page at any time to:
 - Setup the LLM provider and model for OpenHands.
 - [Setup the search engine](/usage/search-engine-setup).
 - [Configure MCP servers](/usage/mcp).
-- [Connect to GitHub](/usage/how-to/gui-mode#github-setup) and [connect to GitLab](/usage/how-to/gui-mode#gitlab-setup).
+- [Connect to GitHub](/usage/how-to/gui-mode#github-setup), [connect to GitLab](/usage/how-to/gui-mode#gitlab-setup)
+  and [connect to Bitbucket](/usage/how-to/gui-mode#bitbucket-setup).
 - Set application settings like your preferred language, notifications and other preferences.
 - [Manage custom secrets](/usage/common-settings#secrets-management).
 
@@ -122,17 +184,15 @@ OpenHands automatically exports a `GITLAB_TOKEN` to the shell environment if pro
 </Accordion>
 </AccordionGroup>
 
-#### BitBucket Setup (Coming soon ...)
+#### BitBucket Setup
 <AccordionGroup>
 <Accordion title="Setting Up a BitBucket Password">
 1. **Generate an App Password**:
    - On BitBucket, go to Personal Settings > App Password.
    - Create a new password with the following scopes:
-     - `repository: read`
+     - `account`: `read`
      - `repository: write`
-     - `pull requests: read`
      - `pull requests: write`
-     - `issues: read`
      - `issues: write`
    - App passwords are non-expiring token. OpenHands will migrate to using API tokens in the future.
   2. **Enter Token in OpenHands**:

docs/usage/how-to/headless-mode.mdx

@@ -18,42 +18,79 @@ poetry run python -m openhands.core.main -t "write a bash script that prints hi"
 You'll need to be sure to set your model, API key, and other settings via environment variables
 [or the `config.toml` file](https://github.com/All-Hands-AI/OpenHands/blob/main/config.template.toml).
 
-## With Docker
+### Working with Repositories
 
-To run OpenHands in Headless mode with Docker:
+You can specify a repository for OpenHands to work with using `--selected-repo` or the `SANDBOX_SELECTED_REPO` environment variable:
 
-1. Set the following environment variables in your terminal:
-   - `SANDBOX_VOLUMES` to specify the directory you want OpenHands to access ([See using SANDBOX_VOLUMES for more info](../runtimes/docker#using-sandbox_volumes))
-   - `LLM_MODEL` - the LLM model to use (e.g. `export LLM_MODEL="anthropic/claude-sonnet-4-20250514"`)
-   - `LLM_API_KEY` - your API key (e.g. `export LLM_API_KEY="sk_test_12345"`)
-
-2. Run the following Docker command:
+> **Note**: Currently, authentication tokens (GITHUB_TOKEN, GITLAB_TOKEN, or BITBUCKET_TOKEN) are required for all repository operations, including public repositories. This is a known limitation that may be addressed in future versions to allow tokenless access to public repositories.
 
 ```bash
+# Using command-line argument
+poetry run python -m openhands.core.main \
+  --selected-repo "owner/repo-name" \
+  -t "analyze the codebase and suggest improvements"
+
+# Using environment variable
+export SANDBOX_SELECTED_REPO="owner/repo-name"
+poetry run python -m openhands.core.main -t "fix any linting issues"
+
+# Authentication tokens are currently required for ALL repository operations (public and private)
+# This includes GitHub, GitLab, and Bitbucket repositories
+export GITHUB_TOKEN="your-token"  # or GITLAB_TOKEN, BITBUCKET_TOKEN
+poetry run python -m openhands.core.main \
+  --selected-repo "owner/repo-name" \
+  -t "review the security implementation"
+
+# Using task files instead of inline task
+echo "Review the README and suggest improvements" > task.txt
+poetry run python -m openhands.core.main -f task.txt --selected-repo "owner/repo"
+```
+
+## With Docker
+
+Set environment variables and run the Docker command:
+
+```bash
+# Set required environment variables
+export SANDBOX_VOLUMES="/path/to/workspace"  # See SANDBOX_VOLUMES docs for details
+export LLM_MODEL="anthropic/claude-sonnet-4-20250514"
+export LLM_API_KEY="your-api-key"
+export SANDBOX_SELECTED_REPO="owner/repo-name"  # Optional: requires GITHUB_TOKEN
+export GITHUB_TOKEN="your-token"  # Required for repository operations
+
+# Run OpenHands
 docker run -it \
     --pull=always \
-    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.52-nikolaik \
     -e SANDBOX_USER_ID=$(id -u) \
     -e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \
     -e LLM_API_KEY=$LLM_API_KEY \
     -e LLM_MODEL=$LLM_MODEL \
+    -e SANDBOX_SELECTED_REPO=$SANDBOX_SELECTED_REPO \
+    -e GITHUB_TOKEN=$GITHUB_TOKEN \
     -e LOG_ALL_EVENTS=true \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v ~/.openhands:/.openhands \
     --add-host host.docker.internal:host-gateway \
     --name openhands-app-$(date +%Y%m%d%H%M%S) \
-    docker.all-hands.dev/all-hands-ai/openhands:0.47 \
+    docker.all-hands.dev/all-hands-ai/openhands:0.52 \
     python -m openhands.core.main -t "write a bash script that prints hi"
 ```
-> **Note**: If you used OpenHands before version 0.44, you may want to run `mv ~/.openhands-state ~/.openhands` to migrate your conversation history to the new location.
+
+> **Note**: If you used OpenHands before version 0.44, run `mv ~/.openhands-state ~/.openhands` to migrate your conversation history.
 
 The `-e SANDBOX_USER_ID=$(id -u)` is passed to the Docker command to ensure the sandbox user matches the host user’s
 permissions. This prevents the agent from creating root-owned files in the mounted workspace.
 
-## Advanced Headless Configurations
+## Additional Options
 
-To view all available configuration options for headless mode, run the Python command with the `--help` flag.
+Common command-line options:
+- `-d "/path/to/workspace"` - Set working directory
+- `-f task.txt` - Load task from file
+- `-i 50` - Set max iterations
+- `-b 10.0` - Set budget limit (USD)
+- `--no-auto-continue` - Interactive mode
 
-### Additional Logs
+Run `poetry run python -m openhands.core.main --help` for all options.
 
-For the headless mode to log all the agent actions, in the terminal run: `export LOG_ALL_EVENTS=true`
+Set `export LOG_ALL_EVENTS=true` to log all agent actions.

docs/usage/llms/llms.mdx

@@ -10,16 +10,18 @@ This section is for users who want to connect OpenHands to different LLMs.
 ## Model Recommendations
 
 Based on our evaluations of language models for coding tasks (using the SWE-bench dataset), we can provide some
-recommendations for model selection. Our latest benchmarking results can be found in [this spreadsheet](https://docs.google.com/spreadsheets/d/1wOUdFCMyY6Nt0AIqF705KN4JKOWgeI4wUGUP60krXXs/edit?gid=0).
+recommendations for model selection. Our latest benchmarking results can be found in
+[this spreadsheet](https://docs.google.com/spreadsheets/d/1wOUdFCMyY6Nt0AIqF705KN4JKOWgeI4wUGUP60krXXs/edit?gid=0).
 
 Based on these findings and community feedback, these are the latest models that have been verified to work reasonably well with OpenHands:
 
 ### Cloud / API-Based Models
 
 - [anthropic/claude-sonnet-4-20250514](https://www.anthropic.com/api) (recommended)
-- [openai/o4-mini](https://openai.com/index/introducing-o3-and-o4-mini/)
+- [openai/gpt-5-2025-08-07](https://openai.com/api/) (recommended)
 - [gemini/gemini-2.5-pro](https://blog.google/technology/google-deepmind/gemini-model-thinking-updates-march-2025/)
 - [deepseek/deepseek-chat](https://api-docs.deepseek.com/)
+- [moonshot/kimi-k2-0711-preview](https://platform.moonshot.ai/docs/pricing/chat#generation-model-kimi-k2)
 
 If you have successfully run OpenHands with specific providers, we encourage you to open a PR to share your setup process
 to help others using the same provider!
@@ -37,6 +39,12 @@ limits and monitor usage.
 - [mistralai/devstral-small](https://www.all-hands.dev/blog/devstral-a-new-state-of-the-art-open-model-for-coding-agents) (20 May 2025) -- also available through [OpenRouter](https://openrouter.ai/mistralai/devstral-small:free)
 - [all-hands/openhands-lm-32b-v0.1](https://www.all-hands.dev/blog/introducing-openhands-lm-32b----a-strong-open-coding-agent-model) (31 March 2025) -- also available through [OpenRouter](https://openrouter.ai/all-hands/openhands-lm-32b-v0.1)
 
+### Known Issues
+
+<Warning>
+As of July 2025, there are known issues with Gemini 2.5 Pro conversations taking longer than normal with OpenHands. We are continuing to investigate.
+</Warning>
+
 <Note>
 Most current local and open source models are not as powerful. When using such models, you may see long
 wait times between messages, poor responses, or errors about malformed JSON. OpenHands can only be as powerful as the
@@ -70,17 +78,20 @@ We have a few guides for running OpenHands with specific model providers:
 - [Groq](/usage/llms/groq)
 - [Local LLMs with SGLang or vLLM](/usage/llms/local-llms)
 - [LiteLLM Proxy](/usage/llms/litellm-proxy)
+- [Moonshot AI](/usage/llms/moonshot)
 - [OpenAI](/usage/llms/openai-llms)
+- [OpenHands](/usage/llms/openhands-llms)
 - [OpenRouter](/usage/llms/openrouter)
 
 ## Model Customization
 
 LLM providers have specific settings that can be customized to optimize their performance with OpenHands, such as:
 
-- **Custom Tokenizers**: For specialized models, you can add a suitable tokenizer
-- **Native Tool Calling**: Toggle native function/tool calling capabilities
+- **Custom Tokenizers**: For specialized models, you can add a suitable tokenizer.
+- **Native Tool Calling**: Toggle native function/tool calling capabilities.
 
-For detailed information about model customization, see [LLM Configuration Options](configuration-options#llm-customization).
+For detailed information about model customization, see
+[LLM Configuration Options](/usage/configuration-options#llm-configuration).
 
 ### API retries and rate limits
 

docs/usage/llms/local-llms.mdx

@@ -68,23 +68,23 @@ Download and install the LM Studio desktop app from [lmstudio.ai](https://lmstud
 1. Check [the installation guide](/usage/local-setup) and ensure all prerequisites are met before running OpenHands, then run:
 
 ```bash
-docker pull docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik
+docker pull docker.all-hands.dev/all-hands-ai/runtime:0.52-nikolaik
 
 docker run -it --rm --pull=always \
-    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.52-nikolaik \
     -e LOG_ALL_EVENTS=true \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v ~/.openhands:/.openhands \
     -p 3000:3000 \
     --add-host host.docker.internal:host-gateway \
     --name openhands-app \
-    docker.all-hands.dev/all-hands-ai/openhands:0.47
+    docker.all-hands.dev/all-hands-ai/openhands:0.52
 ```
 
 2. Wait until the server is running (see log below):
 ```
 Digest: sha256:e72f9baecb458aedb9afc2cd5bc935118d1868719e55d50da73190d3a85c674f
-Status: Image is up to date for docker.all-hands.dev/all-hands-ai/openhands:0.47
+Status: Image is up to date for docker.all-hands.dev/all-hands-ai/openhands:0.52
 Starting OpenHands...
 Running OpenHands as root
 14:22:13 - openhands:INFO: server_config.py:50 - Using config class None
@@ -175,6 +175,27 @@ vllm serve mistralai/Devstral-Small-2505 \
     --enable-prefix-caching
 ```
 
+If you are interested in further improved inference speed, you can also try Snowflake's version
+of vLLM, [ArcticInference](https://www.snowflake.com/en/engineering-blog/fast-speculative-decoding-vllm-arctic/),
+which can achieve up to 2x speedup in some cases.
+
+1. Install the Arctic Inference library that automatically patches vLLM:
+
+```bash
+pip install git+https://github.com/snowflakedb/ArcticInference.git
+```
+
+2. Run the launch command with speculative decoding enabled:
+
+```bash
+vllm serve mistralai/Devstral-Small-2505 \
+    --host 0.0.0.0 --port 8000 \
+    --api-key mykey \
+    --tensor-parallel-size 2 \
+    --served-model-name Devstral-Small-2505 \
+    --speculative-config '{"method": "suffix"}'
+```
+
 ### Run OpenHands (Alternative Backends)
 
 #### Using Docker

docs/usage/llms/moonshot.mdx

@@ -0,0 +1,25 @@
+---
+title: Moonshot AI
+description: How to use Moonshot AI models with OpenHands
+---
+
+## Using Moonshot AI with OpenHands
+
+[Moonshot AI](https://platform.moonshot.ai/) offers several powerful models, including Kimi-K2, which has been verified to work well with OpenHands.
+
+### Setup
+
+1. Sign up for an account at [Moonshot AI Platform](https://platform.moonshot.ai/)
+2. Generate an API key from your account settings
+3. Configure OpenHands to use Moonshot AI:
+
+| Setting | Value |
+| --- | --- |
+| LLM Provider | `moonshot` |
+| LLM Model | `kimi-k2-0711-preview` |
+| API Key | Your Moonshot API key |
+
+### Recommended Models
+
+- `moonshot/kimi-k2-0711-preview` - Kimi-K2 is Moonshot's most powerful model with a 131K context window, function calling support, and web search capabilities.
+

docs/usage/llms/openhands-llms.mdx

@@ -0,0 +1,35 @@
+---
+title: OpenHands
+description: OpenHands LLM provider with access to state-of-the-art (SOTA) agentic coding models.
+---
+
+## Obtain Your OpenHands LLM API Key
+
+1. [Log in to OpenHands Cloud](/usage/cloud/openhands-cloud).
+2. Go to the Settings page and navigate to the `API Keys` tab.
+3. Copy your `LLM API Key`.
+
+![OpenHands LLM API Key](/static/img/openhands-llm-api-key.png)
+
+## Configuration
+
+When running OpenHands, you'll need to set the following in the OpenHands UI through the Settings under the `LLM` tab:
+- `LLM Provider` to `OpenHands`
+- `LLM Model` to the model you will be using (e.g. claude-sonnet-4-20250514)
+- `API Key` to your OpenHands LLM API key copied from above
+
+## Using OpenHands LLM Provider in the CLI
+
+1. [Run OpenHands CLI](/usage/how-to/cli-mode).
+2. To select OpenHands as the LLM provider:
+  - If this is your first time running the CLI, choose `openhands` and then select the model that you would like to use.
+  - If you have previously run the CLI, run the `/settings` command and select to modify the `Basic` settings. Then
+    choose `openhands` and finally the model.
+
+![OpenHands Provider in CLI](/static/img/openhands-provider-cli.png)
+
+## Pricing
+
+Pricing follows official API provider rates. [You can view model prices here.](https://github.com/BerriAI/litellm/blob/main/model_prices_and_context_window.json)
+
+For `qwen3-coder-480b`, we charge the cheapest FP8 rate available on openrouter: \$0.4 per million input tokens and \$1.6 per million output tokens.

docs/usage/local-setup.mdx

@@ -66,20 +66,64 @@ A system with a modern processor and a minimum of **4GB RAM** is recommended to
 
 ### Start the App
 
+#### Option 1: Using the CLI Launcher with uv (Recommended)
+
+We recommend using [uv](https://docs.astral.sh/uv/) for the best OpenHands experience. uv provides better isolation from your current project's virtual environment and is required for OpenHands' default MCP servers (like the [fetch MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch)).
+
+**Install uv** (if you haven't already):
+
+See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for the latest installation instructions for your platform.
+
+**Launch OpenHands**:
 ```bash
-docker pull docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik
+# Launch the GUI server
+uvx --python 3.12 --from openhands-ai openhands serve
+
+# Or with GPU support (requires nvidia-docker)
+uvx --python 3.12 --from openhands-ai openhands serve --gpu
+
+# Or with current directory mounted
+uvx --python 3.12 --from openhands-ai openhands serve --mount-cwd
+```
+
+This will automatically handle Docker requirements checking, image pulling, and launching the GUI server. The `--gpu` flag enables GPU support via nvidia-docker, and `--mount-cwd` mounts your current directory into the container.
+
+<Accordion title="Alternative: Traditional pip installation">
+
+If you prefer to use pip and have Python 3.12+ installed:
+
+```bash
+# Install OpenHands
+pip install openhands-ai
+
+# Launch the GUI server
+openhands serve
+```
+
+Note that you'll still need `uv` installed for the default MCP servers to work properly.
+
+</Accordion>
+
+#### Option 2: Using Docker Directly
+
+<Accordion title="Docker Command (Click to expand)">
+
+```bash
+docker pull docker.all-hands.dev/all-hands-ai/runtime:0.52-nikolaik
 
 docker run -it --rm --pull=always \
-    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.52-nikolaik \
     -e LOG_ALL_EVENTS=true \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v ~/.openhands:/.openhands \
     -p 3000:3000 \
     --add-host host.docker.internal:host-gateway \
     --name openhands-app \
-    docker.all-hands.dev/all-hands-ai/openhands:0.47
+    docker.all-hands.dev/all-hands-ai/openhands:0.52
 ```
 
+</Accordion>
+
 > **Note**: If you used OpenHands before version 0.44, you may want to run `mv ~/.openhands-state ~/.openhands` to migrate your conversation history to the new location.
 
 You'll find OpenHands running at http://localhost:3000!
@@ -100,6 +144,16 @@ OpenHands requires an API key to access most language models. Here's how to get
 
 <AccordionGroup>
 
+<Accordion title="OpenHands (Recommended)">
+
+1. [Log in to OpenHands Cloud](https://app.all-hands.dev).
+2. Go to the Settings page and navigate to the `API Keys` tab.
+3. Copy your `LLM API Key`.
+
+OpenHands provides access to state-of-the-art agentic coding models with competitive pricing. [Learn more about OpenHands LLM provider](/usage/llms/openhands-llms).
+
+</Accordion>
+
 <Accordion title="Anthropic (Claude)">
 
 1. [Create an Anthropic account](https://console.anthropic.com/).

docs/usage/mcp.mdx

@@ -10,38 +10,83 @@ Model Context Protocol (MCP) is a mechanism that allows OpenHands to communicate
 servers can provide additional functionality to the agent, such as specialized data processing, external API access,
 or custom tools. MCP is based on the open standard defined at [modelcontextprotocol.io](https://modelcontextprotocol.io).
 
+
+<Note>
+MCP is currently not available on OpenHands Cloud. This feature is only available when running OpenHands locally.
+</Note>
+
+### How MCP Works
+
+When OpenHands starts, it:
+
+1. Reads the MCP configuration.
+2. Connects to any configured SSE and SHTTP servers.
+3. Starts any configured stdio servers.
+4. Registers the tools provided by these servers with the agent.
+
+The agent can then use these tools just like any built-in tool. When the agent calls an MCP tool:
+
+1. OpenHands routes the call to the appropriate MCP server.
+2. The server processes the request and returns a response.
+3. OpenHands converts the response to an observation and presents it to the agent.
+
 ## Configuration
 
 MCP configuration can be defined in:
 * The OpenHands UI through the Settings under the `MCP` tab.
 * The `config.toml` file under the `[mcp]` section if not using the UI.
 
-### Configuration Example via config.toml
+### Configuration Examples
+
+#### Recommended: Using Proxy Servers (SSE/HTTP)
+
+For stdio-based MCP servers, we recommend using MCP proxy tools like [`supergateway`](https://github.com/supercorp-ai/supergateway) instead of direct stdio connections.
+[SuperGateway](https://github.com/supercorp-ai/supergateway) is a popular MCP proxy that converts stdio MCP servers to HTTP/SSE endpoints:
+
+Start the proxy servers separately:
+```bash
+# Terminal 1: Filesystem server proxy
+supergateway --stdio "npx @modelcontextprotocol/server-filesystem /" --port 8080
+
+# Terminal 2: Fetch server proxy
+supergateway --stdio "uvx mcp-server-fetch" --port 8081
+```
+
+Then configure OpenHands to use the HTTP endpoint:
 
 ```toml
 [mcp]
-# SSE Servers - External servers that communicate via Server-Sent Events
+# SSE Servers - Recommended approach using proxy tools
 sse_servers = [
     # Basic SSE server with just a URL
     "http://example.com:8080/mcp",
 
-    # SSE server with API key authentication
-    {url="https://secure-example.com/mcp", api_key="your-api-key"}
-]
+    # SuperGateway proxy for fetch server
+    "http://localhost:8081/sse",
 
-# Stdio Servers - Local processes that communicate via standard input/output
+    # External MCP service with authentication
+    {url="https://api.example.com/mcp/sse", api_key="your-api-key"}
+]
+```
+
+
+
+#### Alternative: Direct Stdio Servers (Not Recommended for Production)
+
+```toml
+[mcp]
+# Direct stdio servers - use only for development/testing
 stdio_servers = [
     # Basic stdio server
     {name="fetch", command="uvx", args=["mcp-server-fetch"]},
 
     # Stdio server with environment variables
     {
-        name="data-processor",
-        command="python",
-        args=["-m", "my_mcp_server"],
+        name="filesystem",
+        command="npx",
+        args=["@modelcontextprotocol/server-filesystem", "/"],
         env={
-            "DEBUG": "true",
-            "PORT": "8080"
+            "DEBUG": "true"
         }
     }
 ]
@@ -57,8 +102,26 @@ SSE servers are configured using either a string URL or an object with the follo
   - Type: `str`
   - Description: The URL of the SSE server
 
+- `api_key` (optional)
+  - Type: `str`
+  - Description: API key for authentication
+
+### SHTTP Servers
+
+SHTTP (Streamable HTTP) servers are configured using either a string URL or an object with the following properties:
+
+- `url` (required)
+  - Type: `str`
+  - Description: The URL of the SHTTP server
+
+- `api_key` (optional)
+  - Type: `str`
+  - Description: API key for authentication
+
 ### Stdio Servers
 
+**Note**: While stdio servers are supported, we recommend using MCP proxies (see above) for better reliability and performance.
+
 Stdio servers are configured using an object with the following properties:
 
 - `name` (required)
@@ -79,17 +142,55 @@ Stdio servers are configured using an object with the following properties:
   - Default: `{}`
   - Description: Environment variables to set for the server process
 
-## How MCP Works
 
-When OpenHands starts, it:
+#### When to Use Direct Stdio
 
-1. Reads the MCP configuration.
-2. Connects to any configured SSE servers.
-3. Starts any configured stdio servers.
-4. Registers the tools provided by these servers with the agent.
+Direct stdio connections may still be appropriate in these scenarios:
+- **Development and testing**: Quick prototyping of MCP servers
+- **Simple, single-use tools**: Tools that don't require high reliability or concurrent access
+- **Local-only environments**: When you don't want to manage additional proxy processes
 
-The agent can then use these tools just like any built-in tool. When the agent calls an MCP tool:
+For production use, we recommend using proxy tools like SuperGateway.
 
-1. OpenHands routes the call to the appropriate MCP server.
-2. The server processes the request and returns a response.
-3. OpenHands converts the response to an observation and presents it to the agent.
+### Other Proxy Tools
+
+Other options include:
+
+- **Custom FastAPI/Express servers**: Build your own HTTP wrapper around stdio MCP servers
+- **Docker-based proxies**: Containerized solutions for better isolation
+- **Cloud-hosted MCP services**: Third-party services that provide MCP endpoints
+
+### Troubleshooting MCP Connections
+
+#### Common Issues with Stdio Servers
+- **Process crashes**: Stdio processes may crash without proper error handling
+- **Deadlocks**: Stdio communication can deadlock under high load
+- **Resource leaks**: Zombie processes if not properly managed
+- **Debugging difficulty**: Hard to inspect stdio communication
+
+#### Benefits of Using Proxies
+- **HTTP status codes**: Clear error reporting via standard HTTP responses
+- **Request logging**: Easy to log and monitor HTTP requests
+- **Load balancing**: Can distribute requests across multiple server instances
+- **Health checks**: HTTP endpoints can provide health status
+- **CORS support**: Better integration with web-based tools
+
+## Transport Protocols
+
+OpenHands supports three different MCP transport protocols:
+
+### Server-Sent Events (SSE)
+SSE is a legacy HTTP-based transport that uses Server-Sent Events for server-to-client communication and HTTP POST requests for client-to-server communication. This transport is suitable for basic streaming scenarios but has limitations in session management and connection resumability.
+
+### Streamable HTTP (SHTTP)
+SHTTP is the modern HTTP-based transport protocol that provides enhanced features over SSE:
+
+- **Improved Session Management**: Supports stateful sessions with session IDs for maintaining context across requests
+- **Connection Resumability**: Can resume broken connections and replay missed messages using event IDs
+- **Bidirectional Communication**: Uses HTTP POST for client-to-server and optional SSE streams for server-to-client communication
+- **Better Error Handling**: Enhanced error reporting and recovery mechanisms
+
+SHTTP is the recommended transport for HTTP-based MCP servers as it provides better reliability and features compared to the legacy SSE transport.
+
+### Standard Input/Output (stdio)
+Stdio transport enables communication through standard input and output streams, making it ideal for local integrations and command-line tools. This transport is used for locally executed MCP servers that run as separate processes.

docs/usage/prompting/microagents-org.mdx

@@ -24,3 +24,12 @@ General microagent file example for organization `Great-Co` located inside the `
 ```
 
 For GitLab organizations, the same microagent would be located inside the `openhands-config` repository.
+
+## User Microagents When Running Openhands on Your Own
+
+<Note>
+  This works with CLI, headless and development modes. It does not work out of the box when running OpenHands using the docker command.
+</Note>
+
+When running OpenHands on your own, you can place microagents in the `~/.openhands/microagents` folder on your local
+system and OpenHands will always load it for all your conversations.

docs/usage/troubleshooting/troubleshooting.mdx

@@ -38,6 +38,21 @@ On initial prompt, an error is seen with `Permission Denied` or `PermissionError
 * If mounting a local directory, ensure your `WORKSPACE_BASE` has the necessary permissions for the user running
   OpenHands.
 
+### Internal Server Error. Ports are not available
+
+**Description**
+
+When running on Windows, the error `Internal Server Error ("ports are not available: exposing port TCP
+...: bind: An attempt was made to access a socket in a
+way forbidden by its access permissions.")` is encountered.
+
+**Resolution**
+
+* Run the following command in PowerShell, as Administrator to reset the NAT service and release the ports:
+```
+Restart-Service -Name "winnat"
+```
+
 ### Unable to access VS Code tab via local IP
 
 **Description**

evaluation/README.md

@@ -101,13 +101,14 @@ The OpenHands evaluation harness supports a wide variety of benchmarks across [s
 - SWE-Bench: [`evaluation/benchmarks/swe_bench`](./benchmarks/swe_bench)
 - HumanEvalFix: [`evaluation/benchmarks/humanevalfix`](./benchmarks/humanevalfix)
 - BIRD: [`evaluation/benchmarks/bird`](./benchmarks/bird)
-- BioCoder: [`evaluation/benchmarks/ml_bench`](./benchmarks/ml_bench)
+- BioCoder: [`evaluation/benchmarks/biocoder`](./benchmarks/biocoder)
 - ML-Bench: [`evaluation/benchmarks/ml_bench`](./benchmarks/ml_bench)
 - APIBench: [`evaluation/benchmarks/gorilla`](./benchmarks/gorilla/)
 - ToolQA: [`evaluation/benchmarks/toolqa`](./benchmarks/toolqa/)
 - AiderBench: [`evaluation/benchmarks/aider_bench`](./benchmarks/aider_bench/)
 - Commit0: [`evaluation/benchmarks/commit0_bench`](./benchmarks/commit0_bench/)
 - DiscoveryBench: [`evaluation/benchmarks/discoverybench`](./benchmarks/discoverybench/)
+- TerminalBench: [`evaluation/benchmarks/terminal_bench`](./benchmarks/terminal_bench)
 
 ### Web Browsing
 

evaluation/benchmarks/EDA/run_infer.py

@@ -18,8 +18,8 @@ from evaluation.utils.shared import (
 from openhands.controller.state.state import State
 from openhands.core.config import (
     OpenHandsConfig,
+    get_evaluation_parser,
     get_llm_config_arg,
-    get_parser,
 )
 from openhands.core.logger import openhands_logger as logger
 from openhands.core.main import create_runtime, run_controller
@@ -172,7 +172,7 @@ def process_instance(
 
 
 if __name__ == '__main__':
-    parser = get_parser()
+    parser = get_evaluation_parser()
     parser.add_argument(
         '--answerer_model', '-a', default='gpt-3.5-turbo', help='answerer model'
     )

evaluation/benchmarks/commit0/run_infer.py

@@ -26,8 +26,8 @@ from openhands.controller.state.state import State
 from openhands.core.config import (
     AgentConfig,
     OpenHandsConfig,
+    get_evaluation_parser,
     get_llm_config_arg,
-    get_parser,
 )
 from openhands.core.logger import openhands_logger as logger
 from openhands.core.main import create_runtime, run_controller
@@ -117,6 +117,7 @@ def get_config(
         default_agent=metadata.agent_class,
         run_as_openhands=False,
         max_iterations=metadata.max_iterations,
+        enable_browser=RUN_WITH_BROWSING,
         runtime=os.environ.get('RUNTIME', 'docker'),
         sandbox=sandbox_config,
         # do not mount workspace
@@ -505,7 +506,6 @@ def commit0_setup(dataset: pd.DataFrame, repo_split: str) -> pd.DataFrame:
     Returns:
         Filtered dataset based on split type
     """
-
     filtered_dataset = pd.concat(
         [
             dataset[dataset['repo'].str.split('/').str[1] == repo]
@@ -524,7 +524,7 @@ def commit0_setup(dataset: pd.DataFrame, repo_split: str) -> pd.DataFrame:
 
 
 if __name__ == '__main__':
-    parser = get_parser()
+    parser = get_evaluation_parser()
     parser.add_argument(
         '--dataset',
         type=str,

evaluation/benchmarks/discoverybench/run_infer.py

@@ -89,8 +89,7 @@ def get_config(
 def get_dv_query_for_real(
     datasets, question, domain_knowledge=None, workflow_tags=None
 ):
-    """
-    Prepare a structured query for the agent to execute on the specified datasets.
+    """Prepare a structured query for the agent to execute on the specified datasets.
 
     This function constructs a query by compiling metadata from the provided datasets, along with any relevant domain knowledge and workflow tags.
 
@@ -104,7 +103,6 @@ def get_dv_query_for_real(
         query_to_dv: Query to be run on the dataset
         dataset_meta: Metadata of the dataset
     """
-
     dataset_meta = ''
     for dataset_metadata in datasets:
         dataset_meta += 'Dataset name: ' + dataset_metadata['name']
@@ -140,8 +138,7 @@ def get_dv_query_for_real(
 
 
 def initialize_runtime(runtime: Runtime, data_files: list[str]):
-    """
-    Initialize the runtime for the agent.
+    """Initialize the runtime for the agent.
 
     This function is called before the runtime is used to run the agent.
     """
@@ -231,8 +228,7 @@ def process_instance(
     metadata: EvalMetadata,
     reset_logger: bool = True,
 ):
-    """
-    Process and evaluate a single instance of the dataset.
+    """Process and evaluate a single instance of the dataset.
 
     This function executes the OpenHands agent
     for a specific instance of the dataset. It retrieves
@@ -247,7 +243,6 @@ def process_instance(
     Returns:
         output: EvalOutput object
     """
-
     config = get_config(metadata)
 
     # Setup the logger properly, so you can run
@@ -356,8 +351,7 @@ def list_csv_files(list_of_datasets):
 
 
 def create_dataset(repo_location: str, split: str = 'test'):
-    """
-    Create a dataset from the discoverybench repository
+    """Create a dataset from the discoverybench repository
     by walking through the repository and extracting metadata
     from the metadata_{}.json files
 
@@ -368,7 +362,6 @@ def create_dataset(repo_location: str, split: str = 'test'):
     Returns:
         df: DataFrame containing the dataset instances
     """
-
     data_dict = {}
 
     data_location = os.path.join(repo_location, 'discoverybench', 'real', split)

evaluation/benchmarks/gaia/run_infer.py

@@ -10,7 +10,6 @@ import huggingface_hub
 import pandas as pd
 from datasets import load_dataset
 from PIL import Image
-from pydantic import SecretStr
 
 from evaluation.benchmarks.gaia.scorer import question_scorer
 from evaluation.benchmarks.gaia.utils import (
@@ -31,8 +30,8 @@ from evaluation.utils.shared import (
 from openhands.controller.state.state import State
 from openhands.core.config import (
     OpenHandsConfig,
+    get_evaluation_parser,
     get_llm_config_arg,
-    get_parser,
     load_from_toml,
 )
 from openhands.core.config.utils import get_agent_config_arg
@@ -80,8 +79,7 @@ def get_config(
 
     config_copy = copy.deepcopy(config)
     load_from_toml(config_copy)
-    if config_copy.search_api_key:
-        config.search_api_key = SecretStr(config_copy.search_api_key)
+    config.search_api_key = config_copy.search_api_key
     return config
 
 
@@ -294,7 +292,7 @@ Here is the task:
 
 
 if __name__ == '__main__':
-    parser = get_parser()
+    parser = get_evaluation_parser()
     parser.add_argument(
         '--level',
         type=str,

evaluation/benchmarks/gorilla/run_infer.py

@@ -20,8 +20,8 @@ from evaluation.utils.shared import (
 from openhands.controller.state.state import State
 from openhands.core.config import (
     OpenHandsConfig,
+    get_evaluation_parser,
     get_llm_config_arg,
-    get_parser,
 )
 from openhands.core.logger import openhands_logger as logger
 from openhands.core.main import create_runtime, run_controller
@@ -134,7 +134,7 @@ def process_instance(
 
 
 if __name__ == '__main__':
-    parser = get_parser()
+    parser = get_evaluation_parser()
     parser.add_argument(
         '--hubs',
         type=str,

evaluation/benchmarks/gpqa/run_infer.py

@@ -38,8 +38,8 @@ from evaluation.utils.shared import (
 from openhands.controller.state.state import State
 from openhands.core.config import (
     OpenHandsConfig,
+    get_evaluation_parser,
     get_llm_config_arg,
-    get_parser,
 )
 from openhands.core.logger import openhands_logger as logger
 from openhands.core.main import create_runtime, run_controller
@@ -312,7 +312,7 @@ Ok now its time to start solving the question. Good luck!
 
 
 if __name__ == '__main__':
-    parser = get_parser()
+    parser = get_evaluation_parser()
     # data split must be one of 'gpqa_main', 'gqpa_diamond', 'gpqa_experts', 'gpqa_extended'
     parser.add_argument(
         '--data-split',

evaluation/benchmarks/lca_ci_build_repair/eval_infer.py

@@ -21,7 +21,7 @@ from evaluation.utils.shared import (
 from openhands.core.config import (
     LLMConfig,
     OpenHandsConfig,
-    get_parser,
+    get_evaluation_parser,
     load_openhands_config,
 )
 from openhands.core.logger import openhands_logger as logger
@@ -167,7 +167,7 @@ def process_predictions(predictions_path: str):
 
 
 if __name__ == '__main__':
-    parser = get_parser()
+    parser = get_evaluation_parser()
     parser.add_argument(
         '-s',
         '--eval-split',

evaluation/benchmarks/lca_ci_build_repair/run_infer.py

@@ -30,8 +30,8 @@ from evaluation.utils.shared import (
 from openhands.controller.state.state import State
 from openhands.core.config import (
     OpenHandsConfig,
+    get_evaluation_parser,
     get_llm_config_arg,
-    get_parser,
     load_openhands_config,
 )
 from openhands.core.logger import openhands_logger as logger
@@ -358,7 +358,7 @@ Be thorough in your exploration, testing, and reasoning. It's fine if your think
 
 
 if __name__ == '__main__':
-    parser = get_parser()
+    parser = get_evaluation_parser()
     parser.add_argument(
         '-s',
         '--eval-split',

evaluation/benchmarks/logic_reasoning/run_infer.py

@@ -18,8 +18,8 @@ from evaluation.utils.shared import (
 from openhands.controller.state.state import State
 from openhands.core.config import (
     OpenHandsConfig,
+    get_evaluation_parser,
     get_llm_config_arg,
-    get_parser,
 )
 from openhands.core.logger import openhands_logger as logger
 from openhands.core.main import create_runtime, run_controller
@@ -267,7 +267,7 @@ def process_instance(
 
 
 if __name__ == '__main__':
-    parser = get_parser()
+    parser = get_evaluation_parser()
     parser.add_argument(
         '--dataset',
         type=str,

evaluation/benchmarks/mint/run_infer.py

@@ -23,8 +23,8 @@ from evaluation.utils.shared import (
 from openhands.controller.state.state import State
 from openhands.core.config import (
     OpenHandsConfig,
+    get_evaluation_parser,
     get_llm_config_arg,
-    get_parser,
 )
 from openhands.core.logger import openhands_logger as logger
 from openhands.core.main import create_runtime, run_controller
@@ -229,7 +229,7 @@ def process_instance(
 
 
 if __name__ == '__main__':
-    parser = get_parser()
+    parser = get_evaluation_parser()
 
     SUBSETS = [
         # Eurus subset: https://arxiv.org/abs/2404.02078

evaluation/benchmarks/ml_bench/run_analysis.py

@@ -4,7 +4,11 @@ import pprint
 
 import tqdm
 
-from openhands.core.config import get_llm_config_arg, get_parser, load_openhands_config
+from openhands.core.config import (
+    get_evaluation_parser,
+    get_llm_config_arg,
+    load_openhands_config,
+)
 from openhands.core.logger import openhands_logger as logger
 from openhands.llm.llm import LLM
 
@@ -111,7 +115,7 @@ def classify_error(llm: LLM, failed_case: dict) -> str:
 
 
 if __name__ == '__main__':
-    parser = get_parser()
+    parser = get_evaluation_parser()
     parser.add_argument(
         '--json_file_path',
         type=str,

evaluation/benchmarks/ml_bench/run_infer.py

@@ -34,8 +34,8 @@ from evaluation.utils.shared import (
 from openhands.controller.state.state import State
 from openhands.core.config import (
     OpenHandsConfig,
+    get_evaluation_parser,
     get_llm_config_arg,
-    get_parser,
     load_openhands_config,
 )
 from openhands.core.logger import openhands_logger as logger
@@ -273,7 +273,7 @@ def process_instance(instance: Any, metadata: EvalMetadata, reset_logger: bool =
 
 
 if __name__ == '__main__':
-    parser = get_parser()
+    parser = get_evaluation_parser()
     parser.add_argument(
         '-s',
         '--eval-split',

evaluation/benchmarks/multi_swe_bench/README.md

@@ -41,6 +41,10 @@ default, it is set to 1.
 - `language`, the language of your evaluating dataset.
 - `dataset`, the absolute position of the dataset jsonl.
 
+**Skipping errors on build**
+
+For debugging purposes, you can set `export EVAL_SKIP_MAXIMUM_RETRIES_EXCEEDED=true` to continue evaluation even when instances reach maximum retries. After evaluation completes, check `maximum_retries_exceeded.jsonl` for a list of failed instances, fix those issues, and then run the evaluation again with `export EVAL_SKIP_MAXIMUM_RETRIES_EXCEEDED=false`.
+
 The results will be generated in evaluation/evaluation_outputs/outputs/XXX/CodeActAgent/YYY/output.jsonl, you can refer to the [example](examples/output.jsonl).
 
 ## Runing evaluation

evaluation/benchmarks/multi_swe_bench/eval_infer.py

@@ -30,7 +30,7 @@ from evaluation.utils.shared import (
 from openhands.core.config import (
     LLMConfig,
     OpenHandsConfig,
-    get_parser,
+    get_evaluation_parser,
 )
 from openhands.core.logger import openhands_logger as logger
 from openhands.core.main import create_runtime
@@ -105,8 +105,7 @@ def process_instance(
     log_dir: str | None = None,
     runtime_failure_count: int = 0,
 ) -> EvalOutput:
-    """
-    Evaluate agent performance on a SWE-bench problem instance.
+    """Evaluate agent performance on a SWE-bench problem instance.
 
     Note that this signature differs from the expected input to `run_evaluation`. Use
     `functools.partial` to provide optional arguments before passing to the evaluation harness.
@@ -323,7 +322,7 @@ def process_instance(
 
 
 if __name__ == '__main__':
-    parser = get_parser()
+    parser = get_evaluation_parser()
     parser.add_argument(
         '--input-file',
         type=str,

evaluation/benchmarks/multi_swe_bench/run_infer.py

@@ -17,6 +17,7 @@ from evaluation.utils.shared import (
     EvalMetadata,
     EvalOutput,
     assert_and_raise,
+    check_maximum_retries_exceeded,
     codeact_user_response,
     get_default_sandbox_config_for_eval,
     get_metrics,
@@ -31,8 +32,8 @@ from openhands.controller.state.state import State
 from openhands.core.config import (
     AgentConfig,
     OpenHandsConfig,
+    get_evaluation_parser,
     get_llm_config_arg,
-    get_parser,
 )
 from openhands.core.logger import openhands_logger as logger
 from openhands.core.main import create_runtime, run_controller
@@ -344,6 +345,7 @@ def get_config(
         default_agent=metadata.agent_class,
         run_as_openhands=False,
         max_iterations=metadata.max_iterations,
+        enable_browser=RUN_WITH_BROWSING,
         runtime=os.environ.get('RUNTIME', 'docker'),
         sandbox=sandbox_config,
         # do not mount workspace
@@ -770,7 +772,7 @@ def filter_dataset(dataset: pd.DataFrame, filter_column: str) -> pd.DataFrame:
 
 if __name__ == '__main__':
     # pdb.set_trace()
-    parser = get_parser()
+    parser = get_evaluation_parser()
     parser.add_argument(
         '--dataset',
         type=str,
@@ -843,3 +845,5 @@ if __name__ == '__main__':
         timeout_seconds=120 * 60,  # 2 hour PER instance should be more than enough
         max_retries=5,
     )
+    # Check if any instances reached maximum retries
+    check_maximum_retries_exceeded(metadata.eval_output_dir)

evaluation/benchmarks/scienceagentbench/run_infer.py

@@ -21,8 +21,8 @@ from evaluation.utils.shared import (
 from openhands.controller.state.state import State
 from openhands.core.config import (
     OpenHandsConfig,
+    get_evaluation_parser,
     get_llm_config_arg,
-    get_parser,
 )
 from openhands.core.logger import openhands_logger as logger
 from openhands.core.main import create_runtime, run_controller
@@ -239,7 +239,7 @@ If the program uses some packages that are incompatible, please figure out alter
 
 
 if __name__ == '__main__':
-    parser = get_parser()
+    parser = get_evaluation_parser()
     parser.add_argument(
         '--use-knowledge',
         type=str,

evaluation/benchmarks/swe_bench/README.md

@@ -2,6 +2,8 @@
 
 This folder contains the evaluation harness that we built on top of the original [SWE-Bench benchmark](https://www.swebench.com/) ([paper](https://arxiv.org/abs/2310.06770)).
 
+**UPDATE (8/12/2025): We now support running SWE-rebench evaluation (see the paper [here](https://arxiv.org/abs/2505.20411))! For how to run it, checkout [this README](./SWE-rebench.md).**
+
 **UPDATE (6/15/2025): We now support running SWE-bench-Live evaluation (see the paper [here](https://arxiv.org/abs/2505.23419))! For how to run it, checkout [this README](./SWE-bench-Live.md).**
 
 **UPDATE (5/26/2025): We now support running interactive SWE-Bench evaluation (see the paper [here](https://arxiv.org/abs/2502.13069))! For how to run it, checkout [this README](./SWE-Interact.md).**
@@ -38,6 +40,10 @@ Please follow instruction [here](../../README.md#setup) to setup your local deve
 > - If your LLM config has temperature=0, we will automatically use temperature=0.1 for the 2nd and 3rd attempts
 >
 > To enable this iterative protocol, set `export ITERATIVE_EVAL_MODE=true`
+>
+> **Skipping errors on build**
+>
+> For debugging purposes, you can set `export EVAL_SKIP_MAXIMUM_RETRIES_EXCEEDED=true` to continue evaluation even when instances reach maximum retries. After evaluation completes, check `maximum_retries_exceeded.jsonl` for a list of failed instances, fix those issues, and then run the evaluation again with `export EVAL_SKIP_MAXIMUM_RETRIES_EXCEEDED=false`.
 
 
 ### Running Locally with Docker
@@ -179,24 +185,7 @@ The final results will be saved to `evaluation/evaluation_outputs/outputs/swe_be
 - `report.json`: a JSON file that contains keys like `"resolved_ids"` pointing to instance IDs that are resolved by the agent.
 - `logs/`: a directory of test logs
 
-### Run evaluation with `RemoteRuntime`
 
-OpenHands Remote Runtime is currently in beta (read [here](https://runtime.all-hands.dev/) for more details), it allows you to run rollout in parallel in the cloud, so you don't need a powerful machine to run evaluation.
-Fill out [this form](https://docs.google.com/forms/d/e/1FAIpQLSckVz_JFwg2_mOxNZjCtr7aoBFI2Mwdan3f75J_TrdMS1JV2g/viewform) to apply if you want to try this out!
-
-```bash
-./evaluation/benchmarks/swe_bench/scripts/eval_infer_remote.sh [output.jsonl filepath] [num_workers]
-
-# Example - This evaluates patches generated by CodeActAgent on Llama-3.1-70B-Instruct-Turbo on "princeton-nlp/SWE-bench_Lite"'s test set, with 16 number of workers running in parallel
-ALLHANDS_API_KEY="YOUR-API-KEY" RUNTIME=remote SANDBOX_REMOTE_RUNTIME_API_URL="https://runtime.eval.all-hands.dev" EVAL_DOCKER_IMAGE_PREFIX="us-central1-docker.pkg.dev/evaluation-092424/swe-bench-images" \
-evaluation/benchmarks/swe_bench/scripts/eval_infer_remote.sh evaluation/evaluation_outputs/outputs/swe-bench-lite/CodeActAgent/Llama-3.1-70B-Instruct-Turbo_maxiter_100_N_v1.9-no-hint/output.jsonl 16 "princeton-nlp/SWE-bench_Lite" "test"
-```
-
-To clean-up all existing runtimes that you've already started, run:
-
-```bash
-ALLHANDS_API_KEY="YOUR-API-KEY" ./evaluation/utils/scripts/cleanup_remote_runtime.sh
-```
 
 ## SWT-Bench Evaluation
 

evaluation/benchmarks/swe_bench/SWE-rebench.md

@@ -0,0 +1,84 @@
+# SWE-rebench
+
+<p align="center">
+<a href="https://arxiv.org/abs/2505.20411">📃 Paper</a>
+•
+<a href="https://huggingface.co/datasets/nebius/SWE-rebench">🤗 HuggingFace</a>
+•
+<a href="https://swe-rebench.com/leaderboard">📊 Leaderboard</a>
+</p>
+
+SWE-rebench is a large-scale dataset for verifiable software engineering tasks.
+It comes in **two datasets**:
+
+* **[`nebius/SWE-rebench-leaderboard`](https://huggingface.co/datasets/nebius/SWE-rebench-leaderboard)** – updatable benchmark used for [leaderboard evaluation](https://swe-rebench.com/leaderboard).
+* **[`nebius/SWE-rebench`](https://huggingface.co/datasets/nebius/SWE-rebench)** – full dataset with **21,302 tasks**, suitable for training or large-scale offline evaluation.
+
+This document explains how to run OpenHands on SWE-rebench, using the leaderboard split as the main example.
+To run on the full dataset, simply replace the dataset name.
+
+
+## Setting Up
+
+Set up your development environment and configure your LLM provider by following the [SWE-bench README](README.md) in this directory.
+
+
+## Running Inference
+
+Use the existing SWE-bench inference script, changing the dataset to `nebius/SWE-rebench-leaderboard` and selecting the split (`test` for leaderboard submission):
+
+```bash
+./evaluation/benchmarks/swe_bench/scripts/run_infer.sh \
+    llm.your_llm HEAD CodeActAgent 30 50 1 nebius/SWE-rebench-leaderboard test
+```
+
+Arguments:
+
+* `llm.your_llm` – your model configuration key
+* `HEAD` – commit reference for reproducibility
+* `CodeActAgent` – agent type
+* `10` – number of examples to evaluate
+* `50` – maximum iterations per task (increase if needed)
+* `1` – number of workers
+* `nebius/SWE-rebench-leaderboard` – Hugging Face dataset name
+* `test` – dataset split
+
+**Tip:** To run on the **full 21k dataset**, replace `nebius/SWE-rebench-leaderboard` with `nebius/SWE-rebench`.
+
+
+## Evaluating Results
+
+After inference completes, evaluate using the [SWE-bench-fork evaluation harness](https://github.com/SWE-rebench/SWE-bench-fork).
+
+1. Convert the OpenHands output to SWE-bench evaluation format:
+
+```bash
+python evaluation/benchmarks/swe_bench/scripts/live/convert.py \
+  --output_jsonl path/to/evaluation/output.jsonl > preds.jsonl
+```
+
+2. Clone the SWE-bench-fork repo (https://github.com/SWE-rebench/SWE-bench-fork) and follow its README to install dependencies.
+
+
+3. Run the evaluation using the fork:
+
+```bash
+python -m swebench.harness.run_evaluation \
+    --dataset_name nebius/SWE-rebench-leaderboard \
+    --split test \
+    --predictions_path preds.jsonl \
+    --max_workers 10 \
+    --run_id openhands
+```
+
+
+## Citation
+
+```bibtex
+@article{badertdinov2025swerebench,
+  title={SWE-rebench: An Automated Pipeline for Task Collection and Decontaminated Evaluation of Software Engineering Agents},
+  author={Badertdinov, Ibragim and Golubev, Alexander and Nekrashevich, Maksim and Shevtsov, Anton and Karasik, Simon and Andriushchenko, Andrei and Trofimova, Maria and Litvintseva, Daria and Yangel, Boris},
+  journal={arXiv preprint arXiv:2505.20411},
+  year={2025}
+}
+```

evaluation/benchmarks/swe_bench/binary_patch_utils.py

@@ -1,11 +1,8 @@
-"""
-Utilities for handling binary files and patch generation in SWE-bench evaluation.
-"""
+"""Utilities for handling binary files and patch generation in SWE-bench evaluation."""
 
 
 def remove_binary_diffs(patch_text):
-    """
-    Remove binary file diffs from a git patch.
+    """Remove binary file diffs from a git patch.
 
     Args:
         patch_text (str): The git patch text
@@ -36,8 +33,7 @@ def remove_binary_diffs(patch_text):
 
 
 def remove_binary_files_from_git():
-    """
-    Generate a bash command to remove binary files from git staging.
+    """Generate a bash command to remove binary files from git staging.
 
     Returns:
         str: A bash command that removes binary files from git staging

evaluation/benchmarks/swe_bench/eval_infer.py

@@ -26,7 +26,7 @@ from evaluation.utils.shared import (
 from openhands.core.config import (
     LLMConfig,
     OpenHandsConfig,
-    get_parser,
+    get_evaluation_parser,
 )
 from openhands.core.logger import openhands_logger as logger
 from openhands.core.main import create_runtime
@@ -111,8 +111,7 @@ def process_instance(
     runtime_failure_count: int = 0,
     conditional_imports: ConditionalImports | None = None,
 ) -> EvalOutput:
-    """
-    Evaluate agent performance on a SWE-bench problem instance.
+    """Evaluate agent performance on a SWE-bench problem instance.
 
     Note that this signature differs from the expected input to `run_evaluation`. Use
     `functools.partial` to provide optional arguments before passing to the evaluation harness.
@@ -353,7 +352,7 @@ def process_instance(
 
 
 if __name__ == '__main__':
-    parser = get_parser()
+    parser = get_evaluation_parser()
     parser.add_argument(
         '--input-file',
         type=str,

evaluation/benchmarks/swe_bench/loc_eval/README.md

@@ -0,0 +1,45 @@
+# **Localization Evaluation for SWE-Bench**
+
+This folder implements localization evaluation at both file and function levels to complementing the assessment of agent inference on [SWE-Bench](https://www.swebench.com/).
+
+## **1. Environment Setup**
+- Python env: [Install python environment](../../../README.md#development-environment)
+- LLM config: [Configure LLM config](../../../README.md#configure-openhands-and-your-llm)
+
+## **2. Inference & Evaluation**
+- Inference and evaluation follow the original `run_infer.sh` and `run_eval.sh` implementation
+    - You may refer to instructions at [README.md](../README.md) for running inference and evaluation on SWE-Bench
+
+## **3. Localization Evaluation**
+- Localization evaluation computes two-level localization accuracy, while also considers task success as an additional metric for overall evaluation:
+    - **File Localization Accuracy:** Accuracy of correctly localizing the target file
+    - **Function Localization Accuracy:** Accuracy of correctly localizing the target function
+    - **Resolve Rate** (will be auto-skipped if missing): Success rate of whether tasks are successfully resolved
+    - **File Localization Efficiency:** Average number of iterations taken to successfully localize the target file
+    - **Function Localization Efficiency:** Average number of iterations taken to successfully localize the target file
+    - **Task success efficiency:** Average number of iterations taken to resolve the task
+    - **Resource efficiency:** the API expenditure of the agent running inference on SWE-Bench instances
+
+- Run localization evaluation
+    - Format:
+        ```bash
+        ./evaluation/benchmarks/swe_bench/scripts/eval_localization.sh [infer-dir] [split] [dataset] [max-infer-turn] [align-with-max]
+        ```
+        - `infer-dir`: inference directory containing inference outputs
+        - `split`: SWE-Bench dataset split to use
+        - `dataset`: SWE-Bench dataset name
+        - `max-infer-turn`: the maximum number of iterations the agent took to run inference
+        - `align-with-max`: whether to align failure indices (e.g., incorrect localization, unresolved tasks) with `max_iter`
+
+    - Example:
+        ```bash
+        # Example
+        ./evaluation/benchmarks/swe_bench/scripts/eval_localization.sh \
+            --infer-dir ./evaluation/evaluation_outputs/outputs/princeton-nlp__SWE-bench_Verified-test/CodeActAgent/gpt_4o_100_N \
+            --split test \
+            --dataset princeton-nlp/SWE-bench_Verified \
+            --max-infer-turn 100 \
+            --align-with-max true
+        ```
+
+- Localization evaluation results will be automatically saved to `[infer-dir]/loc_eval`

evaluation/benchmarks/swe_bench/loc_eval/loc_evaluator.py

@@ -0,0 +1,994 @@
+import argparse
+import ast
+import json
+import os
+import re
+
+import pandas as pd
+from datasets import load_dataset
+from tqdm import tqdm
+
+from evaluation.benchmarks.swe_bench.loc_eval.loc_utils import LocMeta
+from evaluation.benchmarks.swe_bench.run_infer import filter_dataset
+from evaluation.utils.shared import prepare_dataset
+from openhands.core.logger import openhands_logger as logger
+
+
+class LocEvaluator:
+    def __init__(self, args):
+        """Localization evaluation.
+
+        Args:
+            args: all main arguments
+        """
+        # Config
+        self.args = args
+        self.eval_dir = args.eval_dir
+        self.eval_task_success = self._check_if_to_eval_success()
+        self.sandbox_root = '/workspace'
+        self.agent_turn_num = -1
+        self.max_agent_turn = args.max_infer_turn
+        self.align_failed_with_max_iter = args.align_with_max
+
+        # Data
+        self.instance = None
+        self.trajectory = None
+
+        # Localization
+        self.localizer = LocMeta(args.dataset, args.split)
+        self.gold_loc = {'file': [], 'function': []}
+        self.agent_loc = {
+            'gold loc': {'file': [], 'function': []},
+            'agent loc': {'file': [], 'function': []},
+            'turn index': {'file': [], 'function': []},
+            'loc progress': {'file': [], 'function': []},
+        }
+
+        # Task success tracking
+        self.task_resolved = False
+
+        # Cost
+        self.cost_summary = {'total_cost': 0.0, 'avg_cost': 0.0, 'details': {}}
+
+        # Save
+        self.save_dir = os.path.join(args.save_dir, 'loc_eval_results')
+        self._init_dir(self.save_dir)
+        self.all_eval_results = {}
+        self.overall_eval = {}
+
+    def _init_config(self):
+        # Data
+        self.instance = None
+        self.gold_loc = {'file': [], 'function': []}
+        self.trajectory = None
+        self.agent_turn_num = -1
+
+        # Localization
+        self.agent_loc = {
+            'gold loc': {'file': [], 'function': []},
+            'agent loc': {'file': [], 'function': []},
+            'turn index': {'file': [], 'function': []},
+            'loc progress': {'file': [], 'function': []},
+        }
+
+        # Task success tracking
+        self.task_resolved = False
+
+    def _init_dir(self, directory_path):
+        """Check if a directory exists and create it if it doesn't.
+
+        Args:
+            directory_path (str): Path to the directory to check/create
+
+        Returns:
+            bool: True if directory already existed, False if it was created
+        """
+        if os.path.exists(directory_path):
+            if not os.path.isdir(directory_path):
+                raise NotADirectoryError(
+                    f'Path exists but is not a directory: {directory_path}'
+                )
+            return True
+        else:
+            os.makedirs(directory_path)
+            return False
+
+    def _check_if_to_eval_success(self):
+        """Check if post-evaluation outputs exist"""
+        if not os.path.isdir(self.eval_dir):
+            return False
+        else:
+            return True
+
+    def _compute_avg_over_all(self):
+        """Compute average loc evaluations over all instances"""
+        macro_la_file, micro_la_file = 0, 0
+        macro_la_func, micro_la_func = 0, 0
+        resolve_rate = 0
+        macro_avg_file_idx, macro_avg_func_idx = 0, 0
+        micro_avg_file_idx, micro_avg_func_idx = 0, 0
+        avg_resolve_idx = 0
+        total_instance_num = len(self.all_eval_results)
+
+        for instance_id in self.all_eval_results:
+            curr_eval_result = self.all_eval_results[instance_id]['final_eval']
+
+            # File
+            macro_la_file += curr_eval_result['localization']['loc_acc (%)'][
+                'la_file (%)'
+            ]['la_file_macro']
+            micro_la_file += curr_eval_result['localization']['loc_acc (%)'][
+                'la_file (%)'
+            ]['la_file_micro']
+            macro_avg_file_idx += curr_eval_result['localization']['turn_idx']['file'][
+                'macro'
+            ]
+            micro_avg_file_idx += curr_eval_result['localization']['turn_idx']['file'][
+                'micro'
+            ]
+
+            # Function
+            macro_la_func += curr_eval_result['localization']['loc_acc (%)'][
+                'la_func (%)'
+            ]['la_func_macro']
+            micro_la_func += curr_eval_result['localization']['loc_acc (%)'][
+                'la_func (%)'
+            ]['la_func_micro']
+            macro_avg_func_idx += curr_eval_result['localization']['turn_idx'][
+                'function'
+            ]['macro']
+            micro_avg_func_idx += curr_eval_result['localization']['turn_idx'][
+                'function'
+            ]['micro']
+
+            if self.eval_task_success:
+                if curr_eval_result['task_success']['resolved']:
+                    resolve_rate += 1
+                    avg_resolve_idx += curr_eval_result['task_success']['resolve_index']
+                else:
+                    avg_resolve_idx += self.max_agent_turn
+
+        # Average
+        macro_la_file = macro_la_file / total_instance_num
+        micro_la_file = micro_la_file / total_instance_num
+        macro_la_func = macro_la_func / total_instance_num
+        micro_la_func = micro_la_func / total_instance_num
+        macro_avg_file_idx = macro_avg_file_idx / total_instance_num
+        micro_avg_file_idx = micro_avg_file_idx / total_instance_num
+        macro_avg_func_idx = macro_avg_func_idx / total_instance_num
+        micro_avg_func_idx = micro_avg_func_idx / total_instance_num
+
+        if self.eval_task_success:
+            resolve_rate = resolve_rate / total_instance_num * 100
+            avg_resolve_idx = avg_resolve_idx / total_instance_num
+
+        # Cost metric
+        total_cost, avg_cost = 0.0, 0.0
+        for instance_key in self.cost_summary['details']:
+            total_cost += self.cost_summary['details'][instance_key]
+        avg_cost = total_cost / len(self.cost_summary['details'])
+        self.cost_summary['total_cost'] = total_cost
+        self.cost_summary['avg_cost'] = avg_cost
+
+        self.overall_eval = {
+            'la_file (%)': {'macro': macro_la_file, 'micro': micro_la_file},
+            'la_func (%)': {'macro': macro_la_func, 'micro': micro_la_func},
+            'resolve_rate (%)': resolve_rate if self.eval_task_success else None,
+            'loc_file_idx (turn idx)': {
+                'macro': macro_avg_file_idx,
+                'micro': micro_avg_file_idx,
+            },
+            'loc_func_idx (turn idx)': {
+                'macro': macro_avg_func_idx,
+                'micro': micro_avg_func_idx,
+            },
+            'resolve_idx (turn idx)': avg_resolve_idx
+            if self.eval_task_success
+            else None,
+            'max_turn_limit': self.max_agent_turn,
+            'total_instance_num': total_instance_num,
+            'cost_summary': self.cost_summary,
+        }
+        self._write_to_json(self.overall_eval, 'overall_eval.json')
+
+    def _save_to_eval_dicts(self, agent_trajectory: dict):
+        # Current instancec
+        self._write_to_json(
+            agent_trajectory, f'loc__instance_{self.instance.instance_id}.json'
+        )
+
+        # All instances
+        self.all_eval_results[self.instance.instance_id] = agent_trajectory
+        self._write_to_json(self.all_eval_results, 'all_loc_evals.json')
+
+        # Overall scores
+        self._compute_avg_over_all()
+
+    def _write_to_json(self, data, file_name):
+        """Writes the current object data to a JSON file.
+
+        Returns:
+            bool: True if writing was successful, False otherwise.
+        """
+        try:
+            output_dir = os.path.join(self.save_dir, 'loc_acc')
+            os.makedirs(output_dir, exist_ok=True)
+            filepath = os.path.join(output_dir, file_name)
+            with open(filepath, 'w') as f:
+                json.dump(data, f, indent=4)
+            return True
+        except Exception as e:
+            logger.error(f'Error writing to JSON: {str(e)}')
+            return False
+
+    def read_from_json(self, file_path):
+        """Reads data from a JSON file and loads it into the current object.
+
+        Returns:
+            dict: The loaded JSON data, or an empty dict if the file doesn't exist
+                or an error occurs.
+        """
+        try:
+            with open(file_path, 'r') as file:
+                data = json.load(file)
+                return data
+        except FileNotFoundError:
+            logger.warning(
+                f"Warning: File '{file_path}' not found. Returning an empty dictionary..."
+            )
+            return {}
+        except json.JSONDecodeError:
+            logger.error(
+                f"Error: File '{file_path}' contains invalid JSON. Returning an empty dictionary..."
+            )
+            return {}
+        except Exception as e:
+            logger.error(
+                f'Error reading from JSON: {str(e)}\nReturning an empty dictionary...'
+            )
+            return {}
+
+    def read_from_jsonl(self, file_path):
+        """Reads data from a JSON file and loads it into the current object.
+
+        Returns:
+            dict: The loaded JSON data, or an empty dict if the file doesn't exist
+                or an error occurs.
+        """
+        try:
+            with open(file_path, 'r') as file:
+                data = json.load(file)
+                return data
+        except FileNotFoundError:
+            logger.warning(
+                f"Warning: File '{file_path}' not found. Returning an empty dictionary..."
+            )
+            return {}
+        except json.JSONDecodeError:
+            logger.error(
+                f"Error: File '{file_path}' contains invalid JSON. Returning an empty dictionary..."
+            )
+            return {}
+        except Exception as e:
+            logger.error(
+                f'Error reading from JSON: {str(e)}\nReturning an empty dictionary...'
+            )
+            return {}
+
+    def _parse_agent_turn_num(self):
+        """Get the max agent turn for current instance"""
+        history_idx = 1
+        self.agent_turn_num = 0
+        while history_idx < len(self.trajectory) - 1:
+            if (
+                (self.trajectory[history_idx]['source'] == 'agent')
+                and ('action' in self.trajectory[history_idx].keys())
+                and (self.trajectory[history_idx]['action'] != 'system')
+            ):
+                self.agent_turn_num += 1
+            history_idx += 1
+
+    def _parse_string_to_dict(self, dict_string) -> dict:
+        """Convert a string representation of a dictionary to an actual dictionary.
+
+        Args:
+            dict_string (str): String representation of a dictionary
+
+        Returns:
+            dict or None: The parsed dictionary if successful, None if failed
+        """
+        if not isinstance(dict_string, str):
+            return None
+
+        dict_string = dict_string.strip()
+
+        # (1) Try JSON parsing
+        try:
+            return json.loads(dict_string)
+        except (json.JSONDecodeError, ValueError):
+            pass
+
+        # (1) Try ast parsing
+        try:
+            result = ast.literal_eval(dict_string)
+            if isinstance(result, dict):
+                return result
+            else:
+                return None
+        except (ValueError, SyntaxError):
+            pass
+
+        # If both methods fail, return None
+        return None
+
+    def _parse_value_from_args(self, argument_str: str, key: str) -> str:
+        """Parse a specific key's value from argument string.
+
+        Args:
+            argument_str (str): The argument string containing key-value pairs
+            key (str): The key to extract (e.g., "path", "new_str", "old_str")
+
+        Returns:
+            str: The extracted value, or empty string if not found
+        """
+        if not isinstance(argument_str, str) or not isinstance(key, str):
+            return ''
+
+        try:
+            json_pattern = rf'"{re.escape(key)}"\s*:\s*"((?:[^"\\]|\\.)*)"`'
+            match = re.search(json_pattern, argument_str, re.DOTALL)
+            if match:
+                value = match.group(1)
+                value = (
+                    value.replace('\\"', '"')
+                    .replace('\\n', '\n')
+                    .replace('\\t', '\t')
+                    .replace('\\\\', '\\')
+                )
+                return value
+
+            python_pattern = rf"'{re.escape(key)}'\s*:\s*'((?:[^'\\]|\\.)*)'"
+            match = re.search(python_pattern, argument_str, re.DOTALL)
+            if match:
+                value = match.group(1)
+                value = (
+                    value.replace("\\'", "'")
+                    .replace('\\n', '\n')
+                    .replace('\\t', '\t')
+                    .replace('\\\\', '\\')
+                )
+                return value
+
+            if key in argument_str:
+                parts = argument_str.split(f'"{key}"', 1)
+                if len(parts) == 1:
+                    parts = argument_str.split(f"'{key}'", 1)
+
+                if len(parts) > 1:
+                    remainder = parts[1].strip()
+
+                    for quote_char in ['"', "'"]:
+                        pattern = f'\\s*:\\s*{quote_char}((?:[^{quote_char}\\\\]|\\\\.)*)(?:{quote_char}|$)'
+                        match = re.search(pattern, remainder, re.DOTALL)
+                        if match:
+                            value = match.group(1)
+                            if quote_char == '"':
+                                value = (
+                                    value.replace('\\"', '"')
+                                    .replace('\\n', '\n')
+                                    .replace('\\t', '\t')
+                                    .replace('\\\\', '\\')
+                                )
+                            else:
+                                value = (
+                                    value.replace("\\'", "'")
+                                    .replace('\\n', '\n')
+                                    .replace('\\t', '\t')
+                                    .replace('\\\\', '\\')
+                                )
+                            return value
+
+                    if key == 'path':
+                        path_pattern = r'/[^\s,}"\']*'
+                        match = re.search(path_pattern, remainder)
+                        if match:
+                            return match.group(0)
+
+            return ''
+
+        except Exception:
+            return ''
+
+    def _parse_path_from_args(self, argument_str: str) -> str:
+        """Parse path from argument string.
+
+        Args:
+            argument_str (str): The argument string containing path information
+
+        Returns:
+            str: The extracted file path, or empty string if not found
+        """
+        return self._parse_value_from_args(argument_str, 'path')
+
+    def _parse_func_names_from_str(self, code_patch) -> list:
+        """Parse function names from the new_str code patch.
+
+        Args:
+            code_patch: Either a string (argument string) or already extracted new_str code
+
+        Returns:
+            list: List of function names found in the code patch
+        """
+        if not code_patch:
+            return []
+
+        try:
+            # Look for "def function_name(" patterns
+            # This pattern matches:
+            # - "def" followed by whitespace
+            # - function name (letters, numbers, underscores, also handle special methods like __len__)
+            # - opening parenthesis
+            func_pattern = r'\bdef\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\('
+
+            matches = re.findall(func_pattern, code_patch)
+
+            # Remove duplicates while preserving order
+            seen = set()
+            unique_funcs = []
+            for func_name in matches:
+                if func_name not in seen:
+                    seen.add(func_name)
+                    unique_funcs.append(func_name)
+
+            return unique_funcs
+
+        except Exception:
+            return []
+
+    def _parse_loc_from_history(self, action_history: dict) -> list:
+        """Parse function name and file path"""
+        if not action_history:
+            logger.error('No action history provided.')
+            raise
+
+        curr_turn_agent_loc = {}
+
+        if action_history['action'] != 'edit':
+            return curr_turn_agent_loc
+
+        agent_msg_list = action_history['tool_call_metadata']['model_response'][
+            'choices'
+        ]
+        agent_edit = {
+            'create': ['file_text'],
+            'str_replace': ['old_str', 'new_str'],
+        }
+
+        for cho in agent_msg_list:
+            for func_dict in cho['message']['tool_calls']:
+                edit_args = func_dict['function']['arguments']
+                edit_dict = self._parse_string_to_dict(edit_args)
+
+                if edit_dict:
+                    curr_command = edit_dict['command']
+                    agent_acts = agent_edit[curr_command]
+
+                    file_path = edit_dict.get('path', None)
+                    func_names = []
+
+                    for act in agent_acts:
+                        code_patch = edit_dict.get(act, None)
+                        func_names.extend(self._parse_func_names_from_str(code_patch))
+                    func_names = list(set(func_names))
+
+                else:
+                    for new_act in list(agent_edit.values()):
+                        if new_act in edit_args:
+                            agent_acts = new_act
+                            break
+
+                    file_path = self._parse_path_from_args(edit_args)
+                    func_names = []
+
+                    for act in agent_acts:
+                        code_patch = edit_args.split(agent_acts)[-1].strip()
+                        func_names.extend(self._parse_func_names_from_str(code_patch))
+                    func_names = list(set(func_names))
+
+                if file_path and len(file_path) > 0:
+                    if func_names:
+                        if file_path in curr_turn_agent_loc:
+                            curr_turn_agent_loc[file_path].extend(func_names)
+                        else:
+                            curr_turn_agent_loc[file_path] = func_names
+                    else:
+                        curr_turn_agent_loc[file_path] = []
+
+        return curr_turn_agent_loc
+
+    def _add_task_success_metric(self) -> bool:
+        """Task success evaluation result"""
+        self.task_resolved = False
+        report_pth = os.path.join(
+            self.eval_dir, self.instance.instance_id, 'report.json'
+        )
+        eval_report = self.read_from_json(report_pth)
+        if self.instance.instance_id in eval_report.keys():
+            self.task_resolved = eval_report[self.instance.instance_id]['resolved']
+
+        if self.task_resolved:
+            return {
+                'resolved': self.task_resolved,
+                'resolve_index': self.agent_turn_num,
+            }
+
+        if self.align_failed_with_max_iter:
+            return {
+                'resolved': self.task_resolved,
+                'resolve_index': self.max_agent_turn,
+            }
+        else:
+            return {
+                'resolved': self.task_resolved,
+                'resolve_index': self.agent_turn_num,
+            }
+
+    def eval_agent_trajectory(self):
+        """Evaluate agent's localization at current state"""
+        if not self.trajectory:
+            logger.warning(
+                f'Inference trajectory for current instance (instance ID: {self.instance.instance_id}) is None, skipping localization evaluation for current instance...'
+            )
+            return
+
+        # Process history
+        agent_trajectory = {'final_eval': {}, 'trajectory': {}}
+        turn_idx = 0
+        history_idx = 1
+
+        while history_idx < len(self.trajectory) - 2:
+            history_idx += 1
+            action_history = self.trajectory[history_idx]
+            observ_history = self.trajectory[history_idx + 1]
+
+            # Pass non-agent histories
+            if (action_history['source'] != 'agent') or (
+                'action' not in action_history.keys()
+            ):
+                continue
+
+            # Parse action
+            turn_idx += 1
+            curr_turn_agent_loc = self._parse_loc_from_history(action_history)
+
+            agent_trajectory['trajectory'][f'turn {turn_idx}'] = {
+                'loc_eval': None,
+                'loc': curr_turn_agent_loc,
+                'action': {
+                    'action': action_history['action'],
+                    'message': action_history['message'],
+                },
+                'observation': None,
+            }
+
+            if 'observation' in observ_history.keys():
+                agent_trajectory['trajectory'][f'turn {turn_idx}']['observation'] = {
+                    'observation': observ_history['observation'],
+                    'message': observ_history['message'],
+                }
+
+            # Loc eval
+            if len(curr_turn_agent_loc) > 0:
+                for file_key in curr_turn_agent_loc:
+                    for func_name in curr_turn_agent_loc[file_key]:
+                        # File loc
+                        if file_key in self.gold_loc['file']:
+                            if file_key not in self.agent_loc['agent loc']['file']:
+                                self.agent_loc['agent loc']['file'].append(file_key)
+                                self.agent_loc['turn index']['file'][
+                                    self.gold_loc['file'].index(file_key)
+                                ] = turn_idx
+                                self.agent_loc['loc progress']['file'][
+                                    self.gold_loc['file'].index(file_key)
+                                ] = True
+
+                        # Function loc
+                        new_agent_loc = {'file': file_key, 'function': func_name}
+                        if new_agent_loc in self.gold_loc['function']:
+                            if (
+                                new_agent_loc
+                                not in self.agent_loc['agent loc']['function']
+                            ):
+                                self.agent_loc['agent loc']['function'].append(
+                                    new_agent_loc
+                                )
+                                self.agent_loc['turn index']['function'][
+                                    self.gold_loc['function'].index(new_agent_loc)
+                                ] = turn_idx
+                                self.agent_loc['loc progress']['function'][
+                                    self.gold_loc['function'].index(new_agent_loc)
+                                ] = True
+
+            agent_trajectory['trajectory'][f'turn {turn_idx}']['loc_eval'] = (
+                self.agent_loc
+            )
+
+        # Task success
+        agent_trajectory['final_eval'] = {
+            'total turn': self.agent_turn_num,
+            'max turn': self.max_agent_turn,
+            'localization': {
+                'loc_acc (%)': {
+                    'la_file (%)': {
+                        'la_file_micro': sum(self.agent_loc['loc progress']['file'])
+                        / len(self.agent_loc['loc progress']['file'])
+                        * 100,
+                        'la_file_macro': 100.0
+                        if sum(self.agent_loc['loc progress']['file']) > 0
+                        else 0.0,
+                    },
+                    'la_func (%)': {
+                        'la_func_micro': sum(self.agent_loc['loc progress']['function'])
+                        / len(self.agent_loc['loc progress']['function'])
+                        * 100,
+                        'la_func_macro': 100.0
+                        if sum(self.agent_loc['loc progress']['function']) > 0
+                        else 0.0,
+                    },
+                },
+                'turn_idx': {
+                    'file': {
+                        'micro': max(self.agent_loc['turn index']['file']),
+                        'macro': min(self.agent_loc['turn index']['file']),
+                    },
+                    'function': {
+                        'micro': max(self.agent_loc['turn index']['function']),
+                        'macro': min(self.agent_loc['turn index']['function']),
+                    },
+                },
+                'details': {
+                    'loc_file': self.agent_loc['loc progress']['file'],
+                    'loc_func': self.agent_loc['loc progress']['function'],
+                },
+            },
+            'task_success': None,
+        }
+
+        # Task success
+        if self.eval_task_success:
+            agent_trajectory['final_eval']['task_success'] = (
+                self._add_task_success_metric()
+            )
+
+        # Align loc with success
+        if self.task_resolved:
+            if agent_trajectory['final_eval']['localization']['loc_acc (%)'] != {
+                'la_file (%)': {'la_file_micro': 100.0, 'la_file_macro': 100.0},
+                'la_func (%)': {'la_func_micro': 100.0, 'la_func_macro': 100.0},
+            }:
+                agent_trajectory['final_eval']['localization']['loc_acc (%)'] = {
+                    'la_file (%)': {'la_file_micro': 100.0, 'la_file_macro': 100.0},
+                    'la_func (%)': {'la_func_micro': 100.0, 'la_func_macro': 100.0},
+                }
+                agent_trajectory['final_eval']['localization']['details'] = {
+                    'loc_file': [
+                        True for i in range(len(self.agent_loc['loc progress']['file']))
+                    ],
+                    'loc_func': [
+                        True
+                        for i in range(len(self.agent_loc['loc progress']['function']))
+                    ],
+                }
+
+            if self.align_failed_with_max_iter:
+                for level1 in agent_trajectory['final_eval']['localization'][
+                    'turn_idx'
+                ]:
+                    for level2 in agent_trajectory['final_eval']['localization'][
+                        'turn_idx'
+                    ][level1]:
+                        if (
+                            agent_trajectory['final_eval']['localization']['turn_idx'][
+                                level1
+                            ][level2]
+                            > self.agent_turn_num
+                        ):
+                            agent_trajectory['final_eval']['localization']['turn_idx'][
+                                level1
+                            ][level2] = self.agent_turn_num
+
+        # Save
+        self._save_to_eval_dicts(agent_trajectory)
+
+    def _get_instance_gt_loc(self):
+        """Get ground-truth localization for current instance"""
+        gt_localization = self.localizer.parse_instance_loc(self.instance)
+
+        # Convert to dict
+        gt_loc_dict = gt_localization['patch'].to_dict()
+        assert gt_loc_dict['instance_id'] == self.instance.instance_id
+        self.gold_loc = {
+            'gt_loc_dict': gt_loc_dict['functions'],
+            'file': [],
+            'function': [],
+        }
+
+        for file_key in gt_loc_dict['functions']:
+            if len(gt_loc_dict['functions'][file_key]) == 0:
+                continue
+
+            # File
+            if file_key not in self.gold_loc['file']:
+                self.gold_loc['file'].append(f'{self.sandbox_root}/{file_key}')
+
+            # Function
+            for func_name in gt_loc_dict['functions'][file_key]:
+                new_gt = {
+                    'file': f'{self.sandbox_root}/{file_key}',
+                    'function': func_name,
+                }
+                self.gold_loc['function'].append(new_gt)
+
+        # Init agent loc accordingly
+        init_turn = (
+            self.max_agent_turn
+            if self.align_failed_with_max_iter
+            else self.agent_turn_num
+        )
+        self.agent_loc['gold loc'] = {
+            'file': self.gold_loc['file'],
+            'function': self.gold_loc['function'],
+        }
+        self.agent_loc['turn index']['file'] = [
+            init_turn for i in range(len(self.gold_loc['file']))
+        ]
+        self.agent_loc['turn index']['function'] = [
+            init_turn for i in range(len(self.gold_loc['function']))
+        ]
+        self.agent_loc['loc progress']['file'] = [
+            False for i in range(len(self.gold_loc['file']))
+        ]
+        self.agent_loc['loc progress']['function'] = [
+            False for i in range(len(self.gold_loc['function']))
+        ]
+
+    def instance_loc_eval(
+        self,
+        instance: pd.Series = None,
+        repo_root: str = None,
+        trajectory: list = None,
+        infer_cost: dict = None,
+    ):
+        if instance is None:
+            logger.error(
+                'No instance provided. Skipping current localization evaluation...'
+            )
+        if trajectory is None:
+            logger.error(
+                f'No inference trajectory provided for current instance with ID: {instance.instance_id}'
+            )
+        if infer_cost is None:
+            logger.error(
+                f'No inference accumulated cost for current instance with ID: {instance.instance_id}'
+            )
+
+        # Init
+        self._init_config()
+        self.cost_summary['details'][instance.instance_id] = infer_cost
+
+        # Update current instance
+        self.instance = instance
+        self.trajectory = trajectory
+        self.sandbox_root = repo_root
+
+        # Max turn
+        self._parse_agent_turn_num()
+
+        # GT loc
+        self._get_instance_gt_loc()
+
+        # Loc evaluation
+        self.eval_agent_trajectory()
+
+
+def swe_data_loader(args):
+    """Loading SWE-Bench data.
+
+    Args:
+        args: Main arguments.
+    """
+    dataset = load_dataset(args.dataset, split=args.split)
+    swe_bench_tests = filter_dataset(dataset.to_pandas(), 'instance_id')
+    logger.info(
+        f'Loaded dataset {args.dataset} with split {args.split}: {len(swe_bench_tests)} tasks'
+    )
+    if 'SWE-Gym' in args.dataset:
+        with open(
+            os.path.join(
+                os.path.dirname(os.path.abspath(__file__)),
+                'split',
+                'swegym_verified_instances.json',
+            ),
+            'r',
+        ) as f:
+            swegym_verified_instances = json.load(f)
+            swe_bench_tests = swe_bench_tests[
+                swe_bench_tests['instance_id'].isin(swegym_verified_instances)
+            ]
+        logger.info(
+            f'{len(swe_bench_tests)} tasks left after filtering for SWE-Gym verified instances'
+        )
+
+    instances = prepare_dataset(swe_bench_tests, args.swe_output_file, -1)
+    return instances
+
+
+def infer_data_loader(args):
+    """Load instance IDs.
+
+    Args:
+        args: Main arguments.
+
+    Returns:
+        list: A list of instance IDs (strings) extracted from JSON filenames
+              in the histories directory.
+
+    Raises:
+        FileNotFoundError: If the histories directory doesn't exist.
+        AttributeError: If args doesn't have a 'infer_dir' attribute.
+    """
+    infer_output_filepath = os.path.join(args.infer_dir, 'output.jsonl')
+
+    infer_outputs = []
+    with open(infer_output_filepath, 'r') as file:
+        for line_num, line in enumerate(file, 1):
+            line = line.strip()
+            if line:
+                try:
+                    json_obj = json.loads(line)
+                    infer_outputs.append(json_obj)
+                except json.JSONDecodeError as e:
+                    logger.error(
+                        f"Error parsing JSON on line {line_num} in '{infer_output_filepath}': {str(e)}"
+                    )
+                    continue
+
+    return infer_outputs
+
+
+def infer_cost_calculator(args):
+    """Calculate total and average costs from metric JSON files with detailed output.
+
+    Args:
+        args: Main arguments.
+
+    Returns:
+        dict: A dictionary containing:
+              - 'total_cost': Sum of all accumulated costs
+              - 'average_cost': Average cost per JSON file
+              - 'file_count': Number of JSON files processed
+              - 'individual_costs': List of individual costs (optional)
+    """
+    metrics_dir = os.path.join(args.infer_dir, 'metrics')
+
+    if not os.path.exists(metrics_dir):
+        raise FileNotFoundError(f'Metrics directory not found: {metrics_dir}')
+
+    individual_costs = []
+
+    for filename in os.listdir(metrics_dir):
+        if filename.endswith('.json'):
+            file_path = os.path.join(metrics_dir, filename)
+
+            try:
+                with open(file_path, 'r', encoding='utf-8') as file:
+                    metric_data = json.load(file)
+
+                if 'accumulated_cost' not in metric_data:
+                    raise KeyError(f"'accumulated_cost' not found in {filename}")
+
+                cost = float(metric_data['accumulated_cost'])
+                individual_costs.append(cost)
+
+            except (json.JSONDecodeError, ValueError, TypeError, IOError) as e:
+                logger.warning(f'Warning: Error processing {filename}: {e}')
+                continue
+
+    if not individual_costs:
+        raise ValueError('No valid JSON files found in the metrics directory')
+
+    total_cost = sum(individual_costs)
+    average_cost = total_cost / len(individual_costs)
+
+    return {
+        'total_cost': total_cost,
+        'average_cost': average_cost,
+        'file_count': len(individual_costs),
+        'individual_costs': individual_costs,
+    }
+
+
+if __name__ == '__main__':
+    """Main function for localization evaluation"""
+    parser = argparse.ArgumentParser(
+        description='Localization evaluation on SWE-Bench.'
+    )
+
+    parser.add_argument(
+        '--infer-dir',
+        type=str,
+        default=None,
+        help='Directory containing model inference outputs',
+    )
+    parser.add_argument(
+        '--dataset', type=str, default=None, help='SWE-Bench dataset version'
+    )
+    parser.add_argument(
+        '--split', type=str, default=None, help='SWE-Bench dataset split selection'
+    )
+    parser.add_argument(
+        '--max-infer-turn',
+        type=int,
+        default=None,
+        help='Max number of turns allowed for coding agent.',
+    )
+    parser.add_argument(
+        '--align-with-max',
+        type=str,
+        choices=['true', 'false'],
+        default='true',
+        help='Whether to align failed instances with max iteration count (true/false)',
+    )
+
+    args = parser.parse_args()
+
+    # Convert args.align_with_max str to bool
+    args.align_with_max = args.align_with_max.lower() == 'true'
+
+    # Eval infer and loc
+    args.save_dir = f'{args.infer_dir}/loc_eval'
+    os.makedirs(args.save_dir, exist_ok=True)
+    args.eval_dir = f'{args.infer_dir}/eval_outputs'
+    if not os.path.isdir(args.eval_dir):
+        args.eval_dir = None
+
+    # SWE-Bench
+    args.swe_output_file = os.path.join(args.save_dir, 'swe_dataset.json')
+
+    # Load swebench data
+    swe_instances = swe_data_loader(args)
+
+    # Load inference data
+    infer_outputs = infer_data_loader(args)
+
+    # Loc eval
+    processed_instances = []
+    loc_eval_results = {}
+    loc_evaluator = LocEvaluator(args)
+
+    for infer_idx, infer_instance in tqdm(
+        enumerate(infer_outputs), total=len(infer_outputs), desc='Processing instances'
+    ):
+        instance_id = infer_instance['instance_id']
+        swe_instance = swe_instances.query(f"instance_id == '{instance_id}'").iloc[0]
+        assert instance_id == swe_instance.instance_id
+
+        processed_instances.append(instance_id)
+        upload_instruction = infer_instance['instruction']
+        repo_root = (
+            upload_instruction.split('<uploaded_files>')[1]
+            .split('</uploaded_files>')[0]
+            .strip()
+        )
+        curr_trajectory = infer_instance['history']
+        curr_cost = infer_instance['metrics']['accumulated_cost']
+        loc_evaluator.instance_loc_eval(
+            swe_instance, repo_root, curr_trajectory, curr_cost
+        )
+
+    logger.info(
+        f'\n[Inference Data Summary]'
+        f'\n{" " * 4} - Total cost:   $ {loc_evaluator.cost_summary["total_cost"]}'
+        f'\n{" " * 4} - Average cost: $ {loc_evaluator.cost_summary["avg_cost"]}'
+        f'\n{" " * 4} - Number of Instances: {len(processed_instances)}'
+    )

evaluation/benchmarks/swe_bench/prompts/swe_claude.j2

@@ -1,65 +0,0 @@
-<uploaded_files>
-/workspace/{{ workspace_dir_name }}
-</uploaded_files>
-
-I've uploaded a python code repository in the directory {{ workspace_dir_name }}. Consider the following issue description:
-
-<issue_description>
-{{ instance.problem_statement }}
-</issue_description>
-
-Can you help me implement the necessary changes to the repository so that the requirements specified in the <issue_description> are met?
-I've already taken care of all changes to any of the test files described in the <issue_description>. This means you DON'T have to modify the testing logic or any of the tests in any way!
-Also the development Python environment is already set up for you (i.e., all dependencies already installed), so you don't need to install other packages.
-Your task is to make the minimal changes to non-test files in the /workspace/{{ workspace_dir_name }} directory to ensure the <issue_description> is satisfied.
-
-Follow these phases to resolve the issue:
-
-Phase 1. READING: read the problem and reword it in clearer terms
-   1.1 If there are code or config snippets. Express in words any best practices or conventions in them.
-   1.2 Hightlight message errors, method names, variables, file names, stack traces, and technical details.
-   1.3 Explain the problem in clear terms.
-   1.4 Enumerate the steps to reproduce the problem.
-   1.5 Hightlight any best practices to take into account when testing and fixing the issue
-
-Phase 2. RUNNING: install and run the tests on the repository
-   2.1 Follow the readme
-   2.2 Install the environment and anything needed
-   2.2 Iterate and figure out how to run the tests
-
-Phase 3. EXPLORATION: find the files that are related to the problem and possible solutions
-   3.1 Use `grep` to search for relevant methods, classes, keywords and error messages.
-   3.2 Identify all files related to the problem statement.
-   3.3 Propose the methods and files to fix the issue and explain why.
-   3.4 From the possible file locations, select the most likely location to fix the issue.
-
-Phase 4. TEST CREATION: before implementing any fix, create a script to reproduce and verify the issue.
-   4.1 Look at existing test files in the repository to understand the test format/structure.
-   4.2 Create a minimal reproduction script that reproduces the located issue.
-   4.3 Run the reproduction script to confirm you are reproducing the issue.
-   4.4 Adjust the reproduction script as necessary.
-
-Phase 5. FIX ANALYSIS: state clearly the problem and how to fix it
-   5.1 State clearly what the problem is.
-   5.2 State clearly where the problem is located.
-   5.3 State clearly how the test reproduces the issue.
-   5.4 State clearly the best practices to take into account in the fix.
-   5.5 State clearly how to fix the problem.
-
-Phase 6. FIX IMPLEMENTATION: Edit the source code to implement your chosen solution.
-   6.1 Make minimal, focused changes to fix the issue.
-
-Phase 7. VERIFICATION: Test your implementation thoroughly.
-   7.1 Run your reproduction script to verify the fix works.
-   7.2 Add edge cases to your test script to ensure comprehensive coverage.
-   7.3 Run existing tests related to the modified code to ensure you haven't broken anything.
-
-8. FINAL REVIEW: Carefully re-read the problem description and compare your changes with the base commit {{ instance.base_commit }}.
-   8.1 Ensure you've fully addressed all requirements.
-   8.2 Run any tests in the repository related to:
-     8.2.1 The issue you are fixing
-     8.2.2 The files you modified
-     8.2.3 The functions you changed
-   8.3 If any tests fail, revise your implementation until all tests pass
-
-Be thorough in your exploration, testing, and reasoning. It's fine if your thinking process is lengthy - quality and completeness are more important than brevity.

evaluation/benchmarks/swe_bench/prompts/swe_gemini.j2

@@ -1,45 +0,0 @@
-# Task: Fix Issue in Python Repository
-
-## Repository Context
-You are provided with a Python code repository that contains an issue requiring your attention. The repository is located in a sandboxed environment, and you have access to the codebase to implement the necessary changes.
-The code repository is located at: `/workspace/{{ workspace_dir_name }}`
-(This path is provided for context; use file system tools to confirm paths before access).
-
-## Goal
-Your goal is to fix the issue described in the **Issue Description** section below. Implement the necessary changes to **non-test files only** within the repository, ensuring that **all relevant tests pass** after your changes.
-
-## Key Requirements & Constraints
-
-1.  **Understand the problem** very well: it is a bug report, and you know humans don't always write good descriptions. Explore the codebase to understand the related code and the problem in depth. It is possible that the solution needs to be a bit more extensive than just the stated text. Don't exagerate though: don't do unrelated refactoring, but also don't interpret the description too strictly.
-2.  **Focus on the issues:** Implement the fix focusing on non-test files related to the issue.
-2.  **Environment Ready:** The Python environment is pre-configured with all dependencies. Do not install packages.
-3.  **Mandatory Testing Procedure:**
-    *   **Create Test to Reproduce the Issue:** *Before* implementing any fix, you MUST create a *new test* (separate from existing tests) that specifically reproduces the issue.
-            * Take existing tests as example to understand the testing format/structure.
-            * Enhance this test with edge cases.
-            * Run this test to confirm reproduction.
-    *   **Verify Fix:** After implementing the fix, run your test again to verify the issue is resolved.
-    *   **Identify ALL Relevant Tests:** You MUST perform a **dedicated search and analysis** to identify **all** existing unit tests potentially affected by your changes. This includes:
-        *   Tests in the same module/directory as the changed files (e.g., `tests/` subdirectories).
-        *   Tests explicitly importing or using the modified code/classes/functions.
-        *   Tests mentioned in the issue description or related documentation.
-        *   Tests covering functionalities that *depend on* the modified code (analyze callers/dependencies if necessary).
-        **If you cannot confidently identify a specific subset, you MUST identify and plan to run the entire test suite for the modified application or module(s). State your identified test scope clearly.**
-    *   **Run Identified Relevant Tests:** You MUST execute the **complete set** of relevant existing unit tests you identified in the previous step. Ensure you are running the *correct and comprehensive set* of tests. You MUST NOT modify these existing tests.
-    *   **Final Check & Verification:** Before finishing, ensure **all** identified relevant existing tests pass. **Explicitly confirm that you have considered potential omissions in your test selection and believe the executed tests comprehensively cover the impact of your changes.** Failing to identify and run the *complete* relevant set constitutes a failure. If any identified tests fail, revise your fix. Passing all relevant tests is the primary measure of success.
-4.  **Defensive Programming:** Actively practice defensive programming: anticipate and handle potential edge cases, unexpected inputs, and different ways the affected code might be called **to ensure the fix works reliably and allows relevant tests to pass.** Analyze the potential impact on other parts of the codebase.
-5.  **Final Review:** Compare your solution against the original issue and the base commit ({{ instance.base_commit }}) to ensure completeness and test passage.
-
-## General Workflow Guidance
-
-*   Prioritize understanding the problem, exploring the code, planning your fix, implementing it carefully using the required diff format, and **thoroughly testing** according to the **Mandatory Testing Procedure**.
-*   Consider trade-offs between different solutions. The goal is a **robust change that makes the relevant tests pass.** Quality, correctness, and reliability are key.
-*   Actively practice defensive programming: anticipate and handle potential edge cases, unexpected inputs, and different ways the affected code might be called **to ensure the fix works reliably and allows relevant tests to pass.** Analyze the potential impact on other parts of the codebase.
-
-*   IMPORTANT: Your solution will be tested by additional hidden tests, so do not assume the task is complete just because visible tests pass! Refine the solution until you are confident that it is robust and comprehensive according to the **Defensive Programming** requirement.
-
-## Final Note
-Be thorough in your exploration, testing, and reasoning. It's fine if your thinking process is lengthy - quality and completeness are more important than brevity.
-
-## Issue Description
-{{ instance.problem_statement }}

evaluation/benchmarks/swe_bench/run_infer.py

@@ -28,6 +28,7 @@ from evaluation.utils.shared import (
     EvalMetadata,
     EvalOutput,
     assert_and_raise,
+    check_maximum_retries_exceeded,
     codeact_user_response,
     get_default_sandbox_config_for_eval,
     get_metrics,
@@ -42,8 +43,8 @@ from openhands.controller.state.state import State
 from openhands.core.config import (
     AgentConfig,
     OpenHandsConfig,
+    get_evaluation_parser,
     get_llm_config_arg,
-    get_parser,
 )
 from openhands.core.config.condenser_config import NoOpCondenserConfig
 from openhands.core.config.utils import get_condenser_config_arg
@@ -79,6 +80,8 @@ def set_dataset_type(dataset_name: str) -> str:
         DATASET_TYPE = 'SWE-Gym'
     elif 'swe-bench-live' in name_lower:
         DATASET_TYPE = 'SWE-bench-Live'
+    elif 'swe-rebench' in name_lower:
+        DATASET_TYPE = 'SWE-rebench'
     elif 'multimodal' in name_lower:
         DATASET_TYPE = 'Multimodal'
     else:
@@ -108,11 +111,7 @@ def get_instruction(instance: pd.Series, metadata: EvalMetadata) -> MessageActio
     if mode.startswith('swt'):
         template_name = 'swt.j2'
     elif mode == 'swe':
-        if 'claude' in llm_model:
-            template_name = 'swe_claude.j2'
-        elif 'gemini' in llm_model:
-            template_name = 'swe_gemini.j2'
-        elif 'gpt-4.1' in llm_model:
+        if 'gpt-4.1' in llm_model:
             template_name = 'swe_gpt4.j2'
         else:
             template_name = (
@@ -181,6 +180,8 @@ def get_instance_docker_image(
             docker_image_prefix = 'docker.io/starryzhang/'
         elif DATASET_TYPE == 'SWE-bench':
             docker_image_prefix = 'docker.io/swebench/'
+        elif DATASET_TYPE == 'SWE-rebench':
+            docker_image_prefix = 'docker.io/swerebench/'
         repo, name = instance_id.split('__')
         image_name = f'{docker_image_prefix.rstrip("/")}/sweb.eval.x86_64.{repo}_1776_{name}:latest'.lower()
         logger.debug(f'Using official SWE-Bench image: {image_name}')
@@ -227,6 +228,7 @@ def get_config(
         default_agent=metadata.agent_class,
         run_as_openhands=False,
         max_iterations=metadata.max_iterations,
+        enable_browser=RUN_WITH_BROWSING,
         runtime=os.environ.get('RUNTIME', 'docker'),
         sandbox=sandbox_config,
         # do not mount workspace
@@ -320,6 +322,8 @@ def initialize_runtime(
         # inject the instance swe entry
         if DATASET_TYPE == 'SWE-bench-Live':
             entry_script_path = 'instance_swe_entry_live.sh'
+        elif DATASET_TYPE == 'SWE-rebench':
+            entry_script_path = 'instance_swe_entry_rebench.sh'
         else:
             entry_script_path = 'instance_swe_entry.sh'
         runtime.copy_to(
@@ -732,7 +736,7 @@ def filter_dataset(dataset: pd.DataFrame, filter_column: str) -> pd.DataFrame:
 
 
 if __name__ == '__main__':
-    parser = get_parser()
+    parser = get_evaluation_parser()
     parser.add_argument(
         '--dataset',
         type=str,
@@ -970,3 +974,5 @@ if __name__ == '__main__':
         logger.info(
             f'Done! Total {len(added_instance_ids)} instances added to {output_file}'
         )
+        # Check if any instances reached maximum retries
+        check_maximum_retries_exceeded(metadata.eval_output_dir)

evaluation/benchmarks/swe_bench/run_infer_interact.py

@@ -28,8 +28,8 @@ from evaluation.utils.shared import (
 )
 from openhands.controller.state.state import State
 from openhands.core.config import (
+    get_evaluation_parser,
     get_llm_config_arg,
-    get_parser,
 )
 from openhands.core.config.condenser_config import NoOpCondenserConfig
 from openhands.core.config.utils import get_condenser_config_arg
@@ -201,7 +201,7 @@ def process_instance(
 
 
 if __name__ == '__main__':
-    parser = get_parser()
+    parser = get_evaluation_parser()
     parser.add_argument(
         '--dataset',
         type=str,

evaluation/benchmarks/swe_bench/run_localize.py

@@ -31,8 +31,8 @@ from openhands.controller.state.state import State
 from openhands.core.config import (
     AgentConfig,
     OpenHandsConfig,
+    get_evaluation_parser,
     get_llm_config_arg,
-    get_parser,
 )
 from openhands.core.logger import openhands_logger as logger
 from openhands.core.main import create_runtime, run_controller
@@ -203,6 +203,7 @@ def get_config(
         default_agent=metadata.agent_class,
         run_as_openhands=False,
         max_iterations=metadata.max_iterations,
+        enable_browser=RUN_WITH_BROWSING,
         runtime=os.environ.get('RUNTIME', 'docker'),
         sandbox=sandbox_config,
         # do not mount workspace
@@ -643,7 +644,7 @@ SWEGYM_EXCLUDE_IDS = [
 ]
 
 if __name__ == '__main__':
-    parser = get_parser()
+    parser = get_evaluation_parser()
     parser.add_argument(
         '--dataset',
         type=str,

evaluation/benchmarks/swe_bench/scripts/eval/verify_costs.py

@@ -6,8 +6,7 @@ from openhands.core.logger import openhands_logger as logger
 
 
 def verify_instance_costs(row: pd.Series) -> float:
-    """
-    Verifies that the accumulated_cost matches the sum of individual costs in metrics.
+    """Verifies that the accumulated_cost matches the sum of individual costs in metrics.
     Also checks for duplicate consecutive costs which might indicate buggy counting.
     If the consecutive costs are identical, the file is affected by this bug:
     https://github.com/All-Hands-AI/OpenHands/issues/5383

evaluation/benchmarks/swe_bench/scripts/eval_infer_remote.sh

@@ -1,46 +0,0 @@
-#!/usr/bin/env bash
-set -eo pipefail
-
-INPUT_FILE=$1
-NUM_WORKERS=$2
-DATASET=$3
-SPLIT=$4
-
-if [ -z "$INPUT_FILE" ]; then
-  echo "INPUT_FILE not specified (should be a path to a jsonl file)"
-  exit 1
-fi
-
-if [ -z "$DATASET" ]; then
-  echo "DATASET not specified, use default princeton-nlp/SWE-bench_Lite"
-  DATASET="princeton-nlp/SWE-bench_Lite"
-fi
-
-if [ -z "$SPLIT" ]; then
-  echo "SPLIT not specified, use default test"
-  SPLIT="test"
-fi
-
-if [ -z "$NUM_WORKERS" ]; then
-  echo "NUM_WORKERS not specified, use default 1"
-  NUM_WORKERS=1
-fi
-
-echo "... Evaluating on $INPUT_FILE ..."
-
-COMMAND="poetry run python evaluation/benchmarks/swe_bench/eval_infer.py \
-  --eval-num-workers $NUM_WORKERS \
-  --input-file $INPUT_FILE \
-  --dataset $DATASET \
-  --split $SPLIT"
-
-if [ -n "$EVAL_LIMIT" ]; then
-  echo "EVAL_LIMIT: $EVAL_LIMIT"
-  COMMAND="$COMMAND --eval-n-limit $EVAL_LIMIT"
-fi
-
-# Run the command
-eval $COMMAND
-
-# update the output with evaluation results
-poetry run python evaluation/benchmarks/swe_bench/scripts/eval/update_output_with_eval.py $INPUT_FILE

evaluation/benchmarks/swe_bench/scripts/eval_localization.sh

@@ -0,0 +1,227 @@
+#!/usr/bin/env bash
+set -eo pipefail
+source "evaluation/utils/version_control.sh"
+
+# Function to display usage information
+usage() {
+    echo "Usage: $0 [OPTIONS]"
+    echo "Options:"
+    echo "  --infer-dir DIR         Directory containing model inference outputs"
+    echo "  --split SPLIT           SWE-Bench dataset split selection"
+    echo "  --dataset DATASET       Dataset name"
+    echo "  --max-infer-turn NUM    Max number of turns for coding agent"
+    echo "  --align-with-max BOOL   Align failed instance indices with max iteration (true/false)"
+    echo "  -h, --help              Display this help message"
+    echo ""
+    echo "Example:"
+    echo "  $0 --infer-dir ./inference_outputs --split test --align-with-max false"
+}
+
+# Check if no arguments were provided
+if [ $# -eq 0 ]; then
+    usage
+    exit 1
+fi
+
+# Parse command line arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --infer-dir)
+            INFER_DIR="$2"
+            shift 2
+            ;;
+        --split)
+            SPLIT="$2"
+            shift 2
+            ;;
+        --dataset)
+            DATASET="$2"
+            shift 2
+            ;;
+        --max-infer-turn)
+            MAX_TURN="$2"
+            shift 2
+            ;;
+        --align-with-max)
+            ALIGN_WITH_MAX="$2"
+            shift 2
+            ;;
+        -h|--help)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1"
+            usage
+            exit 1
+            ;;
+    esac
+done
+
+# Check for required arguments (only INFER_DIR is required)
+if [ -z "$INFER_DIR" ]; then
+    echo "Error: Missing required arguments (--infer-dir is required)"
+    usage
+    exit 1
+fi
+
+# Set defaults for optional arguments if not provided
+if [ -z "$SPLIT" ]; then
+    SPLIT="test"
+    echo "Split not specified, using default: $SPLIT"
+fi
+
+if [ -z "$DATASET" ]; then
+    DATASET="princeton-nlp/SWE-bench_Verified"
+    echo "Dataset not specified, using default: $DATASET"
+fi
+
+if [ -z "$MAX_TURN" ]; then
+    MAX_TURN=20
+    echo "Max inference turn not specified, using default: $MAX_TURN"
+fi
+
+if [ -z "$ALIGN_WITH_MAX" ]; then
+    ALIGN_WITH_MAX="true"
+    echo "Align with max not specified, using default: $ALIGN_WITH_MAX"
+fi
+
+# Validate align-with-max value
+if [ "$ALIGN_WITH_MAX" != "true" ] && [ "$ALIGN_WITH_MAX" != "false" ]; then
+    print_error "Invalid value for --align-with-max: $ALIGN_WITH_MAX. Must be 'true' or 'false'"
+    exit 1
+fi
+
+# Color codes for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Function to print colored output
+print_status() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+print_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}[WARNING]${NC} $1"
+}
+
+print_header() {
+    echo -e "${BLUE}[TASK]${NC} $1"
+}
+
+# Check if Python is available
+print_header "Checking Python installation..."
+if ! command -v python3 &> /dev/null; then
+    if ! command -v python &> /dev/null; then
+        print_error "Python is not installed or not in PATH"
+        exit 1
+    else
+        PYTHON_CMD="python"
+        print_status "Using python command"
+    fi
+else
+    PYTHON_CMD="python3"
+    print_status "Using python3 command"
+fi
+
+# Check if the Python script exists
+SCRIPT_NAME="./evaluation/benchmarks/swe_bench/loc_eval/loc_evaluator.py"
+if [ ! -f "$SCRIPT_NAME" ]; then
+    print_error "Python script '$SCRIPT_NAME' not found in current directory"
+    print_warning "Make sure the Python script is in the same directory as this bash script"
+    exit 1
+fi
+
+# Check if required directories exist
+print_header "Validating directories..."
+if [ ! -d "$INFER_DIR" ]; then
+    print_error "Inference directory not found: $INFER_DIR"
+    exit 1
+fi
+
+# Evaluation outputs
+EVAL_DIR="$INFER_DIR/eval_outputs"
+
+# Display configuration
+print_header "Starting Localization Evaluation with the following configuration:"
+echo "  Inference Directory:  $INFER_DIR"
+if [ -d "$EVAL_DIR" ]; then
+    echo "  Evaluation Directory:  $EVAL_DIR"
+else
+    echo "  Evaluation Directory:  None (evaluation outputs doesn't exist)"
+fi
+echo "  Output Directory:      $INFER_DIR/loc_eval"
+echo "  Split:                 $SPLIT"
+echo "  Dataset:               $DATASET"
+echo "  Max Turns:             $MAX_TURN"
+echo "  Align with Max:        $ALIGN_WITH_MAX"
+echo "  Python Command:        $PYTHON_CMD"
+echo ""
+
+# Check Python dependencies (optional check)
+print_header "Checking Python dependencies..."
+$PYTHON_CMD -c "
+import sys
+required_modules = ['pandas', 'json', 'os', 'argparse', 'collections']
+missing_modules = []
+
+for module in required_modules:
+    try:
+        __import__(module)
+    except ImportError:
+        missing_modules.append(module)
+
+if missing_modules:
+    print(f'Missing required modules: {missing_modules}')
+    sys.exit(1)
+else:
+    print('All basic dependencies are available')
+" || {
+    print_error "Some Python dependencies are missing"
+    print_warning "Please install required packages: pip install pandas"
+    exit 1
+}
+
+# Create log directory if doesn't exists
+mkdir -p "$INFER_DIR/loc_eval"
+
+# Set up logging
+LOG_FILE="$INFER_DIR/loc_eval/loc_evaluation_$(date +%Y%m%d_%H%M%S).log"
+print_status "Logging output to: $LOG_FILE"
+
+# Build the command
+CMD_ARGS="\"$SCRIPT_NAME\" \
+    --infer-dir \"$INFER_DIR\" \
+    --split \"$SPLIT\" \
+    --dataset \"$DATASET\" \
+    --max-infer-turn \"$MAX_TURN\" \
+    --align-with-max \"$ALIGN_WITH_MAX\""
+
+# Run the Python script
+print_header "Running localization evaluation..."
+eval "$PYTHON_CMD $CMD_ARGS" 2>&1 | tee "$LOG_FILE"
+
+# Check if the script ran successfully
+if [ ${PIPESTATUS[0]} -eq 0 ]; then
+    print_status "Localization evaluation completed successfully!"
+    print_status "Results saved to: $INFER_DIR/loc_eval"
+    print_status "Log file: $LOG_FILE"
+
+    # Display summary if results exist
+    if [ -f "$INFER_DIR/loc_eval/loc_eval_results/loc_acc/overall_eval.json" ]; then
+        print_header "Evaluation Summary:"
+        cat "$INFER_DIR/loc_eval/loc_eval_results/loc_acc/overall_eval.json"
+        echo
+    fi
+else
+    print_error "Localization evaluation failed!"
+    print_warning "Check the log file for details: $LOG_FILE"
+    exit 1
+fi

evaluation/benchmarks/swe_bench/scripts/setup/instance_swe_entry_rebench.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+
+source ~/.bashrc
+SWEUTIL_DIR=/swe_util
+
+# FIXME: Cannot read SWE_INSTANCE_ID from the environment variable
+# SWE_INSTANCE_ID=django__django-11099
+if [ -z "$SWE_INSTANCE_ID" ]; then
+    echo "Error: SWE_INSTANCE_ID is not set." >&2
+    exit 1
+fi
+
+# Read the swe-bench-test-lite.json file and extract the required item based on instance_id
+item=$(jq --arg INSTANCE_ID "$SWE_INSTANCE_ID" '.[] | select(.instance_id == $INSTANCE_ID)' $SWEUTIL_DIR/eval_data/instances/swe-bench-instance.json)
+
+if [[ -z "$item" ]]; then
+  echo "No item found for the provided instance ID."
+  exit 1
+fi
+
+
+WORKSPACE_NAME=$(echo "$item" | jq -r '(.repo | tostring) + "__" + (.version | tostring) | gsub("/"; "__")')
+
+echo "WORKSPACE_NAME: $WORKSPACE_NAME"
+
+# Clear the workspace
+if [ -d /workspace ]; then
+    rm -rf /workspace/*
+else
+    mkdir /workspace
+fi
+# Copy repo to workspace
+if [ -d /workspace/$WORKSPACE_NAME ]; then
+    rm -rf /workspace/$WORKSPACE_NAME
+fi
+mkdir -p /workspace
+cp -r /testbed /workspace/$WORKSPACE_NAME
+
+# Activate instance-specific environment
+if [ -d /opt/miniconda3 ]; then
+    . /opt/miniconda3/etc/profile.d/conda.sh
+    conda activate testbed
+fi
+
+export PATH=/opt/conda/envs/testbed/bin:$PATH

evaluation/benchmarks/terminal_bench/README.md

@@ -0,0 +1,31 @@
+# Terminal-Bench Evaluation on OpenHands
+
+Terminal-Bench has its own evaluation harness that is very different from OpenHands'. We
+implemented [OpenHands agent](https://github.com/laude-institute/terminal-bench/tree/main/terminal_bench/agents/installed_agents/openhands) using OpenHands local runtime
+inside terminal-bench framework. Hereby we introduce how to use the terminal-bench
+harness to evaluate OpenHands.
+
+## Installation
+
+Terminal-bench ships a CLI tool to manage tasks and run evaluation.
+Please follow official [Installation Doc](https://www.tbench.ai/docs/installation). You could also clone terminal-bench [source code](https://github.com/laude-institute/terminal-bench) and use `uv run tb` CLI.
+
+## Evaluation
+
+Please see [Terminal-Bench Leaderboard](https://www.tbench.ai/leaderboard) for the latest
+instruction on benchmarking guidance. The dataset might evolve.
+
+Sample command:
+
+```bash
+export LLM_BASE_URL=<optional base url>
+export LLM_API_KEY=<llm key>
+tb run \
+    --dataset-name terminal-bench-core \
+    --dataset-version 0.1.1 \
+    --agent openhands \
+    --model <model> \
+    --cleanup
+```
+
+You could run `tb --help` or `tb run --help` to learn more about their CLI.

evaluation/benchmarks/testgeneval/NOTES.md

@@ -5,8 +5,7 @@ pynguin_ids = ['pydata__xarray-6548-16541', 'pydata__xarray-7003-16557', 'pydata
 ids = ['pydata__xarray-3114-16452', 'pydata__xarray-3151-16453', 'pydata__xarray-3156-16454', 'pydata__xarray-3239-16456', 'pydata__xarray-3239-16457', 'pydata__xarray-3239-16458', 'pydata__xarray-3302-16459', 'pydata__xarray-3364-16461', 'pydata__xarray-3677-16471', 'pydata__xarray-3905-16478', 'pydata__xarray-4182-16484', 'pydata__xarray-4248-16486', 'pydata__xarray-4339-16487', 'pydata__xarray-4419-16488', 'pydata__xarray-4629-16492', 'pydata__xarray-4750-16496', 'pydata__xarray-4802-16505', 'pydata__xarray-4966-16515', 'pydata__xarray-4994-16516', 'pydata__xarray-5033-16517', 'pydata__xarray-5126-16518', 'pydata__xarray-5126-16519', 'pydata__xarray-5131-16520', 'pydata__xarray-5365-16529', 'pydata__xarray-5455-16530', 'pydata__xarray-5662-16532', 'pydata__xarray-5731-16534', 'pydata__xarray-6135-16535', 'pydata__xarray-6135-16536', 'pydata__xarray-6386-16537', 'pydata__xarray-6394-16538', 'pydata__xarray-6400-16539', 'pydata__xarray-6461-16540', 'pydata__xarray-6548-16541', 'pydata__xarray-6599-16543', 'pydata__xarray-6601-16544', 'pydata__xarray-6882-16548', 'pydata__xarray-6889-16549', 'pydata__xarray-7003-16557', 'pydata__xarray-7147-16571', 'pydata__xarray-7150-16572', 'pydata__xarray-7203-16577', 'pydata__xarray-7229-16578', 'pydata__xarray-7393-16581', 'pydata__xarray-7400-16582']
 
 
-Command eval (our approach):
-poetry run ./evaluation/benchmarks/testgeneval/scripts/eval_infer_remote.sh evaluation/evaluation_outputs/outputs/kjain14__testgeneval-test/CodeActAgent/gpt-4o_maxiter_25_N_v0.20.0-no-hint-run_1/output.jsonl 10 kjain14/testgeneval test true
+
 
 Command run (our approach):
 ./evaluation/benchmarks/testgeneval/scripts/run_infer.sh llm.eval_gpt HEAD CodeActAgent -1 25 10 kjain14/testgeneval test 1 ../TestGenEval/results/testgeneval/preds/gpt-4o-2024-08-06__testgeneval__0.2__test.jsonl

evaluation/benchmarks/testgeneval/compute_readability.py

@@ -181,9 +181,7 @@ def distinct_methods_stats(tree, num_lines):
 
 
 def loops_stats(tree, num_lines):
-    """
-    Calculate the average number of loops.
-    """
+    """Calculate the average number of loops."""
     total_loops = 0
 
     def traverse(node):
@@ -199,9 +197,7 @@ def loops_stats(tree, num_lines):
 
 
 def branches_stats(tree, num_lines):
-    """
-    Calculate the average number of branches (conditional statements).
-    """
+    """Calculate the average number of branches (conditional statements)."""
     total_branches = 0
 
     def traverse(node):

evaluation/benchmarks/testgeneval/eval_infer.py

@@ -41,7 +41,7 @@ from evaluation.utils.shared import (
     reset_logger_for_multiprocessing,
     run_evaluation,
 )
-from openhands.core.config import OpenHandsConfig, SandboxConfig, get_parser
+from openhands.core.config import OpenHandsConfig, SandboxConfig, get_evaluation_parser
 from openhands.core.logger import openhands_logger as logger
 from openhands.core.main import create_runtime
 from openhands.events.action import CmdRunAction
@@ -192,8 +192,7 @@ def run_mutation_testing(
 def grade_test_output(
     test_suite: str, instance: pd.Series, test_output: str, test_spec: TestSpec, runtime
 ):
-    """
-    Two-pass test grading with short-circuiting:
+    """Two-pass test grading with short-circuiting:
     1. Run all tests to identify passing/failing tests
     2. If no failing tests, evaluate coverage immediately
     3. Otherwise, run only passing tests for coverage analysis
@@ -280,8 +279,7 @@ def process_instance(
     reset_logger: bool = True,
     log_dir: str | None = None,
 ) -> EvalOutput:
-    """
-    Evaluate agent performance on a TestGenEval problem instance.
+    """Evaluate agent performance on a TestGenEval problem instance.
 
     Note that this signature differs from the expected input to `run_evaluation`. Use
     `functools.partial` to provide optional arguments before passing to the evaluation harness.
@@ -453,8 +451,7 @@ def process_instance(
 
 
 def count_and_log_fields(evaluated_predictions, fields, key):
-    """
-    Count and log the sum of specified fields in the evaluated predictions,
+    """Count and log the sum of specified fields in the evaluated predictions,
     ignoring fields with a value of -1. If all values for a field are -1,
     return -1.
 
@@ -484,7 +481,7 @@ def count_and_log_fields(evaluated_predictions, fields, key):
 
 
 if __name__ == '__main__':
-    parser = get_parser()
+    parser = get_evaluation_parser()
     parser.add_argument(
         '--input-file', type=str, required=True, help='Path to input predictions file'
     )

evaluation/benchmarks/testgeneval/log_parsers.py

@@ -4,8 +4,7 @@ from evaluation.benchmarks.testgeneval.constants import TestStatus
 
 
 def parse_log_pytest(log: str) -> dict[str, str]:
-    """
-    Parser for test logs generated with PyTest framework
+    """Parser for test logs generated with PyTest framework
 
     Args:
         log (str): log content
@@ -26,8 +25,7 @@ def parse_log_pytest(log: str) -> dict[str, str]:
 
 
 def parse_log_pytest_options(log: str) -> dict[str, str]:
-    """
-    Parser for test logs generated with PyTest framework with options
+    """Parser for test logs generated with PyTest framework with options
 
     Args:
         log (str): log content
@@ -61,8 +59,7 @@ def parse_log_pytest_options(log: str) -> dict[str, str]:
 
 
 def parse_log_django(log: str) -> dict[str, str]:
-    """
-    Parser for test logs generated with Django tester framework
+    """Parser for test logs generated with Django tester framework
 
     Args:
         log (str): log content
@@ -141,8 +138,7 @@ def parse_log_django(log: str) -> dict[str, str]:
 
 
 def parse_log_pytest_v2(log: str) -> dict[str, str]:
-    """
-    Parser for test logs generated with PyTest framework (Later Version)
+    """Parser for test logs generated with PyTest framework (Later Version)
 
     Args:
         log (str): log content
@@ -170,8 +166,7 @@ def parse_log_pytest_v2(log: str) -> dict[str, str]:
 
 
 def parse_log_seaborn(log: str) -> dict[str, str]:
-    """
-    Parser for test logs generated with seaborn testing framework
+    """Parser for test logs generated with seaborn testing framework
 
     Args:
         log (str): log content
@@ -196,8 +191,7 @@ def parse_log_seaborn(log: str) -> dict[str, str]:
 
 
 def parse_log_sympy(log: str) -> dict[str, str]:
-    """
-    Parser for test logs generated with Sympy framework
+    """Parser for test logs generated with Sympy framework
 
     Args:
         log (str): log content
@@ -229,8 +223,7 @@ def parse_log_sympy(log: str) -> dict[str, str]:
 
 
 def parse_log_matplotlib(log: str) -> dict[str, str]:
-    """
-    Parser for test logs generated with PyTest framework
+    """Parser for test logs generated with PyTest framework
 
     Args:
         log (str): log content