Remove old SaaS extension example

The old example used environment variables which goes against
the new factory-based approach. The new external_repo_extension.py
example shows the proper way to extend OpenHands.

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

.github/workflows/e2e-tests.yml

@@ -187,6 +187,7 @@ jobs:
             test_settings.py::test_github_token_configuration \
             test_conversation.py::test_conversation_start \
             test_browsing_catchphrase.py::test_browsing_catchphrase \
+            test_multi_conversation_resume.py::test_multi_conversation_resume \
             -v --no-header --capture=no --timeout=900
 
       - name: Upload test results

.github/workflows/ghcr-build.yml

@@ -225,7 +225,7 @@ jobs:
           SANDBOX_RUNTIME_CONTAINER_IMAGE=$image_name \
           TEST_IN_CI=true \
           RUN_AS_OPENHANDS=false \
-          poetry run pytest -n 7 -raRs --reruns 2 --reruns-delay 5 -s ./tests/runtime --ignore=tests/runtime/test_browsergym_envs.py --durations=10
+          poetry run pytest -n 0 -raRs --reruns 2 --reruns-delay 5 -s ./tests/runtime --ignore=tests/runtime/test_browsergym_envs.py --durations=10
         env:
           DEBUG: "1"
 
@@ -284,7 +284,7 @@ jobs:
           SANDBOX_RUNTIME_CONTAINER_IMAGE=$image_name \
           TEST_IN_CI=true \
           RUN_AS_OPENHANDS=true \
-          poetry run pytest -n 7 -raRs --reruns 2 --reruns-delay 5 -s ./tests/runtime --ignore=tests/runtime/test_browsergym_envs.py --durations=10
+          poetry run pytest -n 0 -raRs --reruns 2 --reruns-delay 5 -s ./tests/runtime --ignore=tests/runtime/test_browsergym_envs.py --durations=10
         env:
           DEBUG: "1"
 

.github/workflows/stale.yml

@@ -15,7 +15,7 @@ jobs:
           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'
+          exempt-issue-labels: roadmap,backlog
           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

.github/workflows/welcome-good-first-issue.yml

@@ -45,6 +45,7 @@ jobs:
                     "This issue has been labeled as **good first issue**, which means it's a great place to get started with the OpenHands project.\n\n" +
                     "If you're interested in working on it, feel free to! No need to ask for permission.\n\n" +
                     "Be sure to check out our [development setup guide](" + repoUrl + "/blob/main/Development.md) to get your environment set up, and follow our [contribution guidelines](" + repoUrl + "/blob/main/CONTRIBUTING.md) when you're ready to submit a fix.\n\n" +
+                    "Feel free to join our developer community on [Slack](dub.sh/openhands). You can ask for [help](https://openhands-ai.slack.com/archives/C078L0FUGUX), [feedback](https://openhands-ai.slack.com/archives/C086ARSNMGA), and even ask for a [PR review](https://openhands-ai.slack.com/archives/C08D8FJ5771).\n\n" +
                     "🙌 Happy hacking! 🙌\n\n" +
                     "<!-- auto-comment:good-first-issue -->"
             });

.gitignore

@@ -257,3 +257,5 @@ containers/runtime/code
 
 # test results
 test-results
+.sessions
+.eval_sessions

Development.md

@@ -159,7 +159,7 @@ poetry run pytest ./tests/unit/test_*.py
 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.54-nikolaik`
+Example: `export SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.55-nikolaik`
 
 ## Develop inside Docker container
 

LICENSE

@@ -1,7 +1,12 @@
-The MIT License (MIT)
+Portions of this software are licensed as follows:
+* All content that resides under the enterprise/ directory is licensed under the license defined in "enterprise/LICENSE".
+* Content outside of the above mentioned directories or restrictions above is available under the MIT license as defined below.
+
 =====================
 
-Copyright © 2023
+The MIT License (MIT)
+
+Copyright © 2025
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

MIGRATION_GUIDE.md

@@ -0,0 +1,277 @@
+# Migration Guide: From Shared Globals to Context System
+
+This guide explains how to migrate from the deprecated `openhands.server.shared` globals to the new context system.
+
+## Overview
+
+The new context system replaces global variables with dependency injection, providing:
+
+- **Better testability**: Easy to mock dependencies in tests
+- **SaaS extensibility**: Custom contexts for multi-tenant scenarios
+- **Per-request contexts**: Different configurations per request
+- **No import-time side effects**: Lazy initialization of dependencies
+- **Type safety**: Better IDE support and type checking
+
+## Quick Migration
+
+### Before (Deprecated)
+```python
+from openhands.server.shared import config, server_config, file_store, sio
+
+def my_function():
+    # Use global variables
+    workspace_dir = config.workspace_dir
+    app_mode = server_config.app_mode
+    file_store.save_file(...)
+```
+
+### After (Recommended)
+```python
+from fastapi import Depends, Request
+from openhands.server.context import get_server_context, ServerContext
+
+@app.get('/my-endpoint')
+async def my_endpoint(
+    request: Request,
+    context: ServerContext = Depends(get_server_context)
+):
+    # Use context instead of globals
+    config = context.get_config()
+    server_config = context.get_server_config()
+    file_store = context.get_file_store()
+
+    workspace_dir = config.workspace_dir
+    app_mode = server_config.app_mode
+    file_store.save_file(...)
+```
+
+## Detailed Migration Steps
+
+### 1. Route Handlers
+
+**Before:**
+```python
+from openhands.server.shared import config, conversation_manager
+
+@app.post('/conversations')
+async def create_conversation(request: ConversationRequest):
+    conversation = conversation_manager.create_conversation(
+        request.user_id,
+        config.default_agent
+    )
+    return conversation
+```
+
+**After:**
+```python
+from fastapi import Depends
+from openhands.server.context import get_server_context, ServerContext
+
+@app.post('/conversations')
+async def create_conversation(
+    request: ConversationRequest,
+    context: ServerContext = Depends(get_server_context)
+):
+    config = context.get_config()
+    conversation_manager = context.get_conversation_manager()
+
+    conversation = conversation_manager.create_conversation(
+        request.user_id,
+        config.default_agent
+    )
+    return conversation
+```
+
+### 2. Service Classes
+
+**Before:**
+```python
+from openhands.server.shared import file_store, monitoring_listener
+
+class MyService:
+    def process_file(self, file_path: str):
+        content = file_store.read(file_path)
+        monitoring_listener.log_event('file_processed')
+        return content
+```
+
+**After:**
+```python
+from openhands.server.context import ServerContext
+
+class MyService:
+    def __init__(self, context: ServerContext):
+        self.context = context
+
+    def process_file(self, file_path: str):
+        file_store = self.context.get_file_store()
+        monitoring_listener = self.context.get_monitoring_listener()
+
+        content = file_store.read(file_path)
+        monitoring_listener.log_event('file_processed')
+        return content
+
+# In route handler:
+@app.post('/process')
+async def process_endpoint(
+    request: ProcessRequest,
+    context: ServerContext = Depends(get_server_context)
+):
+    service = MyService(context)
+    return service.process_file(request.file_path)
+```
+
+### 3. Store Classes
+
+**Before:**
+```python
+from openhands.server.shared import SettingsStoreImpl
+
+def get_user_settings(user_id: str):
+    store = SettingsStoreImpl(user_id)
+    return store.load()
+```
+
+**After:**
+```python
+from openhands.server.context import ServerContext
+
+def get_user_settings(user_id: str, context: ServerContext):
+    SettingsStoreClass = context.get_settings_store_class()
+    store = SettingsStoreClass(user_id)
+    return store.load()
+
+# In route handler:
+@app.get('/settings/{user_id}')
+async def get_settings(
+    user_id: str,
+    context: ServerContext = Depends(get_server_context)
+):
+    return get_user_settings(user_id, context)
+```
+
+### 4. Testing
+
+**Before:**
+```python
+import pytest
+from unittest.mock import patch
+
+def test_my_function():
+    with patch('openhands.server.shared.config') as mock_config:
+        mock_config.workspace_dir = '/test'
+        result = my_function()
+        assert result == expected
+```
+
+**After:**
+```python
+import pytest
+from openhands.server.context import create_server_context
+
+class MockServerContext:
+    def get_config(self):
+        mock_config = Mock()
+        mock_config.workspace_dir = '/test'
+        return mock_config
+
+def test_my_function():
+    context = MockServerContext()
+    result = my_function(context)
+    assert result == expected
+```
+
+## SaaS Extension Example
+
+The new context system makes it easy to extend OpenHands for SaaS scenarios:
+
+```python
+from openhands.server.context import ServerContext, set_context_class
+
+class SaaSServerContext(ServerContext):
+    def __init__(self, user_id: str, org_id: str):
+        self.user_id = user_id
+        self.org_id = org_id
+
+    def get_file_store(self):
+        # Return tenant-isolated file store
+        return MultiTenantFileStore(self.user_id, self.org_id)
+
+    def get_server_config(self):
+        # Return SaaS-specific configuration
+        return SaaSServerConfig(org_id=self.org_id)
+
+# Configure globally
+set_context_class('myapp.context.SaaSServerContext')
+
+# Use in routes with tenant context
+@app.get('/tenant/{org_id}/files')
+async def get_tenant_files(
+    org_id: str,
+    context: SaaSServerContext = Depends(get_server_context)
+):
+    file_store = context.get_file_store()
+    return file_store.list_files()
+```
+
+## Migration Checklist
+
+- [ ] Replace `from openhands.server.shared import ...` with context injection
+- [ ] Update route handlers to use `Depends(get_server_context)`
+- [ ] Modify service classes to accept `ServerContext` parameter
+- [ ] Update tests to use mock contexts instead of patching globals
+- [ ] Remove direct imports of shared globals
+- [ ] Test that all functionality still works
+
+## Backward Compatibility
+
+The old `openhands.server.shared` module still works but is deprecated. It will show deprecation warnings when imported. The globals are now implemented using the new context system internally.
+
+## Benefits After Migration
+
+1. **Better Testing**: Easy to mock dependencies without patching globals
+2. **Type Safety**: Better IDE support and type checking
+3. **Extensibility**: Easy to create custom contexts for different scenarios
+4. **Performance**: Lazy initialization reduces startup time
+5. **Maintainability**: Clear dependency relationships
+
+## Common Issues
+
+### Issue: Import errors during migration
+**Solution**: Make sure to import the context system correctly:
+```python
+from openhands.server.context import get_server_context, ServerContext
+```
+
+### Issue: Context not available in non-route functions
+**Solution**: Pass the context as a parameter:
+```python
+def helper_function(data: str, context: ServerContext):
+    config = context.get_config()
+    # ... use config
+```
+
+### Issue: Testing becomes more complex
+**Solution**: Create reusable mock contexts:
+```python
+# test_utils.py
+class TestServerContext(ServerContext):
+    def __init__(self):
+        self.mock_config = create_mock_config()
+        self.mock_file_store = create_mock_file_store()
+
+    def get_config(self):
+        return self.mock_config
+
+    def get_file_store(self):
+        return self.mock_file_store
+```
+
+## Getting Help
+
+If you encounter issues during migration:
+
+1. Check the examples in `examples/saas_extension.py`
+2. Look at the implementation in `openhands/server/context/`
+3. Review existing route handlers that have been migrated
+4. Create an issue if you find bugs or need clarification

README.md

@@ -79,17 +79,17 @@ You'll find OpenHands running at [http://localhost:3000](http://localhost:3000)
 You can also run OpenHands directly with Docker:
 
 ```bash
-docker pull docker.all-hands.dev/all-hands-ai/runtime:0.54-nikolaik
+docker pull docker.all-hands.dev/all-hands-ai/runtime:0.55-nikolaik
 
 docker run -it --rm --pull=always \
-    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.54-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.55-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.54
+    docker.all-hands.dev/all-hands-ai/openhands:0.55
 ```
 
 </details>
@@ -130,7 +130,6 @@ If you want to modify the OpenHands source code, check out [Development.md](http
 Having issues? The [Troubleshooting Guide](https://docs.all-hands.dev/usage/troubleshooting) can help.
 
 ## 📖 Documentation
-  <a href="https://deepwiki.com/All-Hands-AI/OpenHands"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki" title="Autogenerated Documentation by DeepWiki"></a>
 
 To learn more about the project, and for tips on using OpenHands,
 check out our [documentation](https://docs.all-hands.dev/usage/getting-started).

README_CN.md

@@ -51,17 +51,17 @@ OpenHands也可以使用Docker在本地系统上运行。
 
 
 ```bash
-docker pull docker.all-hands.dev/all-hands-ai/runtime:0.54-nikolaik
+docker pull docker.all-hands.dev/all-hands-ai/runtime:0.55-nikolaik
 
 docker run -it --rm --pull=always \
-    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.54-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.55-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.54
+    docker.all-hands.dev/all-hands-ai/openhands:0.55
 ```
 
 > **注意**: 如果您在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.54-nikolaik
+docker pull docker.all-hands.dev/all-hands-ai/runtime:0.55-nikolaik
 
 docker run -it --rm --pull=always \
-    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.54-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.55-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.54
+    docker.all-hands.dev/all-hands-ai/openhands:0.55
 ```
 
 **注**: バージョン0.44以前のOpenHandsを使用していた場合は、会話履歴を移行するために `mv ~/.openhands-state ~/.openhands` を実行してください。

REFACTOR_PLAN.md

@@ -0,0 +1,230 @@
+# OpenHands Server Context Refactoring Plan
+
+## Problem Statement
+
+The current OpenHands architecture has globals in `server/shared.py` that are initialized at import time based on environment variables. This creates several issues for the SaaS version:
+
+1. **Import-time dependencies**: All globals are created when modules are imported
+2. **Hard to extend**: SaaS can't easily override or extend components
+3. **CI/CD issues**: Everything depends on env vars being set correctly at import time
+4. **Per-user behavior**: Difficult to implement per-user/per-request behavior
+5. **Outside repo issues**: Hard to run SaaS from outside repo due to import dependencies
+
+## Current Problematic Globals
+
+From `openhands/server/shared.py`:
+- `config: OpenHandsConfig` - Core app configuration
+- `server_config: ServerConfig` - Server-specific configuration
+- `file_store: FileStore` - File storage implementation
+- `sio: socketio.AsyncServer` - Socket.IO server instance
+- `conversation_manager` - Conversation management implementation
+- `monitoring_listener` - Monitoring implementation
+- `SettingsStoreImpl`, `SecretsStoreImpl`, `ConversationStoreImpl` - Storage implementations
+
+## Solution: ServerContext Pattern
+
+### 1. Create ServerContext Base Class
+
+Create `openhands/server/context/server_context.py`:
+
+```python
+from abc import ABC, abstractmethod
+from typing import Optional
+import socketio
+from openhands.core.config.openhands_config import OpenHandsConfig
+from openhands.server.config.server_config import ServerConfig
+from openhands.storage.files import FileStore
+# ... other imports
+
+class ServerContext(ABC):
+    """Base class for server context that holds all server dependencies.
+
+    This replaces the global variables in shared.py and allows for:
+    - Dependency injection
+    - Easy extensibility for SaaS
+    - Per-request contexts
+    - Testability
+    """
+
+    def __init__(self):
+        self._config: Optional[OpenHandsConfig] = None
+        self._server_config: Optional[ServerConfig] = None
+        self._file_store: Optional[FileStore] = None
+        # ... other cached instances
+
+    @abstractmethod
+    def get_config(self) -> OpenHandsConfig:
+        """Get the OpenHands configuration"""
+
+    @abstractmethod
+    def get_server_config(self) -> ServerConfig:
+        """Get the server configuration"""
+
+    @abstractmethod
+    def get_file_store(self) -> FileStore:
+        """Get the file store implementation"""
+
+    # ... other abstract methods for all current globals
+```
+
+### 2. Create Default Implementation
+
+Create `openhands/server/context/default_server_context.py`:
+
+```python
+class DefaultServerContext(ServerContext):
+    """Default implementation that maintains current behavior"""
+
+    def get_config(self) -> OpenHandsConfig:
+        if self._config is None:
+            self._config = load_openhands_config()
+        return self._config
+
+    def get_server_config(self) -> ServerConfig:
+        if self._server_config is None:
+            self._server_config = load_server_config()
+        return self._server_config
+
+    # ... implement all methods with current logic
+```
+
+### 3. Context Provider System
+
+Create `openhands/server/context/context_provider.py`:
+
+```python
+from fastapi import Request
+from openhands.utils.import_utils import get_impl
+
+_context_class: Optional[str] = None
+
+def set_context_class(context_class: str):
+    """Set the server context class to use"""
+    global _context_class
+    _context_class = context_class
+
+async def get_server_context(request: Request) -> ServerContext:
+    """Get server context from request, with caching"""
+    context = getattr(request.state, 'server_context', None)
+    if context:
+        return context
+
+    # Use configured context class or default
+    context_cls_name = _context_class or 'openhands.server.context.default_server_context.DefaultServerContext'
+    context_cls = get_impl(ServerContext, context_cls_name)
+    context = context_cls()
+
+    request.state.server_context = context
+    return context
+```
+
+### 4. Update Shared.py (Backward Compatibility)
+
+Keep `shared.py` for backward compatibility but make it use the context:
+
+```python
+# openhands/server/shared.py
+from openhands.server.context.default_server_context import DefaultServerContext
+
+# Create default context for backward compatibility
+_default_context = DefaultServerContext()
+
+# Expose globals for backward compatibility
+config = _default_context.get_config()
+server_config = _default_context.get_server_config()
+file_store = _default_context.get_file_store()
+# ... etc
+```
+
+### 5. Update Routes to Use Context
+
+Update all route files to use dependency injection:
+
+```python
+# Example: openhands/server/routes/settings.py
+from openhands.server.context import get_server_context
+
+@app.get('/settings')
+async def get_settings(
+    request: Request,
+    context: ServerContext = Depends(get_server_context)
+):
+    config = context.get_config()
+    # ... use config instead of importing from shared
+```
+
+## Benefits for SaaS
+
+### 1. Easy Extension
+
+SaaS can create their own context:
+
+```python
+# In SaaS repo: saas/server_context.py
+from openhands.server.context import ServerContext
+
+class SaaSServerContext(ServerContext):
+    def get_server_config(self) -> ServerConfig:
+        # Return SaaS-specific config with enterprise features
+        return SaaSServerConfig()
+
+    def get_conversation_manager(self) -> ConversationManager:
+        # Return multi-tenant conversation manager
+        return MultiTenantConversationManager()
+```
+
+### 2. Per-Request Contexts
+
+SaaS can implement per-user contexts:
+
+```python
+class PerUserServerContext(ServerContext):
+    def __init__(self, user_id: str, org_id: str):
+        super().__init__()
+        self.user_id = user_id
+        self.org_id = org_id
+
+    def get_file_store(self) -> FileStore:
+        # Return user-specific file store
+        return UserFileStore(self.user_id, self.org_id)
+```
+
+### 3. No Import-Time Dependencies
+
+SaaS can run without setting environment variables at import time:
+
+```python
+# In SaaS startup
+from openhands.server.context import set_context_class
+set_context_class('saas.server_context.SaaSServerContext')
+```
+
+## Migration Strategy
+
+### Phase 1: Create Context System
+1. Create ServerContext base class and default implementation
+2. Create context provider system
+3. Update shared.py for backward compatibility
+
+### Phase 2: Update Routes Gradually
+1. Update one route at a time to use context injection
+2. Test each route to ensure no regressions
+3. Keep backward compatibility during transition
+
+### Phase 3: Clean Up
+1. Remove globals from shared.py once all routes are updated
+2. Update documentation
+3. Create examples for SaaS extension
+
+## Implementation Order
+
+1. `openhands/server/context/server_context.py` - Base class
+2. `openhands/server/context/default_server_context.py` - Default implementation
+3. `openhands/server/context/context_provider.py` - Provider system
+4. `openhands/server/context/__init__.py` - Public API
+5. Update `openhands/server/shared.py` for backward compatibility
+6. Update routes one by one to use context injection
+7. Update tests to use context system
+8. Documentation and examples
+
+This approach provides a clean migration path while maintaining backward compatibility and enabling the SaaS extensibility requirements.

REFACTOR_SUMMARY.md

@@ -0,0 +1,206 @@
+# OpenHands Server Globals Refactoring - Summary
+
+## Overview
+
+Successfully refactored OpenHands server globals in `shared.py` and `server_config.py` to enable SaaS extensibility without import-time dependencies. The refactoring introduces a dependency injection pattern using a `ServerContext` system that maintains backward compatibility while enabling multi-tenant SaaS scenarios.
+
+## Problem Solved
+
+### Before Refactoring
+- **Global variables on import**: `shared.py` created globals like `config`, `server_config`, `file_store`, `sio`, etc. on module import
+- **Import-time side effects**: Loading the module triggered configuration loading and dependency initialization
+- **SaaS integration issues**: External SaaS repos had CI/CD problems due to environment variable dependencies
+- **Testing difficulties**: Hard to mock dependencies due to global state
+- **No extensibility**: Impossible to customize behavior for different tenants or environments
+
+### After Refactoring
+- **Dependency injection**: Clean `ServerContext` pattern with lazy initialization
+- **No import-time side effects**: Dependencies only loaded when actually needed
+- **SaaS extensibility**: Easy to create custom contexts for multi-tenant scenarios
+- **Better testability**: Easy to mock contexts for testing
+- **Backward compatibility**: Existing code continues to work with deprecation warnings
+
+## Architecture Changes
+
+### New Context System
+
+```
+openhands/server/context/
+├── __init__.py                 # Public API
+├── server_context.py          # Abstract base class
+├── default_server_context.py  # Default implementation
+└── context_provider.py        # Dependency injection system
+```
+
+### Key Components
+
+1. **ServerContext (Abstract Base Class)**
+   - Defines interface for all server dependencies
+   - 9 abstract methods for different dependency types
+   - Extensible for SaaS implementations
+
+2. **DefaultServerContext**
+   - Maintains exact behavior of original shared.py
+   - Lazy initialization of all dependencies
+   - No import-time side effects
+
+3. **Context Provider System**
+   - `get_server_context()` for FastAPI dependency injection
+   - `set_context_class()` for global configuration
+   - `create_server_context()` for testing/CLI usage
+
+4. **Backward Compatibility Layer**
+   - `shared.py` now uses `__getattr__` for lazy loading
+   - All existing imports continue to work
+   - Deprecation warnings guide migration
+
+## SaaS Extensibility
+
+### Multi-Tenant Context Example
+
+```python
+class SaaSServerContext(ServerContext):
+    def __init__(self, user_id: str, org_id: str):
+        self.user_id = user_id
+        self.org_id = org_id
+
+    def get_file_store(self):
+        # Return tenant-isolated file store
+        return MultiTenantFileStore(self.user_id, self.org_id)
+
+    def get_server_config(self):
+        # Return SaaS-specific configuration
+        return SaaSServerConfig(org_id=self.org_id)
+
+# Configure globally
+set_context_class('myapp.context.SaaSServerContext')
+```
+
+### Benefits for SaaS
+- **Per-tenant isolation**: Different storage, config, and features per organization
+- **Enterprise features**: Easy to add billing, advanced monitoring, etc.
+- **Scalable architecture**: Context per request enables horizontal scaling
+- **Clean separation**: SaaS code stays in external repo, extends OpenHands cleanly
+
+## Migration Path
+
+### For OpenHands Core
+- **Phase 1**: Refactoring complete, backward compatibility maintained
+- **Phase 2**: Gradually migrate routes to use dependency injection
+- **Phase 3**: Remove deprecated shared.py (future release)
+
+### For SaaS Implementations
+- **Immediate**: Can use new context system for new features
+- **Gradual**: Migrate existing code using migration guide
+- **Benefits**: Cleaner architecture, better testing, easier deployment
+
+## Files Created/Modified
+
+### New Files
+- `openhands/server/context/__init__.py` - Public API
+- `openhands/server/context/server_context.py` - Abstract base class
+- `openhands/server/context/default_server_context.py` - Default implementation
+- `openhands/server/context/context_provider.py` - Dependency injection
+- `examples/saas_extension.py` - SaaS extension example
+- `MIGRATION_GUIDE.md` - Detailed migration instructions
+- `test_refactor.py` - Comprehensive test suite
+
+### Modified Files
+- `openhands/server/shared.py` - Backward compatibility layer
+
+## Testing Results
+
+Comprehensive test suite with 5 test categories:
+
+1. ✅ **Context System**: Import, creation, class switching
+2. ✅ **Backward Compatibility**: Lazy loading, attribute access
+3. ✅ **Abstract Base Class**: Proper abstraction, required methods
+4. ✅ **Default Context**: Instantiation, method availability
+5. ✅ **SaaS Example**: Multi-tenant context structure
+
+**Result: 5/5 tests passed** 🎉
+
+## Usage Examples
+
+### New Way (Recommended)
+```python
+from fastapi import Depends
+from openhands.server.context import get_server_context, ServerContext
+
+@app.get('/conversations')
+async def get_conversations(
+    context: ServerContext = Depends(get_server_context)
+):
+    config = context.get_config()
+    conversation_manager = context.get_conversation_manager()
+    return conversation_manager.list_conversations()
+```
+
+### Old Way (Still Works)
+```python
+from openhands.server.shared import config, conversation_manager
+
+@app.get('/conversations')
+async def get_conversations():
+    # Shows deprecation warning but works
+    return conversation_manager.list_conversations()
+```
+
+### SaaS Extension
+```python
+# In SaaS application startup
+from openhands.server.context import set_context_class
+set_context_class('myapp.context.SaaSServerContext')
+
+# Routes automatically get tenant-aware context
+@app.get('/tenant/{org_id}/conversations')
+async def get_tenant_conversations(
+    org_id: str,
+    context: SaaSServerContext = Depends(get_server_context)
+):
+    # context.org_id and context.user_id available
+    # All dependencies are tenant-isolated
+    conversation_manager = context.get_conversation_manager()
+    return conversation_manager.list_conversations()
+```
+
+## Benefits Achieved
+
+### For OpenHands Core
+- ✅ **Better Architecture**: Clean dependency injection pattern
+- ✅ **Improved Testing**: Easy to mock dependencies
+- ✅ **No Breaking Changes**: Full backward compatibility
+- ✅ **Performance**: Lazy loading reduces startup time
+- ✅ **Type Safety**: Better IDE support and type checking
+
+### For SaaS Implementations
+- ✅ **Multi-Tenancy**: Per-organization contexts and isolation
+- ✅ **Extensibility**: Easy to add enterprise features
+- ✅ **Clean Integration**: No need to fork OpenHands
+- ✅ **Deployment Flexibility**: Can run from external repos
+- ✅ **CI/CD Fixes**: No more environment variable dependencies
+
+### For Development
+- ✅ **Maintainability**: Clear dependency relationships
+- ✅ **Debugging**: Easier to trace dependency issues
+- ✅ **Documentation**: Clear migration path and examples
+- ✅ **Future-Proof**: Extensible architecture for new features
+
+## Next Steps
+
+1. **Immediate**: Refactoring is complete and tested
+2. **Short-term**: Begin migrating core routes to use dependency injection
+3. **Medium-term**: SaaS implementations can adopt new context system
+4. **Long-term**: Remove deprecated shared.py in future major release
+
+## Conclusion
+
+The refactoring successfully addresses all the original problems:
+
+- ❌ **Import-time dependencies** → ✅ **Lazy initialization**
+- ❌ **Global state pollution** → ✅ **Clean dependency injection**
+- ❌ **SaaS integration issues** → ✅ **Multi-tenant context system**
+- ❌ **Testing difficulties** → ✅ **Easy mocking and testing**
+- ❌ **No extensibility** → ✅ **Pluggable context implementations**
+
+The new architecture enables OpenHands to support SaaS scenarios while maintaining full backward compatibility and improving the overall codebase quality.

config.template.toml

@@ -363,10 +363,11 @@ classpath = "my_package.my_module.MyCustomAgent"
 #confirmation_mode = false
 
 # The security analyzer to use (For Headless / CLI only -  In Web this is overridden by Session Init)
-#security_analyzer = ""
+# Available options: 'llm' (default), 'invariant'
+#security_analyzer = "llm"
 
 # Whether to enable security analyzer
-#enable_security_analyzer = false
+#enable_security_analyzer = true
 
 #################################### Condenser #################################
 # Condensers control how conversation history is managed and compressed when

containers/app/Dockerfile

@@ -58,34 +58,34 @@ 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 --gid $OPENHANDS_USER_ID app
+RUN groupadd --gid $OPENHANDS_USER_ID openhands
 RUN useradd -l -m -u $OPENHANDS_USER_ID --gid $OPENHANDS_USER_ID -s /bin/bash openhands && \
-    usermod -aG app openhands && \
+    usermod -aG openhands openhands && \
     usermod -aG sudo openhands && \
     echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers
-RUN chown -R openhands:app /app && chmod -R 770 /app
-RUN sudo chown -R openhands:app $WORKSPACE_BASE && sudo chmod -R 770 $WORKSPACE_BASE
+RUN chown -R openhands:openhands /app && chmod -R 770 /app
+RUN sudo chown -R openhands:openhands $WORKSPACE_BASE && sudo chmod -R 770 $WORKSPACE_BASE
 USER openhands
 
 ENV VIRTUAL_ENV=/app/.venv \
     PATH="/app/.venv/bin:$PATH" \
     PYTHONPATH='/app'
 
-COPY --chown=openhands:app --chmod=770 --from=backend-builder ${VIRTUAL_ENV} ${VIRTUAL_ENV}
+COPY --chown=openhands:openhands --chmod=770 --from=backend-builder ${VIRTUAL_ENV} ${VIRTUAL_ENV}
 
-COPY --chown=openhands:app --chmod=770 ./microagents ./microagents
-COPY --chown=openhands:app --chmod=770 ./openhands ./openhands
-COPY --chown=openhands:app --chmod=777 ./openhands/runtime/plugins ./openhands/runtime/plugins
-COPY --chown=openhands:app pyproject.toml poetry.lock README.md MANIFEST.in LICENSE ./
+COPY --chown=openhands:openhands --chmod=770 ./microagents ./microagents
+COPY --chown=openhands:openhands --chmod=770 ./openhands ./openhands
+COPY --chown=openhands:openhands --chmod=777 ./openhands/runtime/plugins ./openhands/runtime/plugins
+COPY --chown=openhands:openhands pyproject.toml poetry.lock README.md MANIFEST.in LICENSE ./
 
 # This is run as "openhands" user, and will create __pycache__ with openhands:openhands ownership
 RUN python openhands/core/download.py # No-op to download assets
 # Add this line to set group ownership of all files/directories not already in "app" group
-# openhands:openhands -> openhands:app
-RUN find /app \! -group app -exec chgrp app {} +
+# openhands:openhands -> openhands:openhands
+RUN find /app \! -group openhands -exec chgrp openhands {} +
 
-COPY --chown=openhands:app --chmod=770 --from=frontend-builder /app/build ./frontend/build
-COPY --chown=openhands:app --chmod=770 ./containers/app/entrypoint.sh /app/entrypoint.sh
+COPY --chown=openhands:openhands --chmod=770 --from=frontend-builder /app/build ./frontend/build
+COPY --chown=openhands:openhands --chmod=770 ./containers/app/entrypoint.sh /app/entrypoint.sh
 
 USER root
 

containers/app/entrypoint.sh

@@ -54,7 +54,7 @@ else
       fi
     fi
   fi
-  usermod -aG app enduser
+  usermod -aG openhands enduser
   # get the user group of /var/run/docker.sock and set openhands to that group
   DOCKER_SOCKET_GID=$(stat -c '%g' /var/run/docker.sock)
   echo "Docker socket group id: $DOCKER_SOCKET_GID"

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.54-nikolaik}
+      - SANDBOX_RUNTIME_CONTAINER_IMAGE=${SANDBOX_RUNTIME_CONTAINER_IMAGE:-ghcr.io/all-hands-ai/runtime:0.55-nikolaik}
       - SANDBOX_USER_ID=${SANDBOX_USER_ID:-1234}
       - WORKSPACE_MOUNT_PATH=${WORKSPACE_BASE:-$PWD/workspace}
     ports:

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.54-nikolaik}
+      - SANDBOX_RUNTIME_CONTAINER_IMAGE=${SANDBOX_RUNTIME_CONTAINER_IMAGE:-docker.all-hands.dev/all-hands-ai/runtime:0.55-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/EXTENSIBILITY_MIGRATION.md

@@ -0,0 +1,272 @@
+# OpenHands Extensibility Migration Guide
+
+This guide explains how to migrate from the old global variable approach to the new factory-based extensibility system.
+
+## Overview
+
+OpenHands has been refactored to eliminate import-time dependencies on environment variables and global state. This enables external repositories to cleanly extend OpenHands without configuration conflicts.
+
+## The Problem We Solved
+
+### Before (Problematic)
+```python
+# In OpenHands shared.py - loaded at import time
+config = Config()  # Reads environment variables
+server_config = ServerConfig()  # More environment variables
+
+# External repos had to:
+# 1. Set environment variables before importing OpenHands
+# 2. Deal with global state conflicts
+# 3. Couldn't easily override specific behaviors
+```
+
+### After (Clean)
+```python
+# External repos can now:
+from openhands.server.factory import create_openhands_app
+
+app = create_openhands_app(
+    context_factory=lambda: MyCustomContext(),
+    include_oss_routes=False
+)
+```
+
+## Migration Paths
+
+### 1. For External Repositories (Recommended)
+
+**Old Way (Don't do this):**
+```python
+# external_repo/main.py
+import os
+os.environ['OPENHANDS_CONFIG_CLS'] = 'my_config.MyConfig'
+os.environ['CONVERSATION_MANAGER_CLASS'] = 'my_manager.MyManager'
+
+from openhands.server.app import app  # Imports with global state
+```
+
+**New Way (Recommended):**
+```python
+# external_repo/main.py
+from openhands.server.factory import create_openhands_app
+from external_repo.context import ExternalRepoContext
+
+def create_app():
+    return create_openhands_app(
+        context_factory=lambda: ExternalRepoContext(),
+        include_oss_routes=False,  # Skip OSS-specific routes
+        title='My Enterprise Platform'
+    )
+
+app = create_app()
+
+# Add your own routes
+@app.get('/enterprise/dashboard')
+async def dashboard():
+    return {'status': 'enterprise'}
+```
+
+### 2. For OpenHands Core Development
+
+**Old Way:**
+```python
+# In route handlers
+from openhands.server.shared import config, server_config
+
+@app.get('/example')
+async def example_route():
+    storage_path = config.workspace_base
+    app_mode = server_config.app_mode
+```
+
+**New Way:**
+```python
+# In route handlers
+from fastapi import Depends
+from openhands.server.context import get_server_context, ServerContext
+
+@app.get('/example')
+async def example_route(
+    context: ServerContext = Depends(get_server_context)
+):
+    config = context.get_config()
+    server_config = context.get_server_config()
+    storage_path = config.workspace_base
+    app_mode = server_config.app_mode
+```
+
+## Custom Context Implementation
+
+### Step 1: Create Your Context Class
+
+```python
+# my_extension/context.py
+from openhands.server.context.server_context import ServerContext
+
+class MyCustomContext(ServerContext):
+    def __init__(self, tenant_id: str = 'default'):
+        super().__init__()
+        self.tenant_id = tenant_id
+    
+    def get_config(self):
+        """Override with tenant-specific configuration."""
+        config = super().get_config()
+        config.workspace_base = f'/data/tenants/{self.tenant_id}/workspace'
+        return config
+    
+    def get_server_config(self):
+        """Override server configuration."""
+        server_config = super().get_server_config()
+        server_config.app_mode = 'ENTERPRISE'
+        server_config.enable_billing = True
+        return server_config
+```
+
+### Step 2: Create Your FastAPI App
+
+```python
+# my_extension/app.py
+from openhands.server.factory import create_openhands_app
+from my_extension.context import MyCustomContext
+
+def create_my_app():
+    # Option A: Extend OpenHands app directly
+    app = create_openhands_app(
+        context_factory=lambda: MyCustomContext(),
+        title='My Enterprise Platform'
+    )
+    
+    # Add your routes
+    @app.get('/enterprise/status')
+    async def enterprise_status():
+        return {'mode': 'enterprise'}
+    
+    return app
+
+# Option B: Create your own app and mount OpenHands
+from fastapi import FastAPI
+
+def create_my_app_with_mount():
+    main_app = FastAPI(title='My Platform')
+    
+    openhands_app = create_openhands_app(
+        context_factory=lambda: MyCustomContext()
+    )
+    
+    main_app.mount('/openhands', openhands_app)
+    
+    @main_app.get('/my-dashboard')
+    async def dashboard():
+        return {'dashboard': 'data'}
+    
+    return main_app
+```
+
+### Step 3: Run Your Application
+
+```python
+# my_extension/main.py
+import uvicorn
+from my_extension.app import create_my_app
+
+if __name__ == '__main__':
+    app = create_my_app()
+    uvicorn.run(app, host='0.0.0.0', port=8000)
+```
+
+## Advanced Patterns
+
+### Multi-Tenant Context
+
+```python
+class MultiTenantContext(ServerContext):
+    def __init__(self, request: Request):
+        super().__init__()
+        # Extract tenant from request
+        self.tenant_id = request.headers.get('X-Tenant-ID', 'default')
+    
+    def get_file_store(self):
+        # Return tenant-isolated file store
+        return TenantFileStore(tenant_id=self.tenant_id)
+
+# Use with factory
+def create_tenant_context(request: Request):
+    return MultiTenantContext(request)
+
+app = create_openhands_app(
+    context_factory=create_tenant_context
+)
+```
+
+### Custom Lifespan Management
+
+```python
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def my_lifespan(app: FastAPI):
+    # Startup
+    print("Starting my custom services...")
+    await initialize_my_database()
+    
+    yield
+    
+    # Shutdown
+    print("Shutting down my custom services...")
+    await cleanup_my_database()
+
+app = create_openhands_app(
+    context_factory=MyContext,
+    custom_lifespan=my_lifespan
+)
+```
+
+## Testing Your Extension
+
+```python
+# tests/test_my_extension.py
+from fastapi.testclient import TestClient
+from my_extension.app import create_my_app
+
+def test_my_extension():
+    app = create_my_app()
+    client = TestClient(app)
+    
+    # Test your custom routes
+    response = client.get('/enterprise/status')
+    assert response.status_code == 200
+    assert response.json()['mode'] == 'enterprise'
+    
+    # Test OpenHands routes still work
+    response = client.get('/api/health')
+    assert response.status_code == 200
+```
+
+## Benefits of the New Approach
+
+1. **No Environment Variables**: Configuration is done through code, not environment variables
+2. **Clean Separation**: External repos don't modify OpenHands globals
+3. **Dependency Injection**: Proper FastAPI dependency injection patterns
+4. **Testability**: Easy to mock contexts for testing
+5. **Flexibility**: Can create multiple apps with different configurations
+6. **No Import-Time Side Effects**: Safe to import OpenHands modules
+
+## Backward Compatibility
+
+The old `openhands.server.shared` module still works but is deprecated. It will show deprecation warnings and should be migrated to the new context system.
+
+## Common Pitfalls
+
+1. **Don't set environment variables**: Use the factory pattern instead
+2. **Don't import `openhands.server.app` directly**: Use the factory to create your own app
+3. **Don't modify global state**: Use dependency injection through contexts
+4. **Don't forget to override dependencies**: Use `app.dependency_overrides` if needed
+
+## Getting Help
+
+If you need help migrating your extension, please:
+1. Check the examples in `examples/external_repo_extension.py`
+2. Look at the test cases for patterns
+3. Open an issue with your specific use case
+
+The new system is designed to be more flexible and maintainable while enabling clean extensibility for all types of OpenHands deployments.

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

@@ -1,5 +1,5 @@
 ---
-title: Jira Data Center Integration (Beta)
+title: Jira Data Center Integration (Coming soon...)
 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.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: Jira Cloud Integration
+title: Jira Cloud Integration (Coming soon...)
 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.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: Linear Integration
+title: Linear Integration (Coming soon...)
 description: Complete guide for setting up Linear integration with OpenHands Cloud, including service account creation, API key generation, webhook configuration, and workspace integration setup.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-title: Project Management Tool Integrations
+title: Project Management Tool Integrations (Coming soon...)
 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.
 ---
 
@@ -18,9 +18,9 @@ Integration requires two levels of setup:
 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)
+- [Jira Cloud Integration (Coming soon...)](./jira-integration.md)
+- [Jira Data Center Integration (Coming soon...)](./jira-dc-integration.md)
+- [Linear Integration (Coming soon...)](./linear-integration.md)
 
 ## Usage
 

docs/usage/confirmation-mode.mdx

@@ -0,0 +1,52 @@
+# Confirmation Mode and Security Analyzers
+
+OpenHands provides a security framework to help protect users from potentially risky actions through **Confirmation Mode** and **Security Analyzers**. This system analyzes agent actions and prompts users for confirmation when high-risk operations are detected.
+
+## Overview
+
+The security system consists of two main components:
+
+1. **Confirmation Mode**: When enabled, the agent will pause and ask for user confirmation before executing actions that are flagged as high-risk by the security analyzer.
+
+2. **Security Analyzers**: These are modules that evaluate the risk level of agent actions and determine whether user confirmation is required.
+
+## Configuration
+
+### CLI
+In CLI mode, confirmation is enabled by default. You will have an option to uses the LLM Analyzer and will automatically confirm LOW and MEDIUM risk actions, only prompting for HIGH risk actions.
+
+## Security Analyzers
+
+OpenHands includes multiple analyzers:
+
+- **No Analyzer**: Do not use any security analyzer. The agent will prompt you to confirm *EVERY* action.
+- **LLM Risk Analyzer** (default): Uses the same LLM as the agent to assess action risk levels
+- **Invariant Analyzer**: Uses Invariant Labs' policy engine to evaluate action traces against security policies
+
+### LLM Risk Analyzer
+The default analyzer that leverages the agent's LLM to evaluate the security risk of each action. It considers the action type, parameters, and context to assign risk levels.
+
+### Invariant Analyzer
+An advanced analyzer that:
+- Collects conversation events and parses them into a trace
+- Checks the trace against an Invariant policy to classify risk (low, medium, high)
+- Manages an Invariant server container automatically if needed
+- Supports optional browsing-alignment and harmful-content checks
+
+## How It Works
+
+1. **Action Analysis**: When the agent wants to perform an action, the selected security analyzer evaluates its risk level.
+
+2. **Risk Assessment**: The analyzer returns one of three risk levels:
+   - **LOW**: Action proceeds without confirmation
+   - **MEDIUM**: Action proceeds without confirmation (may be configurable in future)
+   - **HIGH**: Action is paused, and user confirmation is requested
+
+3. **User Confirmation**: For high-risk actions, a confirmation dialog appears with:
+   - Description of the action
+   - Risk assessment explanation
+   - Options to approve or deny action
+
+4. **Action Execution**: Based on user response:
+   - **Approve**: Action proceeds as planned
+   - **Deny**: Action is cancelled

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

@@ -87,19 +87,13 @@ source ~/.bashrc  # or source ~/.zshrc
 
 </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 openhands
 </Note>
 
-4. Set your model, API key, and other preferences using the UI (or alternatively environment variables, below).
+3. 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
@@ -119,7 +113,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.54-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.55-nikolaik \
     -e SANDBOX_USER_ID=$(id -u) \
     -e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \
     -e LLM_API_KEY=$LLM_API_KEY \
@@ -128,7 +122,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.54 \
+    docker.all-hands.dev/all-hands-ai/openhands:0.55 \
     python -m openhands.cli.entry --override-cli-mode true
 ```
 

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

@@ -61,7 +61,7 @@ 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.54-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.55-nikolaik \
     -e SANDBOX_USER_ID=$(id -u) \
     -e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \
     -e LLM_API_KEY=$LLM_API_KEY \
@@ -73,7 +73,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.54 \
+    docker.all-hands.dev/all-hands-ai/openhands:0.55 \
     python -m openhands.core.main -t "write a bash script that prints hi"
 ```
 

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.54-nikolaik
+docker pull docker.all-hands.dev/all-hands-ai/runtime:0.55-nikolaik
 
 docker run -it --rm --pull=always \
-    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.54-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.55-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.54
+    docker.all-hands.dev/all-hands-ai/openhands:0.55
 ```
 
 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.54
+Status: Image is up to date for docker.all-hands.dev/all-hands-ai/openhands:0.55
 Starting OpenHands...
 Running OpenHands as root
 14:22:13 - openhands:INFO: server_config.py:50 - Using config class None

docs/usage/local-setup.mdx

@@ -45,6 +45,13 @@ A system with a modern processor and a minimum of **4GB RAM** is recommended to
   1. [Install WSL](https://learn.microsoft.com/en-us/windows/wsl/install).
   2. Run `wsl --version` in powershell and confirm `Default Version: 2`.
 
+  **Ubuntu (Linux Distribution)**
+
+  1. Install Ubuntu: `wsl --install -d Ubuntu` in PowerShell as Administrator.
+  2. Restart computer when prompted.
+  3. Open Ubuntu from Start menu to complete setup.
+  4. Verify installation: `wsl --list` should show Ubuntu.
+
   **Docker Desktop**
 
   1. [Install Docker Desktop on Windows](https://docs.docker.com/desktop/setup/install/windows-install).
@@ -53,7 +60,7 @@ A system with a modern processor and a minimum of **4GB RAM** is recommended to
   - Resources > WSL Integration: `Enable integration with my default WSL distro` is enabled.
 
   <Note>
-  The docker command below to start the app must be run inside the WSL terminal.
+  The docker command below to start the app must be run inside the WSL terminal. Use `wsl -d Ubuntu` in PowerShell or search "Ubuntu" in the Start menu to access the Ubuntu terminal.
   </Note>
 
   **Alternative: Windows without WSL**
@@ -109,17 +116,17 @@ Note that you'll still need `uv` installed for the default MCP servers to work p
 <Accordion title="Docker Command (Click to expand)">
 
 ```bash
-docker pull docker.all-hands.dev/all-hands-ai/runtime:0.54-nikolaik
+docker pull docker.all-hands.dev/all-hands-ai/runtime:0.55-nikolaik
 
 docker run -it --rm --pull=always \
-    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.54-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.55-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.54
+    docker.all-hands.dev/all-hands-ai/openhands:0.55
 ```
 
 </Accordion>

docs/usage/runtimes/e2b.mdx

@@ -22,7 +22,7 @@ SDK to spawn and control these sandboxes.
 
 You can use the E2B CLI to create a custom sandbox with a Dockerfile. Read the full guide
 [here](https://e2b.dev/docs/guide/custom-sandbox). The premade OpenHands sandbox for E2B is set up in the `containers`
-directory. and it's called `openhands`.
+directory, and it's called `openhands`.
 
 ## Debugging
 

docs/usage/troubleshooting/troubleshooting.mdx

@@ -38,6 +38,23 @@ 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.
 
+### On Linux, Getting ConnectTimeout Error
+
+**Description**
+
+When running on Linux, you might run into the error `ERROR:root:<class 'httpx.ConnectTimeout'>: timed out`.
+
+**Resolution**
+
+If you installed Docker from your distribution’s package repository (e.g., docker.io on Debian/Ubuntu), be aware that
+these packages can sometimes be outdated or include changes that cause compatibility issues. try reinstalling Docker
+[using the official instructions](https://docs.docker.com/engine/install/) to ensure you are running a compatible version.
+
+If that does not solve the issue, try incrementally adding the following parameters to the docker run command:
+* `--network host`
+* `-e SANDBOX_USE_HOST_NETWORK=true`
+* `-e DOCKER_HOST_ADDR=127.0.0.1`
+
 ### Internal Server Error. Ports are not available
 
 **Description**

enterprise/LICENSE

@@ -0,0 +1,89 @@
+# PolyForm Free Trial License 1.0.0
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software
+to do everything you might do with the software that would
+otherwise infringe the licensor's copyright in it for any
+permitted purpose.  However, you may only make changes or
+new works based on the software according to [Changes and New
+Works License](#changes-and-new-works-license), and you may
+not distribute copies of the software.
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## Free Trial
+
+Use of the software for more than 30 days per calendar year is not allowed without a commercial license.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+If you violate any of these terms, or do anything with the
+software not covered by your licenses, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

evaluation/benchmarks/EDA/run_infer.py

@@ -9,8 +9,8 @@ from evaluation.utils.shared import (
     EvalMetadata,
     EvalOutput,
     compatibility_for_eval_history_pairs,
-    get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -61,18 +61,15 @@ AGENT_CLS_TO_INST_SUFFIX = {
 def get_config(
     metadata: EvalMetadata,
 ) -> OpenHandsConfig:
-    sandbox_config = get_default_sandbox_config_for_eval()
-    sandbox_config.base_container_image = 'python:3.12-bookworm'
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    # Create config with EDA-specific container image
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         runtime='docker',
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
     )
+
+    # Override the container image for EDA
+    config.sandbox.base_container_image = 'python:3.12-bookworm'
+
     config.set_llm_config(metadata.llm_config)
     agent_config = config.get_agent_config(metadata.agent_class)
     agent_config.enable_prompt_extensions = False

evaluation/benchmarks/agent_bench/run_infer.py

@@ -17,8 +17,8 @@ from evaluation.utils.shared import (
     EvalMetadata,
     EvalOutput,
     compatibility_for_eval_history_pairs,
-    get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -41,19 +41,12 @@ from openhands.utils.async_utils import call_async_from_sync
 def get_config(
     metadata: EvalMetadata,
 ) -> OpenHandsConfig:
-    sandbox_config = get_default_sandbox_config_for_eval()
-    sandbox_config.base_container_image = 'python:3.12-slim'
+    # Create config with agent_bench-specific container image
+    config = get_openhands_config_for_eval(metadata=metadata)
+
+    # Override the container image for agent_bench
+    config.sandbox.base_container_image = 'python:3.12-slim'
 
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
-        runtime=os.environ.get('RUNTIME', 'docker'),
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
-    )
     config.set_llm_config(metadata.llm_config)
     agent_config = config.get_agent_config(metadata.agent_class)
     agent_config.enable_prompt_extensions = False

evaluation/benchmarks/aider_bench/run_infer.py

@@ -18,6 +18,7 @@ from evaluation.utils.shared import (
     compatibility_for_eval_history_pairs,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -50,15 +51,10 @@ def get_config(
 ) -> OpenHandsConfig:
     sandbox_config = get_default_sandbox_config_for_eval()
     sandbox_config.base_container_image = 'python:3.11-bookworm'
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
+        sandbox_config=sandbox_config,
         runtime=os.environ.get('RUNTIME', 'docker'),
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
     )
     config.set_llm_config(metadata.llm_config)
     agent_config = config.get_agent_config(metadata.agent_class)

evaluation/benchmarks/biocoder/run_infer.py

@@ -16,6 +16,7 @@ from evaluation.utils.shared import (
     compatibility_for_eval_history_pairs,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -61,15 +62,10 @@ def get_config(
     sandbox_config = get_default_sandbox_config_for_eval()
     sandbox_config.base_container_image = BIOCODER_BENCH_CONTAINER_IMAGE
 
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         runtime='docker',
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     config.set_llm_config(metadata.llm_config)
     agent_config = config.get_agent_config(metadata.agent_class)

evaluation/benchmarks/bird/run_infer.py

@@ -19,6 +19,7 @@ from evaluation.utils.shared import (
     compatibility_for_eval_history_pairs,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -75,15 +76,10 @@ def get_config(
     sandbox_config = get_default_sandbox_config_for_eval()
     sandbox_config.base_container_image = 'python:3.12-bookworm'
 
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         runtime='docker',
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     config.set_llm_config(metadata.llm_config)
     agent_config = config.get_agent_config(metadata.agent_class)

evaluation/benchmarks/browsing_delegation/run_infer.py

@@ -12,6 +12,7 @@ from evaluation.utils.shared import (
     compatibility_for_eval_history_pairs,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -40,14 +41,8 @@ def get_config(
     )
     sandbox_config = get_default_sandbox_config_for_eval()
     sandbox_config.base_container_image = 'python:3.12-bookworm'
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
-        runtime='docker',
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        workspace_base=None,
-        workspace_mount_path=None,
+    config = get_openhands_config_for_eval(
+        metadata=metadata, runtime='docker', sandbox_config=sandbox_config
     )
     config.set_llm_config(metadata.llm_config)
     agent_config = config.get_agent_config(metadata.agent_class)

evaluation/benchmarks/commit0/run_infer.py

@@ -17,6 +17,7 @@ from evaluation.utils.shared import (
     codeact_user_response,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -114,16 +115,11 @@ def get_config(
     sandbox_config = get_default_sandbox_config_for_eval()
     sandbox_config.base_container_image = base_container_image
 
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
-        max_iterations=metadata.max_iterations,
-        enable_browser=RUN_WITH_BROWSING,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
+        sandbox_config=sandbox_config,
         runtime=os.environ.get('RUNTIME', 'docker'),
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        enable_browser=RUN_WITH_BROWSING,
     )
     config.set_llm_config(
         update_llm_config_for_completions_logging(

evaluation/benchmarks/discoverybench/run_infer.py

@@ -18,6 +18,7 @@ from evaluation.utils.shared import (
     compatibility_for_eval_history_pairs,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -65,15 +66,10 @@ def get_config(
 ) -> OpenHandsConfig:
     sandbox_config = get_default_sandbox_config_for_eval()
     sandbox_config.base_container_image = 'python:3.12-bookworm'
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         runtime='docker',
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     config.set_llm_config(metadata.llm_config)
     agent_config = config.get_agent_config(metadata.agent_class)

evaluation/benchmarks/gaia/run_infer.py

@@ -23,6 +23,7 @@ from evaluation.utils.shared import (
     compatibility_for_eval_history_pairs,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -60,15 +61,10 @@ def get_config(
 ) -> OpenHandsConfig:
     sandbox_config = get_default_sandbox_config_for_eval()
     sandbox_config.base_container_image = 'nikolaik/python-nodejs:python3.12-nodejs22'
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
+        sandbox_config=sandbox_config,
         runtime='docker',
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
     )
     config.set_llm_config(metadata.llm_config)
     if metadata.agent_config:

evaluation/benchmarks/gorilla/run_infer.py

@@ -13,6 +13,7 @@ from evaluation.utils.shared import (
     compatibility_for_eval_history_pairs,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -43,15 +44,10 @@ def get_config(
 ) -> OpenHandsConfig:
     sandbox_config = get_default_sandbox_config_for_eval()
     sandbox_config.base_container_image = 'python:3.12-bookworm'
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         runtime='docker',
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     config.set_llm_config(metadata.llm_config)
     agent_config = config.get_agent_config(metadata.agent_class)

evaluation/benchmarks/gpqa/run_infer.py

@@ -31,6 +31,7 @@ from evaluation.utils.shared import (
     compatibility_for_eval_history_pairs,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -64,15 +65,10 @@ def get_config(
 ) -> OpenHandsConfig:
     sandbox_config = get_default_sandbox_config_for_eval()
     sandbox_config.base_container_image = 'python:3.12-bookworm'
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         runtime='docker',
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     config.set_llm_config(metadata.llm_config)
     agent_config = config.get_agent_config(metadata.agent_class)

evaluation/benchmarks/humanevalfix/run_infer.py

@@ -24,6 +24,7 @@ from evaluation.utils.shared import (
     compatibility_for_eval_history_pairs,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -85,15 +86,10 @@ def get_config(
 ) -> OpenHandsConfig:
     sandbox_config = get_default_sandbox_config_for_eval()
     sandbox_config.base_container_image = 'python:3.12-bookworm'
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         runtime='docker',
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     config.set_llm_config(metadata.llm_config)
     agent_config = config.get_agent_config(metadata.agent_class)

evaluation/benchmarks/lca_ci_build_repair/eval_infer.py

@@ -16,6 +16,7 @@ import ruamel.yaml
 from evaluation.utils.shared import (
     EvalMetadata,
     get_default_sandbox_config_for_eval,
+    get_openhands_config_for_eval,
     make_metadata,
 )
 from openhands.core.config import (
@@ -37,15 +38,10 @@ def get_config(
 ) -> OpenHandsConfig:
     sandbox_config = get_default_sandbox_config_for_eval()
     sandbox_config.base_container_image = 'python:3.12-bookworm'
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         runtime='docker',
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     config.set_llm_config(metadata.llm_config)
     agent_config = config.get_agent_config(metadata.agent_class)

evaluation/benchmarks/lca_ci_build_repair/run_infer.py

@@ -23,6 +23,7 @@ from evaluation.utils.shared import (
     compatibility_for_eval_history_pairs,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -48,15 +49,10 @@ def get_config(
 ) -> OpenHandsConfig:
     sandbox_config = get_default_sandbox_config_for_eval()
     sandbox_config.base_container_image = 'python:3.12-bookworm'
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         runtime='docker',
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     config.set_llm_config(metadata.llm_config)
     agent_config = config.get_agent_config(metadata.agent_class)

evaluation/benchmarks/logic_reasoning/run_infer.py

@@ -11,6 +11,7 @@ from evaluation.utils.shared import (
     compatibility_for_eval_history_pairs,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -52,15 +53,10 @@ def get_config(
         '$OH_INTERPRETER_PATH -m pip install scitools-pyke'
     )
 
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         runtime='docker',
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     config.set_llm_config(metadata.llm_config)
     agent_config = config.get_agent_config(metadata.agent_class)

evaluation/benchmarks/miniwob/run_infer.py

@@ -14,6 +14,7 @@ from evaluation.utils.shared import (
     compatibility_for_eval_history_pairs,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -58,15 +59,10 @@ def get_config(
 ) -> OpenHandsConfig:
     sandbox_config = get_default_sandbox_config_for_eval()
     sandbox_config.base_container_image = 'xingyaoww/od-eval-miniwob:v1.0'
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         runtime=os.environ.get('RUNTIME', 'docker'),
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     config.set_llm_config(
         update_llm_config_for_completions_logging(

evaluation/benchmarks/mint/run_infer.py

@@ -16,6 +16,7 @@ from evaluation.utils.shared import (
     compatibility_for_eval_history_pairs,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -110,15 +111,10 @@ def get_config(
         f'$OH_INTERPRETER_PATH -m pip install {" ".join(MINT_DEPENDENCIES)}'
     )
 
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         runtime='docker',
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     config.set_llm_config(metadata.llm_config)
     agent_config = config.get_agent_config(metadata.agent_class)

evaluation/benchmarks/ml_bench/run_infer.py

@@ -27,6 +27,7 @@ from evaluation.utils.shared import (
     compatibility_for_eval_history_pairs,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -80,15 +81,10 @@ def get_config(
 ) -> OpenHandsConfig:
     sandbox_config = get_default_sandbox_config_for_eval()
     sandbox_config.base_container_image = 'public.ecr.aws/i5g0m1f6/ml-bench'
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         runtime='docker',
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     config.set_llm_config(metadata.llm_config)
     agent_config = config.get_agent_config(metadata.agent_class)

evaluation/benchmarks/multi_swe_bench/eval_infer.py

@@ -23,6 +23,7 @@ from evaluation.utils.shared import (
     EvalMetadata,
     EvalOutput,
     get_default_sandbox_config_for_eval,
+    get_openhands_config_for_eval,
     prepare_dataset,
     reset_logger_for_multiprocessing,
     run_evaluation,
@@ -87,13 +88,9 @@ def get_config(metadata: EvalMetadata, instance: pd.Series) -> OpenHandsConfig:
         dataset_name=metadata.dataset,
         instance_id=instance['instance_id'],
     )
-    config = OpenHandsConfig(
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
         runtime=os.environ.get('RUNTIME', 'docker'),
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     return config
 

evaluation/benchmarks/multi_swe_bench/run_infer.py

@@ -21,6 +21,7 @@ from evaluation.utils.shared import (
     codeact_user_response,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     is_fatal_evaluation_error,
     make_metadata,
     prepare_dataset,
@@ -341,16 +342,11 @@ def get_config(
         instance_id=instance['instance_id'],
     )
 
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
-        max_iterations=metadata.max_iterations,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         enable_browser=RUN_WITH_BROWSING,
         runtime=os.environ.get('RUNTIME', 'docker'),
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     config.set_llm_config(
         update_llm_config_for_completions_logging(

evaluation/benchmarks/nocode_bench/run_infer_nc.py

@@ -31,6 +31,7 @@ from evaluation.utils.shared import (
     codeact_user_response,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     is_fatal_evaluation_error,
     make_metadata,
     prepare_dataset,
@@ -174,15 +175,10 @@ def get_config(
         instance_id=instance['instance_id'],
     )
 
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
-        max_iterations=metadata.max_iterations,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         runtime=os.environ.get('RUNTIME', 'docker'),
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
 
     config.set_llm_config(

evaluation/benchmarks/scienceagentbench/run_infer.py

@@ -13,6 +13,7 @@ from evaluation.utils.shared import (
     compatibility_for_eval_history_pairs,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -64,16 +65,10 @@ def get_config(
     sandbox_config.base_container_image = (
         'docker.io/xingyaoww/openhands-eval-scienceagentbench'
     )
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         runtime=os.environ.get('RUNTIME', 'docker'),
-        max_budget_per_task=4,
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     config.set_llm_config(
         update_llm_config_for_completions_logging(

evaluation/benchmarks/swe_bench/eval_infer.py

@@ -19,6 +19,7 @@ from evaluation.utils.shared import (
     EvalMetadata,
     EvalOutput,
     get_default_sandbox_config_for_eval,
+    get_openhands_config_for_eval,
     prepare_dataset,
     reset_logger_for_multiprocessing,
     run_evaluation,
@@ -83,13 +84,9 @@ def get_config(metadata: EvalMetadata, instance: pd.Series) -> OpenHandsConfig:
         dataset_name=metadata.dataset,
         instance_id=instance['instance_id'],
     )
-    config = OpenHandsConfig(
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
         runtime=os.environ.get('RUNTIME', 'docker'),
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     return config
 

evaluation/benchmarks/swe_bench/run_infer.py

@@ -32,6 +32,7 @@ from evaluation.utils.shared import (
     codeact_user_response,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     is_fatal_evaluation_error,
     make_metadata,
     prepare_dataset,
@@ -227,16 +228,11 @@ def get_config(
         instance_id=instance['instance_id'],
     )
 
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
-        max_iterations=metadata.max_iterations,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         enable_browser=RUN_WITH_BROWSING,
         runtime=os.environ.get('RUNTIME', 'docker'),
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
 
     config.set_llm_config(

evaluation/benchmarks/swe_bench/run_localize.py

@@ -20,6 +20,7 @@ from evaluation.utils.shared import (
     codeact_user_response,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     is_fatal_evaluation_error,
     make_metadata,
     prepare_dataset,
@@ -199,16 +200,11 @@ def get_config(
         'REPO_PATH': f'/workspace/{workspace_dir_name}/',
     }
 
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
-        max_iterations=metadata.max_iterations,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         enable_browser=RUN_WITH_BROWSING,
         runtime=os.environ.get('RUNTIME', 'docker'),
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     config.set_llm_config(
         update_llm_config_for_completions_logging(

evaluation/benchmarks/swe_bench/scripts/rollout_swegym.sh

@@ -13,6 +13,7 @@ N_RUNS=${4:-1}
 export EXP_NAME=$EXP_NAME
 # use 2x resources for rollout since some codebases are pretty resource-intensive
 export DEFAULT_RUNTIME_RESOURCE_FACTOR=2
+export ITERATIVE_EVAL_MODE=false
 echo "MODEL: $MODEL"
 echo "EXP_NAME: $EXP_NAME"
 DATASET="SWE-Gym/SWE-Gym"  # change this to the "/SWE-Gym-Lite" if you want to rollout the lite subset

evaluation/benchmarks/testgeneval/eval_infer.py

@@ -37,6 +37,7 @@ from evaluation.benchmarks.testgeneval.utils import load_testgeneval_dataset
 from evaluation.utils.shared import (
     EvalMetadata,
     EvalOutput,
+    get_openhands_config_for_eval,
     prepare_dataset,
     reset_logger_for_multiprocessing,
     run_evaluation,
@@ -58,20 +59,21 @@ def get_config(instance: pd.Series) -> OpenHandsConfig:
         f'Invalid container image for instance {instance["instance_id_swebench"]}.'
     )
     logger.info(f'Using instance container image: {base_container_image}.')
-    return OpenHandsConfig(
-        run_as_openhands=False,
-        runtime=os.environ.get('RUNTIME', 'eventstream'),
-        sandbox=SandboxConfig(
-            base_container_image=base_container_image,
-            use_host_network=False,
-            timeout=1800,
-            api_key=os.environ.get('ALLHANDS_API_KEY'),
-            remote_runtime_api_url=os.environ.get(
-                'SANDBOX_REMOTE_RUNTIME_API_URL', 'http://localhost:8000'
-            ),
+
+    # Create custom sandbox config for testgeneval with specific requirements
+    sandbox_config = SandboxConfig(
+        base_container_image=base_container_image,
+        use_host_network=False,
+        timeout=1800,  # Longer timeout than default (300)
+        api_key=os.environ.get('ALLHANDS_API_KEY'),
+        remote_runtime_api_url=os.environ.get(
+            'SANDBOX_REMOTE_RUNTIME_API_URL', 'http://localhost:8000'
         ),
-        workspace_base=None,
-        workspace_mount_path=None,
+    )
+
+    return get_openhands_config_for_eval(
+        sandbox_config=sandbox_config,
+        runtime=os.environ.get('RUNTIME', 'docker'),  # Different default runtime
     )
 
 

evaluation/benchmarks/testgeneval/run_infer.py

@@ -25,6 +25,7 @@ from evaluation.utils.shared import (
     assert_and_raise,
     codeact_user_response,
     get_metrics,
+    get_openhands_config_for_eval,
     is_fatal_evaluation_error,
     make_metadata,
     prepare_dataset,
@@ -126,29 +127,26 @@ def get_config(
         f'Submit an issue on https://github.com/All-Hands-AI/OpenHands if you run into any issues.'
     )
 
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
-        max_iterations=metadata.max_iterations,
-        runtime=os.environ.get('RUNTIME', 'eventstream'),
-        sandbox=SandboxConfig(
-            base_container_image=base_container_image,
-            enable_auto_lint=True,
-            use_host_network=False,
-            # large enough timeout, since some testcases take very long to run
-            timeout=300,
-            # Add platform to the sandbox config to solve issue 4401
-            platform='linux/amd64',
-            api_key=os.environ.get('ALLHANDS_API_KEY', None),
-            remote_runtime_api_url=os.environ.get(
-                'SANDBOX_REMOTE_RUNTIME_API_URL', 'http://localhost:8000'
-            ),
-            keep_runtime_alive=False,
-            remote_runtime_init_timeout=3600,
+    sandbox_config = SandboxConfig(
+        base_container_image=base_container_image,
+        enable_auto_lint=True,
+        use_host_network=False,
+        # large enough timeout, since some testcases take very long to run
+        timeout=300,
+        # Add platform to the sandbox config to solve issue 4401
+        platform='linux/amd64',
+        api_key=os.environ.get('ALLHANDS_API_KEY', None),
+        remote_runtime_api_url=os.environ.get(
+            'SANDBOX_REMOTE_RUNTIME_API_URL', 'http://localhost:8000'
         ),
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        keep_runtime_alive=False,
+        remote_runtime_init_timeout=3600,
+    )
+
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
+        sandbox_config=sandbox_config,
+        runtime=os.environ.get('RUNTIME', 'docker'),
     )
     config.set_llm_config(
         update_llm_config_for_completions_logging(

evaluation/benchmarks/the_agent_company/run_infer.py

@@ -12,7 +12,10 @@ import tempfile
 import yaml
 from browsing import pre_login
 
-from evaluation.utils.shared import get_default_sandbox_config_for_eval
+from evaluation.utils.shared import (
+    get_default_sandbox_config_for_eval,
+    get_openhands_config_for_eval,
+)
 from openhands.controller.state.state import State
 from openhands.core.config import (
     LLMConfig,
@@ -42,19 +45,17 @@ def get_config(
     sandbox_config.enable_auto_lint = True
     # If the web services are running on the host machine, this must be set to True
     sandbox_config.use_host_network = True
-    config = OpenHandsConfig(
-        run_as_openhands=False,
-        max_budget_per_task=4,
+    config = get_openhands_config_for_eval(
         max_iterations=100,
-        save_trajectory_path=os.path.join(
-            mount_path_on_host, f'traj_{task_short_name}.json'
-        ),
-        sandbox=sandbox_config,
         # we mount trajectories path so that trajectories, generated by OpenHands
         # controller, can be accessible to the evaluator file in the runtime container
+        sandbox_config=sandbox_config,
         workspace_mount_path=mount_path_on_host,
-        workspace_mount_path_in_sandbox='/outputs',
     )
+    config.save_trajectory_path = os.path.join(
+        mount_path_on_host, f'traj_{task_short_name}.json'
+    )
+    config.max_budget_per_task = 4
     config.set_llm_config(llm_config)
     if agent_config:
         config.set_agent_config(agent_config)

evaluation/benchmarks/toolqa/run_infer.py

@@ -12,6 +12,7 @@ from evaluation.utils.shared import (
     compatibility_for_eval_history_pairs,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -44,15 +45,10 @@ def get_config(
 ) -> OpenHandsConfig:
     sandbox_config = get_default_sandbox_config_for_eval()
     sandbox_config.base_container_image = 'python:3.12-bookworm'
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         runtime='docker',
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     config.set_llm_config(metadata.llm_config)
     agent_config = config.get_agent_config(metadata.agent_class)

evaluation/benchmarks/visual_swe_bench/run_infer.py

@@ -20,6 +20,7 @@ from evaluation.utils.shared import (
     codeact_user_response,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     is_fatal_evaluation_error,
     make_metadata,
     prepare_dataset,
@@ -160,16 +161,11 @@ def get_config(
         instance_id=instance['instance_id'],
     )
 
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
-        max_iterations=metadata.max_iterations,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         enable_browser=RUN_WITH_BROWSING,
         runtime=os.environ.get('RUNTIME', 'docker'),
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     config.set_llm_config(
         update_llm_config_for_completions_logging(

evaluation/benchmarks/visualwebarena/run_infer.py

@@ -13,6 +13,7 @@ from evaluation.utils.shared import (
     compatibility_for_eval_history_pairs,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -73,16 +74,10 @@ def get_config(
         'VWA_WIKIPEDIA': f'{base_url}:8888',
         'VWA_HOMEPAGE': f'{base_url}:4399',
     }
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         runtime='docker',
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
-        attach_to_existing=True,
+        sandbox_config=sandbox_config,
     )
     config.set_llm_config(
         update_llm_config_for_completions_logging(

evaluation/benchmarks/webarena/run_infer.py

@@ -13,6 +13,7 @@ from evaluation.utils.shared import (
     compatibility_for_eval_history_pairs,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -65,15 +66,10 @@ def get_config(
         'MAP': f'{base_url}:3000',
         'HOMEPAGE': f'{base_url}:4399',
     }
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         runtime='docker',
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
+        sandbox_config=sandbox_config,
     )
     config.set_llm_config(metadata.llm_config)
     agent_config = config.get_agent_config(metadata.agent_class)

evaluation/integration_tests/run_infer.py

@@ -10,6 +10,7 @@ from evaluation.utils.shared import (
     EvalOutput,
     get_default_sandbox_config_for_eval,
     get_metrics,
+    get_openhands_config_for_eval,
     make_metadata,
     prepare_dataset,
     reset_logger_for_multiprocessing,
@@ -45,18 +46,12 @@ def get_config(
 ) -> OpenHandsConfig:
     sandbox_config = get_default_sandbox_config_for_eval()
     sandbox_config.platform = 'linux/amd64'
-    config = OpenHandsConfig(
-        default_agent=metadata.agent_class,
-        run_as_openhands=False,
+    config = get_openhands_config_for_eval(
+        metadata=metadata,
         runtime=os.environ.get('RUNTIME', 'docker'),
-        max_iterations=metadata.max_iterations,
-        sandbox=sandbox_config,
-        # do not mount workspace
-        workspace_base=None,
-        workspace_mount_path=None,
-        # debug
-        debug=True,
+        sandbox_config=sandbox_config,
     )
+    config.debug = True
     config.set_llm_config(
         update_llm_config_for_completions_logging(
             metadata.llm_config, metadata.eval_output_dir, instance_id

evaluation/utils/scripts/aggregate_token_usage.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""
+Script to aggregate token usage metrics from LLM completion files.
+
+Usage:
+    python aggregate_token_usage.py <directory_path> [--input-cost <cost>] [--output-cost <cost>] [--cached-cost <cost>]
+
+Arguments:
+    directory_path: Path to the directory containing completion files
+    --input-cost: Cost per input token (default: 0.0)
+    --output-cost: Cost per output token (default: 0.0)
+    --cached-cost: Cost per cached token (default: 0.0)
+"""
+
+import argparse
+import json
+import os
+from pathlib import Path
+
+
+def aggregate_token_usage(
+    directory_path, input_cost=0.0, output_cost=0.0, cached_cost=0.0
+):
+    """
+    Aggregate token usage metrics from all JSON completion files in the directory.
+
+    Args:
+        directory_path (str): Path to directory containing completion files
+        input_cost (float): Cost per input token
+        output_cost (float): Cost per output token
+        cached_cost (float): Cost per cached token
+    """
+
+    # Initialize counters
+    totals = {
+        'input_tokens': 0,
+        'output_tokens': 0,
+        'cached_tokens': 0,
+        'total_tokens': 0,
+        'files_processed': 0,
+        'files_with_errors': 0,
+        'cost': 0,
+    }
+
+    # Find all JSON files recursively
+    json_files = list(Path(directory_path).rglob('*.json'))
+
+    print(f'Found {len(json_files)} JSON files to process...')
+
+    for json_file in json_files:
+        try:
+            with open(json_file, 'r', encoding='utf-8') as f:
+                data = json.load(f)
+
+            # Look for usage data in response or fncall_response
+            usage_data = None
+            if (
+                'response' in data
+                and isinstance(data['response'], dict)
+                and 'usage' in data['response']
+            ):
+                usage_data = data['response']['usage']
+            elif (
+                'fncall_response' in data
+                and isinstance(data['fncall_response'], dict)
+                and 'usage' in data['fncall_response']
+            ):
+                usage_data = data['fncall_response']['usage']
+
+            if usage_data:
+                # Extract token counts
+                completion_tokens = usage_data.get('completion_tokens', 0)
+                prompt_tokens = usage_data.get('prompt_tokens', 0)
+                cached_tokens = usage_data.get('cached_tokens', 0)
+
+                # Handle cases where cached_tokens might be in prompt_tokens_details
+                if cached_tokens == 0 and 'prompt_tokens_details' in usage_data:
+                    details = usage_data['prompt_tokens_details']
+                    if isinstance(details, dict) and 'cached_tokens' in details:
+                        cached_tokens = details.get('cached_tokens', 0) or 0
+
+                # Calculate non-cached input tokens
+                non_cached_input = prompt_tokens - cached_tokens
+
+                # Update totals
+                totals['input_tokens'] += non_cached_input
+                totals['output_tokens'] += completion_tokens
+                totals['cached_tokens'] += cached_tokens
+                totals['total_tokens'] += prompt_tokens + completion_tokens
+
+            if 'cost' in data:
+                totals['cost'] += data['cost']
+            totals['files_processed'] += 1
+
+            # Progress indicator
+            if totals['files_processed'] % 1000 == 0:
+                print(f'Processed {totals["files_processed"]} files...')
+
+        except Exception as e:
+            totals['files_with_errors'] += 1
+            if totals['files_with_errors'] <= 5:  # Only show first 5 errors
+                print(f'Error processing {json_file}: {e}')
+
+    # Calculate costs
+    input_cost_total = totals['input_tokens'] * input_cost
+    output_cost_total = totals['output_tokens'] * output_cost
+    cached_cost_total = totals['cached_tokens'] * cached_cost
+    total_cost = input_cost_total + output_cost_total + cached_cost_total
+
+    # Print results
+    print('\n' + '=' * 60)
+    print('TOKEN USAGE AGGREGATION RESULTS')
+    print('=' * 60)
+    print(f'Files processed: {totals["files_processed"]:,}')
+    print(f'Files with errors: {totals["files_with_errors"]:,}')
+    print()
+    print('TOKEN COUNTS:')
+    print(f'  Input tokens (non-cached):             {totals["input_tokens"]:,}')
+    print(f'  Output tokens:                         {totals["output_tokens"]:,}')
+    print(f'  Cached tokens:                         {totals["cached_tokens"]:,}')
+    print(f'  Total tokens:                          {totals["total_tokens"]:,}')
+    print(f'  Total costs (based on returned value): ${totals["cost"]:.6f}')
+    print()
+
+    if input_cost > 0 or output_cost > 0 or cached_cost > 0:
+        print('COST CALCULATED BASED ON PROVIDED RATE:')
+        print(
+            f'  Input cost:   ${input_cost_total:.6f} ({totals["input_tokens"]:,} × ${input_cost:.6f})'
+        )
+        print(
+            f'  Output cost:  ${output_cost_total:.6f} ({totals["output_tokens"]:,} × ${output_cost:.6f})'
+        )
+        print(
+            f'  Cached cost:  ${cached_cost_total:.6f} ({totals["cached_tokens"]:,} × ${cached_cost:.6f})'
+        )
+        print(f'  Total cost:   ${total_cost:.6f}')
+        print()
+
+    print('SUMMARY:')
+    print(
+        f'  Total input tokens:  {totals["input_tokens"] + totals["cached_tokens"]:,}'
+    )
+    print(f'  Total output tokens: {totals["output_tokens"]:,}')
+    print(f'  Grand total tokens:  {totals["total_tokens"]:,}')
+
+    return totals
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Aggregate token usage metrics from LLM completion files',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python aggregate_token_usage.py /path/to/completions
+  python aggregate_token_usage.py /path/to/completions --input-cost 0.000001 --output-cost 0.000002
+  python aggregate_token_usage.py /path/to/completions --input-cost 0.000001 --output-cost 0.000002 --cached-cost 0.0000005
+        """,
+    )
+
+    parser.add_argument(
+        'directory_path', help='Path to directory containing completion files'
+    )
+
+    parser.add_argument(
+        '--input-cost',
+        type=float,
+        default=0.0,
+        help='Cost per input token (default: 0.0)',
+    )
+
+    parser.add_argument(
+        '--output-cost',
+        type=float,
+        default=0.0,
+        help='Cost per output token (default: 0.0)',
+    )
+
+    parser.add_argument(
+        '--cached-cost',
+        type=float,
+        default=0.0,
+        help='Cost per cached token (default: 0.0)',
+    )
+
+    args = parser.parse_args()
+
+    # Validate directory path
+    if not os.path.exists(args.directory_path):
+        print(f"Error: Directory '{args.directory_path}' does not exist.")
+        return 1
+
+    if not os.path.isdir(args.directory_path):
+        print(f"Error: '{args.directory_path}' is not a directory.")
+        return 1
+
+    # Run aggregation
+    try:
+        aggregate_token_usage(
+            args.directory_path, args.input_cost, args.output_cost, args.cached_cost
+        )
+        return 0
+    except Exception as e:
+        print(f'Error during aggregation: {e}')
+        return 1
+
+
+if __name__ == '__main__':
+    exit(main())

evaluation/utils/shared.py

@@ -703,3 +703,79 @@ def get_default_sandbox_config_for_eval() -> SandboxConfig:
         remote_runtime_enable_retries=True,
         remote_runtime_class='sysbox',
     )
+
+
+def get_openhands_config_for_eval(
+    metadata: EvalMetadata | None = None,
+    sandbox_config: SandboxConfig | None = None,
+    runtime: str | None = None,
+    max_iterations: int | None = None,
+    default_agent: str | None = None,
+    enable_browser: bool = False,
+    workspace_base: str | None = None,
+    workspace_mount_path: str | None = None,
+):
+    """Create an OpenHandsConfig with common patterns used across evaluation scripts.
+
+    This function provides a standardized way to create OpenHands configurations
+    for evaluation runs, with sensible defaults that match the patterns used in
+    most run_infer.py scripts. Individual evaluation scripts can override specific
+    attributes as needed.
+
+    Args:
+        metadata: EvalMetadata containing agent class, max iterations, etc.
+        sandbox_config: Custom sandbox config. If None, uses get_default_sandbox_config_for_eval()
+        runtime: Runtime type. If None, uses environment RUNTIME or 'docker'
+        max_iterations: Max iterations for the agent. If None, uses metadata.max_iterations
+        default_agent: Agent class name. If None, uses metadata.agent_class
+        enable_browser: Whether to enable browser functionality
+        workspace_base: Workspace base path. Defaults to None
+        workspace_mount_path: Workspace mount path. Defaults to None
+
+    Returns:
+        OpenHandsConfig: Configured for evaluation with eval-specific overrides applied
+    """
+    # Defer import to avoid circular imports at module load time
+    from openhands.core.config.openhands_config import (
+        OpenHandsConfig as _OHConfig,  # type: ignore
+    )
+
+    # Use provided sandbox config or get default
+    if sandbox_config is None:
+        sandbox_config = get_default_sandbox_config_for_eval()
+
+    # Extract values from metadata if provided
+    if metadata is not None:
+        if max_iterations is None:
+            max_iterations = metadata.max_iterations
+        if default_agent is None:
+            default_agent = metadata.agent_class
+
+    # Use environment runtime or default
+    if runtime is None:
+        runtime = os.environ.get('RUNTIME', 'docker')
+
+    # Provide sensible defaults if still None
+    if default_agent is None:
+        default_agent = 'CodeActAgent'
+    if max_iterations is None:
+        max_iterations = 50
+
+    # Always use repo-local .eval_sessions directory (absolute path)
+    eval_store = os.path.abspath(os.path.join(os.getcwd(), '.eval_sessions'))
+
+    # Create the base config with evaluation-specific overrides
+    config = _OHConfig(
+        default_agent=default_agent,
+        run_as_openhands=False,
+        runtime=runtime,
+        max_iterations=max_iterations,
+        enable_browser=enable_browser,
+        sandbox=sandbox_config,
+        workspace_base=workspace_base,
+        workspace_mount_path=workspace_mount_path,
+        file_store='local',
+        file_store_path=eval_store,
+    )
+
+    return config

examples/external_repo_extension.py

@@ -0,0 +1,217 @@
+"""Example of how an external repository can extend OpenHands.
+
+This demonstrates the proper way for external repositories to build upon OpenHands
+without relying on environment variables or global state. The external repo can:
+
+1. Create its own FastAPI app with custom context
+2. Add its own routes and middleware
+3. Include OpenHands routes as needed
+4. Override specific behaviors through dependency injection
+
+This approach eliminates the need for environment variable configuration
+and allows clean separation between OpenHands core and extensions.
+"""
+
+from contextlib import asynccontextmanager
+from typing import AsyncIterator, Optional
+
+from fastapi import Depends, FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from openhands.server.context.server_context import ServerContext
+from openhands.server.factory import create_openhands_app
+
+
+# Step 1: Create your custom ServerContext
+class ExternalRepoContext(ServerContext):
+    """Custom context for external repository with enterprise features."""
+    
+    def __init__(self, tenant_id: str = 'default', user_id: Optional[str] = None):
+        super().__init__()
+        self.tenant_id = tenant_id
+        self.user_id = user_id
+        self._custom_config = None
+    
+    def get_config(self):
+        """Override config with tenant-specific settings."""
+        config = super().get_config()
+        
+        # Add tenant-specific configuration
+        config.update({
+            'tenant_id': self.tenant_id,
+            'custom_storage_path': f'/data/tenants/{self.tenant_id}',
+            'custom_feature_flags': {
+                'enterprise_features': True,
+                'advanced_analytics': True,
+            }
+        })
+        
+        return config
+    
+    def get_server_config(self):
+        """Override server config for enterprise deployment."""
+        server_config = super().get_server_config()
+        
+        # Customize for enterprise
+        server_config.app_mode = 'ENTERPRISE'  # Custom app mode
+        server_config.enable_billing = True
+        server_config.hide_llm_settings = False
+        
+        return server_config
+    
+    def get_file_store(self):
+        """Use tenant-isolated file storage."""
+        # In a real implementation, this would return a tenant-aware file store
+        file_store = super().get_file_store()
+        # Customize file store for tenant isolation
+        return file_store
+
+
+# Step 2: Create your custom lifespan (optional)
+@asynccontextmanager
+async def external_repo_lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """Custom lifespan for external repo initialization."""
+    print("🚀 Starting external repo services...")
+    
+    # Initialize your custom services here
+    # e.g., database connections, external API clients, etc.
+    
+    yield
+    
+    print("🛑 Shutting down external repo services...")
+    # Cleanup your custom services here
+
+
+# Step 3: Create context factory for your needs
+def create_external_context(tenant_id: str = 'default') -> ExternalRepoContext:
+    """Factory function to create context instances."""
+    return ExternalRepoContext(tenant_id=tenant_id)
+
+
+# Step 4: Create your FastAPI app with OpenHands integration
+def create_external_app() -> FastAPI:
+    """Create the external repository's FastAPI application."""
+    
+    # Option A: Create OpenHands app with your custom context
+    openhands_app = create_openhands_app(
+        context_factory=lambda: create_external_context(),
+        include_oss_routes=False,  # Skip OSS routes for enterprise
+        custom_lifespan=external_repo_lifespan,
+        title='My Enterprise Platform',
+        description='Enterprise platform built on OpenHands'
+    )
+    
+    # Option B: Create your own app and mount OpenHands
+    main_app = FastAPI(
+        title='My Enterprise Platform',
+        description='Enterprise platform with OpenHands integration',
+        version='1.0.0'
+    )
+    
+    # Add your custom routes
+    @main_app.get('/enterprise/status')
+    async def enterprise_status():
+        return {'status': 'running', 'mode': 'enterprise'}
+    
+    @main_app.get('/enterprise/tenant/{tenant_id}/info')
+    async def tenant_info(
+        tenant_id: str,
+        request: Request,
+        # Use dependency injection to get context
+        context: ServerContext = Depends(lambda r: create_external_context(tenant_id))
+    ):
+        config = context.get_config()
+        return {
+            'tenant_id': tenant_id,
+            'storage_path': config.get('custom_storage_path'),
+            'features': config.get('custom_feature_flags', {})
+        }
+    
+    # Add custom middleware
+    @main_app.middleware('http')
+    async def tenant_middleware(request: Request, call_next):
+        # Extract tenant from header or path
+        tenant_id = request.headers.get('X-Tenant-ID', 'default')
+        request.state.tenant_id = tenant_id
+        
+        response = await call_next(request)
+        response.headers['X-Tenant-ID'] = tenant_id
+        return response
+    
+    # Mount OpenHands app at a subpath
+    main_app.mount('/openhands', openhands_app)
+    
+    return main_app
+
+
+# Step 5: Alternative approach - extend OpenHands app directly
+def create_extended_openhands_app() -> FastAPI:
+    """Alternative: extend OpenHands app directly with custom routes."""
+    
+    app = create_openhands_app(
+        context_factory=lambda: create_external_context(),
+        custom_lifespan=external_repo_lifespan
+    )
+    
+    # Add your routes to the OpenHands app
+    @app.get('/api/enterprise/dashboard')
+    async def enterprise_dashboard(
+        request: Request,
+        context: ServerContext = Depends(lambda r: create_external_context())
+    ):
+        config = context.get_config()
+        return {
+            'dashboard_data': 'enterprise_metrics',
+            'tenant_features': config.get('custom_feature_flags', {})
+        }
+    
+    return app
+
+
+# Example usage in external repo's main.py
+if __name__ == '__main__':
+    import uvicorn
+    
+    # Choose your approach
+    app = create_external_app()  # Full custom app with OpenHands mounted
+    # app = create_extended_openhands_app()  # Extended OpenHands app
+    
+    # Run the server
+    uvicorn.run(
+        app,
+        host='0.0.0.0',
+        port=8000,
+        reload=True
+    )
+
+
+# Example of how to test the integration
+def test_external_integration():
+    """Test that the external integration works correctly."""
+    from fastapi.testclient import TestClient
+    
+    app = create_external_app()
+    client = TestClient(app)
+    
+    # Test custom routes
+    response = client.get('/enterprise/status')
+    assert response.status_code == 200
+    assert response.json()['mode'] == 'enterprise'
+    
+    # Test tenant-specific routes
+    response = client.get('/enterprise/tenant/acme-corp/info')
+    assert response.status_code == 200
+    data = response.json()
+    assert data['tenant_id'] == 'acme-corp'
+    assert 'enterprise_features' in data['features']
+    
+    # Test OpenHands routes still work
+    response = client.get('/openhands/api/health')
+    assert response.status_code == 200
+    
+    print("✅ All integration tests passed!")
+
+
+if __name__ == '__main__':
+    # Run tests
+    test_external_integration()

frontend/__tests__/components/features/home/repo-connector.test.tsx

@@ -54,12 +54,14 @@ const MOCK_RESPOSITORIES: GitRepository[] = [
     full_name: "rbren/polaris",
     git_provider: "github",
     is_public: true,
+    main_branch: "main",
   },
   {
     id: "2",
     full_name: "All-Hands-AI/OpenHands",
     git_provider: "github",
     is_public: true,
+    main_branch: "main",
   },
 ];
 
@@ -99,16 +101,15 @@ describe("RepoConnector", () => {
 
     // First select the provider
     const providerDropdown = await waitFor(() =>
-      screen.getByText("Select Provider"),
+      screen.getByTestId("git-provider-dropdown"),
     );
     await userEvent.click(providerDropdown);
-    await userEvent.click(screen.getByText("Github"));
+    await userEvent.click(screen.getByText("GitHub"));
 
     // Then interact with the repository dropdown
-    const repoDropdown = await waitFor(() =>
-      screen.getByTestId("repo-dropdown"),
+    const repoInput = await waitFor(() =>
+      screen.getByTestId("git-repo-dropdown"),
     );
-    const repoInput = within(repoDropdown).getByRole("combobox");
     await userEvent.click(repoInput);
 
     // Wait for the options to be loaded and displayed
@@ -134,23 +135,23 @@ describe("RepoConnector", () => {
     expect(launchButton).toBeDisabled();
 
     // Mock the repository branches API call
-    vi.spyOn(OpenHands, "getRepositoryBranches").mockResolvedValue([
+    vi.spyOn(OpenHands, "getRepositoryBranches").mockResolvedValue({ branches: [
       { name: "main", commit_sha: "123", protected: false },
       { name: "develop", commit_sha: "456", protected: false },
-    ]);
+    ], has_next_page: false, current_page: 1, per_page: 30, total_count: 2 });
 
     // First select the provider
     const providerDropdown = await waitFor(() =>
-      screen.getByText("Select Provider"),
+      screen.getByTestId("git-provider-dropdown"),
     );
     await userEvent.click(providerDropdown);
-    await userEvent.click(screen.getByText("Github"));
+    await userEvent.click(screen.getByText("GitHub"));
 
     // Then select the repository
-    const repoDropdown = await waitFor(() =>
-      screen.getByTestId("repo-dropdown"),
+    const repoInput = await waitFor(() =>
+      screen.getByTestId("git-repo-dropdown"),
     );
-    const repoInput = within(repoDropdown).getByRole("combobox");
+
     await userEvent.click(repoInput);
 
     // Wait for the options to be loaded and displayed
@@ -161,7 +162,8 @@ describe("RepoConnector", () => {
 
     // Wait for the branch to be auto-selected
     await waitFor(() => {
-      expect(screen.getByText("main")).toBeInTheDocument();
+      const branchInput = screen.getByTestId("git-branch-dropdown-input");
+      expect(branchInput).toHaveValue("main");
     });
 
     expect(launchButton).toBeEnabled();
@@ -224,6 +226,19 @@ describe("RepoConnector", () => {
 
   it("should create a conversation and redirect with the selected repo when pressing the launch button", async () => {
     const createConversationSpy = vi.spyOn(OpenHands, "createConversation");
+    createConversationSpy.mockResolvedValue({
+      conversation_id: "mock-conversation-id",
+      title: "Test Conversation",
+      selected_repository: "user/repo1",
+      selected_branch: "main",
+      git_provider: "github",
+      last_updated_at: "2023-01-01T00:00:00Z",
+      created_at: "2023-01-01T00:00:00Z",
+      status: "STARTING",
+      runtime_status: null,
+      url: null,
+      session_api_key: null,
+    });
     const retrieveUserGitRepositoriesSpy = vi.spyOn(
       OpenHands,
       "retrieveUserGitRepositories",
@@ -244,23 +259,23 @@ describe("RepoConnector", () => {
     expect(createConversationSpy).not.toHaveBeenCalled();
 
     // Mock the repository branches API call
-    vi.spyOn(OpenHands, "getRepositoryBranches").mockResolvedValue([
+    vi.spyOn(OpenHands, "getRepositoryBranches").mockResolvedValue({ branches: [
       { name: "main", commit_sha: "123", protected: false },
       { name: "develop", commit_sha: "456", protected: false },
-    ]);
+    ], has_next_page: false, current_page: 1, per_page: 30, total_count: 2 });
 
     // First select the provider
     const providerDropdown = await waitFor(() =>
-      screen.getByText("Select Provider"),
+      screen.getByTestId("git-provider-dropdown"),
     );
     await userEvent.click(providerDropdown);
-    await userEvent.click(screen.getByText("Github"));
+    await userEvent.click(screen.getByText("GitHub"));
 
     // Then select the repository
-    const repoDropdown = await waitFor(() =>
-      within(repoConnector).getByTestId("repo-dropdown"),
+    const repoInput = await waitFor(() =>
+      within(repoConnector).getByTestId("git-repo-dropdown"),
     );
-    const repoInput = within(repoDropdown).getByRole("combobox");
+
     await userEvent.click(repoInput);
 
     // Wait for the options to be loaded and displayed
@@ -271,7 +286,8 @@ describe("RepoConnector", () => {
 
     // Wait for the branch to be auto-selected
     await waitFor(() => {
-      expect(screen.getByText("main")).toBeInTheDocument();
+      const branchInput = screen.getByTestId("git-branch-dropdown-input");
+      expect(branchInput).toHaveValue("main");
     });
 
     await userEvent.click(launchButton);
@@ -288,6 +304,8 @@ describe("RepoConnector", () => {
   });
 
   it("should change the launch button text to 'Loading...' when creating a conversation", async () => {
+    const createConversationSpy = vi.spyOn(OpenHands, "createConversation");
+    createConversationSpy.mockImplementation(() => new Promise(() => {})); // Never resolves to keep loading state
     const retrieveUserGitRepositoriesSpy = vi.spyOn(
       OpenHands,
       "retrieveUserGitRepositories",
@@ -298,10 +316,10 @@ describe("RepoConnector", () => {
     });
 
     // Mock the repository branches API call
-    vi.spyOn(OpenHands, "getRepositoryBranches").mockResolvedValue([
+    vi.spyOn(OpenHands, "getRepositoryBranches").mockResolvedValue({ branches: [
       { name: "main", commit_sha: "123", protected: false },
       { name: "develop", commit_sha: "456", protected: false },
-    ]);
+    ], has_next_page: false, current_page: 1, per_page: 30, total_count: 2 });
 
     renderRepoConnector();
 
@@ -309,16 +327,16 @@ describe("RepoConnector", () => {
 
     // First select the provider
     const providerDropdown = await waitFor(() =>
-      screen.getByText("Select Provider"),
+      screen.getByTestId("git-provider-dropdown"),
     );
     await userEvent.click(providerDropdown);
-    await userEvent.click(screen.getByText("Github"));
+    await userEvent.click(screen.getByText("GitHub"));
 
     // Then select the repository
-    const repoDropdown = await waitFor(() =>
-      screen.getByTestId("repo-dropdown"),
+    const repoInput = await waitFor(() =>
+      screen.getByTestId("git-repo-dropdown"),
     );
-    const repoInput = within(repoDropdown).getByRole("combobox");
+
     await userEvent.click(repoInput);
 
     // Wait for the options to be loaded and displayed
@@ -329,7 +347,8 @@ describe("RepoConnector", () => {
 
     // Wait for the branch to be auto-selected
     await waitFor(() => {
-      expect(screen.getByText("main")).toBeInTheDocument();
+      const branchInput = screen.getByTestId("git-branch-dropdown-input");
+      expect(branchInput).toHaveValue("main");
     });
 
     await userEvent.click(launchButton);
@@ -358,7 +377,7 @@ describe("RepoConnector", () => {
     const goToSettingsButton = await screen.findByTestId(
       "navigate-to-settings-button",
     );
-    const dropdown = screen.queryByTestId("repo-dropdown");
+    const dropdown = screen.queryByTestId("git-repo-dropdown");
     const launchButton = screen.queryByTestId("repo-launch-button");
     const providerLinks = screen.queryAllByText(/add git(hub|lab) repos/i);
 

frontend/__tests__/components/features/home/repo-selection-form.test.tsx

@@ -151,7 +151,7 @@ describe("RepositorySelectionForm", () => {
     });
 
     renderForm();
-    expect(await screen.findByTestId("repo-dropdown")).toBeInTheDocument();
+    expect(await screen.findByTestId("git-repo-dropdown")).toBeInTheDocument();
   });
 
   it("shows error message when repository fetch fails", async () => {
@@ -168,10 +168,10 @@ describe("RepositorySelectionForm", () => {
     renderForm();
 
     expect(
-      await screen.findByTestId("repo-dropdown-error"),
+      await screen.findByTestId("dropdown-error"),
     ).toBeInTheDocument();
     expect(
-      screen.getByText("HOME$FAILED_TO_LOAD_REPOSITORIES"),
+      screen.getByText("Failed to load data"),
     ).toBeInTheDocument();
   });
 
@@ -231,11 +231,7 @@ describe("RepositorySelectionForm", () => {
 
     renderForm();
 
-    const dropdown = await screen.findByTestId("repo-dropdown");
-    const input = dropdown.querySelector(
-      'input[type="text"]',
-    ) as HTMLInputElement;
-    expect(input).toBeInTheDocument();
+    const input = await screen.findByTestId("git-repo-dropdown");
 
     await userEvent.type(input, "https://github.com/kubernetes/kubernetes");
     expect(searchGitReposSpy).toHaveBeenLastCalledWith(
@@ -270,11 +266,7 @@ describe("RepositorySelectionForm", () => {
 
     renderForm();
 
-    const dropdown = await screen.findByTestId("repo-dropdown");
-    const input = dropdown.querySelector(
-      'input[type="text"]',
-    ) as HTMLInputElement;
-    expect(input).toBeInTheDocument();
+    const input = await screen.findByTestId("git-repo-dropdown");
 
     await userEvent.type(input, "https://github.com/kubernetes/kubernetes");
     expect(searchGitReposSpy).toHaveBeenLastCalledWith(

frontend/__tests__/routes/home-screen.test.tsx

@@ -37,34 +37,27 @@ const selectRepository = async (repoName: string) => {
 
   // First select the provider
   const providerDropdown = await waitFor(() =>
-    screen.getByText("Select Provider"),
+    screen.getByTestId("git-provider-dropdown"),
   );
   await userEvent.click(providerDropdown);
-  await userEvent.click(screen.getByText("Github"));
+  await userEvent.click(screen.getByText("GitHub"));
 
   // Then select the repository
-  const dropdown = within(repoConnector).getByTestId("repo-dropdown");
-  const repoInput = within(dropdown).getByRole("combobox");
+  const repoInput = within(repoConnector).getByTestId("git-repo-dropdown");
   await userEvent.click(repoInput);
 
   // Wait for the options to be loaded and displayed
   await waitFor(() => {
-    const options = screen.getAllByText(repoName);
-    // Find the option in the dropdown (it will have role="option")
-    const dropdownOption = options.find(
-      (el) => el.getAttribute("role") === "option",
-    );
-    expect(dropdownOption).toBeInTheDocument();
+    const dropdownMenu = screen.getByTestId("git-repo-dropdown-menu");
+    expect(within(dropdownMenu).getByText(repoName)).toBeInTheDocument();
   });
-  const options = screen.getAllByText(repoName);
-  const dropdownOption = options.find(
-    (el) => el.getAttribute("role") === "option",
-  );
-  await userEvent.click(dropdownOption!);
+  const dropdownMenu = screen.getByTestId("git-repo-dropdown-menu");
+  await userEvent.click(within(dropdownMenu).getByText(repoName));
 
   // Wait for the branch to be auto-selected
   await waitFor(() => {
-    expect(screen.getByText("main")).toBeInTheDocument();
+    const branchInput = screen.getByTestId("git-branch-dropdown-input");
+    expect(branchInput).toHaveValue("main");
   });
 };
 
@@ -85,12 +78,14 @@ const MOCK_RESPOSITORIES: GitRepository[] = [
     full_name: "octocat/hello-world",
     git_provider: "github",
     is_public: true,
+    main_branch: "main",
   },
   {
     id: "2",
     full_name: "octocat/earth",
     git_provider: "github",
     is_public: true,
+    main_branch: "main",
   },
 ];
 
@@ -140,10 +135,10 @@ describe("HomeScreen", () => {
         await screen.findAllByTestId("task-launch-button");
 
       // Mock the repository branches API call
-      vi.spyOn(OpenHands, "getRepositoryBranches").mockResolvedValue([
+      vi.spyOn(OpenHands, "getRepositoryBranches").mockResolvedValue({ branches: [
         { name: "main", commit_sha: "123", protected: false },
         { name: "develop", commit_sha: "456", protected: false },
-      ]);
+      ], has_next_page: false, current_page: 1, per_page: 30, total_count: 2 });
 
       // Select a repository to enable the repo launch button
       await selectRepository("octocat/hello-world");

frontend/__tests__/routes/llm-settings.test.tsx

@@ -79,6 +79,35 @@ describe("Content", () => {
         expect(screen.getByTestId("set-indicator")).toBeInTheDocument();
       });
     });
+
+    it("should conditionally show security analyzer based on confirmation mode", async () => {
+      renderLlmSettingsScreen();
+      await screen.findByTestId("llm-settings-screen");
+
+      const confirmation = screen.getByTestId("enable-confirmation-mode-switch");
+
+      // Initially confirmation mode is false, so security analyzer should not be visible
+      expect(confirmation).not.toBeChecked();
+      expect(
+        screen.queryByTestId("security-analyzer-input"),
+      ).not.toBeInTheDocument();
+
+      // Enable confirmation mode
+      await userEvent.click(confirmation);
+      expect(confirmation).toBeChecked();
+
+      // Security analyzer should now be visible
+      screen.getByTestId("security-analyzer-input");
+
+      // Disable confirmation mode again
+      await userEvent.click(confirmation);
+      expect(confirmation).not.toBeChecked();
+
+      // Security analyzer should be hidden again
+      expect(
+        screen.queryByTestId("security-analyzer-input"),
+      ).not.toBeInTheDocument();
+    });
   });
 
   describe("Advanced form", () => {
@@ -107,7 +136,6 @@ describe("Content", () => {
       within(advancedForm).getByTestId("llm-api-key-input");
       within(advancedForm).getByTestId("llm-api-key-help-anchor-advanced");
       within(advancedForm).getByTestId("agent-input");
-      within(advancedForm).getByTestId("enable-confirmation-mode-switch");
       within(advancedForm).getByTestId("enable-memory-condenser-switch");
 
       await userEvent.click(advancedSwitch);
@@ -130,9 +158,6 @@ describe("Content", () => {
       const baseUrl = screen.getByTestId("base-url-input");
       const apiKey = screen.getByTestId("llm-api-key-input");
       const agent = screen.getByTestId("agent-input");
-      const confirmation = screen.getByTestId(
-        "enable-confirmation-mode-switch",
-      );
       const condensor = screen.getByTestId("enable-memory-condenser-switch");
 
       expect(model).toHaveValue("openhands/claude-sonnet-4-20250514");
@@ -140,15 +165,7 @@ describe("Content", () => {
       expect(apiKey).toHaveValue("");
       expect(apiKey).toHaveProperty("placeholder", "");
       expect(agent).toHaveValue("CodeActAgent");
-      expect(confirmation).not.toBeChecked();
       expect(condensor).toBeChecked();
-
-      // check that security analyzer is present
-      expect(
-        screen.queryByTestId("security-analyzer-input"),
-      ).not.toBeInTheDocument();
-      await userEvent.click(confirmation);
-      screen.getByTestId("security-analyzer-input");
     });
 
     it("should render the advanced form if existings settings are advanced", async () => {
@@ -177,7 +194,7 @@ describe("Content", () => {
         agent: "CoActAgent",
         confirmation_mode: true,
         enable_default_condenser: false,
-        security_analyzer: "mock-invariant",
+        security_analyzer: "none",
       });
 
       renderLlmSettingsScreen();
@@ -203,7 +220,7 @@ describe("Content", () => {
         expect(agent).toHaveValue("CoActAgent");
         expect(confirmation).toBeChecked();
         expect(condensor).not.toBeChecked();
-        expect(securityAnalyzer).toHaveValue("mock-invariant");
+        expect(securityAnalyzer).toHaveValue("SETTINGS$SECURITY_ANALYZER_NONE");
       });
     });
   });
@@ -293,7 +310,7 @@ describe("Form submission", () => {
     // select security analyzer
     const securityAnalyzer = screen.getByTestId("security-analyzer-input");
     await userEvent.click(securityAnalyzer);
-    const securityAnalyzerOption = screen.getByText("mock-invariant");
+    const securityAnalyzerOption = screen.getByText("SETTINGS$SECURITY_ANALYZER_NONE");
     await userEvent.click(securityAnalyzerOption);
 
     const submitButton = screen.getByTestId("submit-button");
@@ -306,7 +323,7 @@ describe("Form submission", () => {
         agent: "CoActAgent",
         confirmation_mode: true,
         enable_default_condenser: false,
-        security_analyzer: "mock-invariant",
+        security_analyzer: null,
       }),
     );
   });
@@ -375,9 +392,11 @@ describe("Form submission", () => {
     const baseUrl = await screen.findByTestId("base-url-input");
     const apiKey = await screen.findByTestId("llm-api-key-input");
     const agent = await screen.findByTestId("agent-input");
-    const confirmation = await screen.findByTestId("enable-confirmation-mode-switch");
     const condensor = await screen.findByTestId("enable-memory-condenser-switch");
 
+    // Confirmation mode switch is now in basic settings, always visible
+    const confirmation = await screen.findByTestId("enable-confirmation-mode-switch");
+
     // enter custom model
     await userEvent.type(model, "-mini");
     expect(model).toHaveValue("openai/gpt-4o-mini");
@@ -451,14 +470,17 @@ describe("Form submission", () => {
     // select security analyzer
     const securityAnalyzer = await screen.findByTestId("security-analyzer-input");
     await userEvent.click(securityAnalyzer);
-    const securityAnalyzerOption = screen.getByText("mock-invariant");
+    const securityAnalyzerOption = screen.getByText("SETTINGS$SECURITY_ANALYZER_NONE");
     await userEvent.click(securityAnalyzerOption);
-    expect(securityAnalyzer).toHaveValue("mock-invariant");
+    expect(securityAnalyzer).toHaveValue("SETTINGS$SECURITY_ANALYZER_NONE");
 
     expect(submitButton).not.toBeDisabled();
 
-    await userEvent.clear(securityAnalyzer);
-    expect(securityAnalyzer).toHaveValue("");
+    // revert back to original value
+    await userEvent.click(securityAnalyzer);
+    const originalSecurityAnalyzerOption = screen.getByText("SETTINGS$SECURITY_ANALYZER_LLM_DEFAULT");
+    await userEvent.click(originalSecurityAnalyzerOption);
+    expect(securityAnalyzer).toHaveValue("SETTINGS$SECURITY_ANALYZER_LLM_DEFAULT");
     expect(submitButton).toBeDisabled();
   });
 
@@ -552,7 +574,7 @@ describe("Form submission", () => {
       expect.objectContaining({
         llm_model: "openhands/claude-sonnet-4-20250514",
         llm_base_url: "",
-        confirmation_mode: false,
+        confirmation_mode: true, // Confirmation mode is now a basic setting, should be preserved
       }),
     );
   });

frontend/__tests__/routes/secrets-settings.test.tsx

@@ -107,9 +107,7 @@ describe("Content", () => {
       expect(screen.queryByTestId("add-secret-button")).not.toBeInTheDocument(),
     );
     const button = await screen.findByTestId("connect-git-button");
-    await userEvent.click(button);
-
-    screen.getByTestId("git-settings-screen");
+    expect(button).toHaveAttribute("href", "/settings/integrations");
   });
 
   it("should render an empty table when there are no existing secrets", async () => {

frontend/__tests__/utils/has-advanced-settings-set.test.ts

@@ -29,23 +29,5 @@ describe("hasAdvancedSettingsSet", () => {
         }),
       ).toBe(true);
     });
-
-    test("CONFIRMATION_MODE is true", () => {
-      expect(
-        hasAdvancedSettingsSet({
-          ...DEFAULT_SETTINGS,
-          CONFIRMATION_MODE: true,
-        }),
-      ).toBe(true);
-    });
-
-    test("SECURITY_ANALYZER is set", () => {
-      expect(
-        hasAdvancedSettingsSet({
-          ...DEFAULT_SETTINGS,
-          SECURITY_ANALYZER: "test",
-        }),
-      ).toBe(true);
-    });
   });
 });

frontend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openhands-frontend",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "private": true,
   "type": "module",
   "engines": {
@@ -11,50 +11,50 @@
     "@heroui/use-infinite-scroll": "^2.2.10",
     "@microlink/react-json-view": "^1.26.2",
     "@monaco-editor/react": "^4.7.0-rc.0",
-    "@react-router/node": "^7.8.0",
-    "@react-router/serve": "^7.8.0",
-    "@react-types/shared": "^3.31.0",
+    "@react-router/node": "^7.8.2",
+    "@react-router/serve": "^7.8.2",
+    "@react-types/shared": "^3.32.0",
     "@reduxjs/toolkit": "^2.8.2",
-    "@stripe/react-stripe-js": "^3.9.0",
-    "@stripe/stripe-js": "^7.8.0",
+    "@stripe/react-stripe-js": "^3.9.2",
+    "@stripe/stripe-js": "^7.9.0",
     "@tailwindcss/postcss": "^4.1.12",
     "@tailwindcss/vite": "^4.1.12",
-    "@tanstack/react-query": "^5.85.3",
+    "@tanstack/react-query": "^5.85.5",
     "@uidotdev/usehooks": "^2.4.1",
-    "@vitejs/plugin-react": "^5.0.0",
+    "@vitejs/plugin-react": "^5.0.2",
     "@xterm/addon-fit": "^0.10.0",
     "@xterm/xterm": "^5.4.0",
     "axios": "^1.11.0",
     "clsx": "^2.1.1",
     "date-fns": "^4.1.0",
+    "downshift": "^9.0.10",
     "eslint-config-airbnb-typescript": "^18.0.0",
     "framer-motion": "^12.23.12",
-    "i18next": "^25.3.6",
+    "i18next": "^25.4.2",
     "i18next-browser-languagedetector": "^8.2.0",
     "i18next-http-backend": "^3.0.2",
-    "isbot": "^5.1.29",
-    "jose": "^6.0.12",
-    "lucide-react": "^0.539.0",
+    "isbot": "^5.1.30",
+    "jose": "^6.1.0",
+    "lucide-react": "^0.542.0",
     "monaco-editor": "^0.52.2",
-    "posthog-js": "^1.260.1",
+    "posthog-js": "^1.261.0",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
     "react-highlight": "^0.15.0",
-    "react-hot-toast": "^2.5.1",
-    "react-i18next": "^15.6.1",
+    "react-hot-toast": "^2.6.0",
+    "react-i18next": "^15.7.2",
     "react-icons": "^5.5.0",
     "react-markdown": "^10.1.0",
     "react-redux": "^9.2.0",
-    "react-router": "^7.8.0",
-    "react-select": "^5.10.2",
-    "react-syntax-highlighter": "^15.6.1",
+    "react-router": "^7.8.2",
+    "react-syntax-highlighter": "^15.6.6",
     "react-textarea-autosize": "^8.5.9",
     "remark-breaks": "^4.0.0",
     "remark-gfm": "^4.0.1",
     "sirv-cli": "^3.0.1",
     "socket.io-client": "^4.8.1",
     "tailwind-merge": "^3.3.1",
-    "vite": "^7.1.1",
+    "vite": "^7.1.3",
     "web-vitals": "^5.1.0",
     "ws": "^8.18.2"
   },
@@ -88,17 +88,17 @@
     "@babel/traverse": "^7.28.3",
     "@babel/types": "^7.28.2",
     "@mswjs/socket.io-binding": "^0.2.0",
-    "@playwright/test": "^1.54.2",
-    "@react-router/dev": "^7.8.0",
+    "@playwright/test": "^1.55.0",
+    "@react-router/dev": "^7.8.2",
     "@tailwindcss/typography": "^0.5.16",
     "@tanstack/eslint-plugin-query": "^5.83.1",
     "@testing-library/dom": "^10.4.1",
-    "@testing-library/jest-dom": "^6.7.0",
+    "@testing-library/jest-dom": "^6.8.0",
     "@testing-library/react": "^16.3.0",
     "@testing-library/user-event": "^14.6.1",
-    "@types/node": "^24.2.0",
-    "@types/react": "^19.1.9",
-    "@types/react-dom": "^19.1.7",
+    "@types/node": "^24.3.0",
+    "@types/react": "^19.1.12",
+    "@types/react-dom": "^19.1.9",
     "@types/react-highlight": "^0.12.8",
     "@types/react-syntax-highlighter": "^15.5.13",
     "@types/ws": "^8.18.1",
@@ -117,16 +117,16 @@
     "eslint-plugin-prettier": "^5.5.4",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^4.6.2",
-    "eslint-plugin-unused-imports": "^4.1.4",
+    "eslint-plugin-unused-imports": "^4.2.0",
     "husky": "^9.1.7",
     "jsdom": "^26.1.0",
     "lint-staged": "^16.1.4",
     "msw": "^2.6.6",
     "prettier": "^3.6.2",
-    "stripe": "^18.4.0",
+    "stripe": "^18.5.0",
     "tailwindcss": "^4.1.8",
     "typescript": "^5.9.2",
-    "vite-plugin-svgr": "^4.2.0",
+    "vite-plugin-svgr": "^4.5.0",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.0.2"
   },

frontend/src/api/open-hands.ts

@@ -21,11 +21,17 @@ import {
 } from "./open-hands.types";
 import { openHands } from "./open-hands-axios";
 import { ApiSettings, PostApiSettings, Provider } from "#/types/settings";
-import { GitUser, GitRepository, Branch } from "#/types/git";
+import {
+  GitUser,
+  GitRepository,
+  PaginatedBranchesResponse,
+  Branch,
+} from "#/types/git";
 import { SuggestedTask } from "#/components/features/home/tasks/task.types";
 import { extractNextPageFromLink } from "#/utils/extract-next-page-from-link";
 import { RepositoryMicroagent } from "#/types/microagent-management";
 import { BatchFeedbackData } from "#/hooks/query/use-batch-feedback";
+import { SubscriptionAccess } from "#/types/billing";
 
 class OpenHands {
   private static currentConversation: Conversation | null = null;
@@ -428,6 +434,13 @@ class OpenHands {
     return data.credits;
   }
 
+  static async getSubscriptionAccess(): Promise<SubscriptionAccess | null> {
+    const { data } = await openHands.get<SubscriptionAccess | null>(
+      "/api/billing/subscription-access",
+    );
+    return data;
+  }
+
   static async getGitUser(): Promise<GitUser> {
     const response = await openHands.get<GitUser>("/api/user/info");
 
@@ -567,14 +580,38 @@ class OpenHands {
     };
   }
 
-  static async getRepositoryBranches(repository: string): Promise<Branch[]> {
-    const { data } = await openHands.get<Branch[]>(
-      `/api/user/repository/branches?repository=${encodeURIComponent(repository)}`,
+  static async getRepositoryBranches(
+    repository: string,
+    page: number = 1,
+    perPage: number = 30,
+  ): Promise<PaginatedBranchesResponse> {
+    const { data } = await openHands.get<PaginatedBranchesResponse>(
+      `/api/user/repository/branches?repository=${encodeURIComponent(repository)}&page=${page}&per_page=${perPage}`,
     );
 
     return data;
   }
 
+  static async searchRepositoryBranches(
+    repository: string,
+    query: string,
+    perPage: number = 30,
+    selectedProvider?: Provider,
+  ): Promise<Branch[]> {
+    const { data } = await openHands.get<Branch[]>(
+      `/api/user/search/branches`,
+      {
+        params: {
+          repository,
+          query,
+          per_page: perPage,
+          selected_provider: selectedProvider,
+        },
+      },
+    );
+    return data;
+  }
+
   /**
    * Get the available microagents associated with a conversation
    * @param conversationId The ID of the conversation
@@ -726,6 +763,27 @@ class OpenHands {
     );
     return data;
   }
+
+  static async getMicroagentManagementConversations(
+    selectedRepository: string,
+    pageId?: string,
+    limit: number = 100,
+  ): Promise<Conversation[]> {
+    const params: Record<string, string | number> = {
+      limit,
+      selected_repository: selectedRepository,
+    };
+
+    if (pageId) {
+      params.page_id = pageId;
+    }
+
+    const { data } = await openHands.get<ResultSet<Conversation>>(
+      "/api/microagent-management/conversations",
+      { params },
+    );
+    return data.results;
+  }
 }
 
 export default OpenHands;

frontend/src/api/open-hands.types.ts

@@ -49,13 +49,11 @@ export interface GetConfigResponse {
   APP_SLUG?: string;
   GITHUB_CLIENT_ID: string;
   POSTHOG_CLIENT_KEY: string;
-  STRIPE_PUBLISHABLE_KEY?: string;
   PROVIDERS_CONFIGURED?: Provider[];
   AUTH_URL?: string;
   FEATURE_FLAGS: {
     ENABLE_BILLING: boolean;
     HIDE_LLM_SETTINGS: boolean;
-    HIDE_MICROAGENT_MANAGEMENT?: boolean;
     ENABLE_JIRA: boolean;
     ENABLE_JIRA_DC: boolean;
     ENABLE_LINEAR: boolean;

frontend/src/components/common/git-branch-dropdown.tsx

@@ -1,69 +0,0 @@
-import { useMemo } from "react";
-import { useRepositoryBranches } from "../../hooks/query/use-repository-branches";
-import { ReactSelectDropdown, SelectOption } from "./react-select-dropdown";
-
-export interface GitBranchDropdownProps {
-  repositoryName?: string | null;
-  value?: string | null;
-  placeholder?: string;
-  className?: string;
-  errorMessage?: string;
-  disabled?: boolean;
-  onChange?: (branchName: string | null) => void;
-}
-
-export function GitBranchDropdown({
-  repositoryName,
-  value,
-  placeholder = "Select branch...",
-  className,
-  errorMessage,
-  disabled = false,
-  onChange,
-}: GitBranchDropdownProps) {
-  const { data: branches, isLoading } = useRepositoryBranches(
-    repositoryName || null,
-  );
-
-  const options: SelectOption[] = useMemo(
-    () =>
-      branches?.map((branch) => ({
-        value: branch.name,
-        label: branch.name,
-      })) || [],
-    [branches],
-  );
-
-  const hasNoBranches = !isLoading && branches && branches.length === 0;
-
-  const selectedOption = useMemo(
-    () => options.find((option) => option.value === value) || null,
-    [options, value],
-  );
-
-  const handleChange = (option: SelectOption | null) => {
-    onChange?.(option?.value || null);
-  };
-
-  const isDisabled = disabled || !repositoryName || isLoading || hasNoBranches;
-
-  const displayPlaceholder = hasNoBranches ? "No branches found" : placeholder;
-  const displayErrorMessage = hasNoBranches
-    ? "This repository has no branches"
-    : errorMessage;
-
-  return (
-    <ReactSelectDropdown
-      options={options}
-      value={selectedOption}
-      placeholder={displayPlaceholder}
-      className={className}
-      errorMessage={displayErrorMessage}
-      disabled={isDisabled}
-      isClearable={false}
-      isSearchable
-      isLoading={isLoading}
-      onChange={handleChange}
-    />
-  );
-}

frontend/src/components/common/git-provider-dropdown.tsx

@@ -1,58 +0,0 @@
-import { useMemo } from "react";
-import { Provider } from "../../types/settings";
-import { ReactSelectDropdown, SelectOption } from "./react-select-dropdown";
-
-export interface GitProviderDropdownProps {
-  providers: Provider[];
-  value?: Provider | null;
-  placeholder?: string;
-  className?: string;
-  errorMessage?: string;
-  disabled?: boolean;
-  isLoading?: boolean;
-  onChange?: (provider: Provider | null) => void;
-}
-
-export function GitProviderDropdown({
-  providers,
-  value,
-  placeholder = "Select Provider",
-  className,
-  errorMessage,
-  disabled = false,
-  isLoading = false,
-  onChange,
-}: GitProviderDropdownProps) {
-  const options: SelectOption[] = useMemo(
-    () =>
-      providers.map((provider) => ({
-        value: provider,
-        label: provider.charAt(0).toUpperCase() + provider.slice(1),
-      })),
-    [providers],
-  );
-
-  const selectedOption = useMemo(
-    () => options.find((option) => option.value === value) || null,
-    [options, value],
-  );
-
-  const handleChange = (option: SelectOption | null) => {
-    onChange?.(option?.value as Provider | null);
-  };
-
-  return (
-    <ReactSelectDropdown
-      options={options}
-      value={selectedOption}
-      placeholder={placeholder}
-      className={className}
-      errorMessage={errorMessage}
-      disabled={disabled}
-      isClearable={false}
-      isSearchable={false}
-      isLoading={isLoading}
-      onChange={handleChange}
-    />
-  );
-}

frontend/src/components/common/git-repository-dropdown.tsx

@@ -1,208 +0,0 @@
-import { useCallback, useMemo, useState } from "react";
-import { useTranslation } from "react-i18next";
-import { Provider } from "../../types/settings";
-import { useGitRepositories } from "../../hooks/query/use-git-repositories";
-import { useSearchRepositories } from "../../hooks/query/use-search-repositories";
-import { useDebounce } from "../../hooks/use-debounce";
-import OpenHands from "../../api/open-hands";
-import { GitRepository } from "../../types/git";
-import {
-  ReactSelectAsyncDropdown,
-  AsyncSelectOption,
-} from "./react-select-async-dropdown";
-
-export interface GitRepositoryDropdownProps {
-  provider: Provider;
-  value?: string | null;
-  placeholder?: string;
-  className?: string;
-  errorMessage?: string;
-  disabled?: boolean;
-  onChange?: (repository?: GitRepository) => void;
-}
-
-export function GitRepositoryDropdown({
-  provider,
-  value,
-  placeholder = "Search repositories...",
-  className,
-  errorMessage,
-  disabled = false,
-  onChange,
-}: GitRepositoryDropdownProps) {
-  const { t } = useTranslation();
-  const [searchInput, setSearchInput] = useState("");
-  const debouncedSearchInput = useDebounce(searchInput, 300);
-
-  // Process search input to handle URLs
-  const processedSearchInput = useMemo(() => {
-    if (debouncedSearchInput.startsWith("https://")) {
-      const match = debouncedSearchInput.match(
-        /https:\/\/[^/]+\/([^/]+\/[^/]+)/,
-      );
-      return match ? match[1] : debouncedSearchInput;
-    }
-    return debouncedSearchInput;
-  }, [debouncedSearchInput]);
-
-  const {
-    data,
-    fetchNextPage,
-    hasNextPage,
-    isLoading,
-    isFetchingNextPage,
-    isError,
-  } = useGitRepositories({
-    provider,
-    enabled: !disabled,
-  });
-
-  // Search query for processed input (handles URLs)
-  const { data: searchData, isLoading: isSearchLoading } =
-    useSearchRepositories(processedSearchInput, provider);
-
-  const allOptions: AsyncSelectOption[] = useMemo(
-    () =>
-      data?.pages
-        ? data.pages.flatMap((page) =>
-            page.data.map((repo) => ({
-              value: repo.id,
-              label: repo.full_name,
-            })),
-          )
-        : [],
-    [data],
-  );
-
-  const searchOptions: AsyncSelectOption[] = useMemo(
-    () =>
-      searchData
-        ? searchData.map((repo) => ({
-            value: repo.id,
-            label: repo.full_name,
-          }))
-        : [],
-    [searchData],
-  );
-
-  const selectedOption = useMemo(() => {
-    // First check in loaded pages
-    const option = allOptions.find((opt) => opt.value === value);
-    if (option) return option;
-
-    // If not found, check in search results
-    const searchOption = searchOptions.find((opt) => opt.value === value);
-    if (searchOption) return searchOption;
-
-    return null;
-  }, [allOptions, searchOptions, value]);
-
-  const loadOptions = useCallback(
-    async (inputValue: string): Promise<AsyncSelectOption[]> => {
-      // Update search input to trigger debounced search
-      setSearchInput(inputValue);
-
-      // If empty input, show all loaded options
-      if (!inputValue.trim()) {
-        return allOptions;
-      }
-
-      // For very short inputs, do local filtering
-      if (inputValue.length < 2) {
-        return allOptions.filter((option) =>
-          option.label.toLowerCase().includes(inputValue.toLowerCase()),
-        );
-      }
-
-      // Handle URL inputs by performing direct search
-      if (inputValue.startsWith("https://")) {
-        const match = inputValue.match(/https:\/\/[^/]+\/([^/]+\/[^/]+)/);
-        if (match) {
-          const repoName = match[1];
-          try {
-            // Perform direct search for URL-based inputs
-            const repositories = await OpenHands.searchGitRepositories(
-              repoName,
-              3,
-              provider,
-            );
-            return repositories.map((repo) => ({
-              value: repo.full_name,
-              label: repo.full_name,
-              data: repo,
-            }));
-          } catch (error) {
-            // Fall back to local filtering if search fails
-            return allOptions.filter((option) =>
-              option.label.toLowerCase().includes(repoName.toLowerCase()),
-            );
-          }
-        }
-      }
-
-      // For regular text inputs, use hook-based search results if available
-      if (searchOptions.length > 0 && processedSearchInput === inputValue) {
-        return searchOptions;
-      }
-
-      // Fallback to local filtering while search is loading
-      return allOptions.filter((option) =>
-        option.label.toLowerCase().includes(inputValue.toLowerCase()),
-      );
-    },
-    [allOptions, searchOptions, processedSearchInput, provider],
-  );
-
-  const handleChange = (option: AsyncSelectOption | null) => {
-    if (!option) {
-      onChange?.(undefined);
-      return;
-    }
-
-    // First check in loaded pages
-    let repo = data?.pages
-      ?.flatMap((p) => p.data)
-      .find((r) => r.id === option.value);
-
-    // If not found, check in search results
-    if (!repo) {
-      repo = searchData?.find((r) => r.id === option.value);
-    }
-
-    onChange?.(repo);
-  };
-
-  const handleMenuScrollToBottom = useCallback(() => {
-    if (hasNextPage && !isFetchingNextPage && !isLoading) {
-      fetchNextPage();
-    }
-  }, [hasNextPage, isFetchingNextPage, isLoading, fetchNextPage]);
-
-  return (
-    <>
-      <ReactSelectAsyncDropdown
-        testId="repo-dropdown"
-        loadOptions={loadOptions}
-        value={selectedOption}
-        placeholder={placeholder}
-        className={className}
-        errorMessage={errorMessage}
-        disabled={disabled}
-        isClearable={false}
-        isLoading={isLoading || isFetchingNextPage || isSearchLoading}
-        cacheOptions
-        defaultOptions={allOptions}
-        onChange={handleChange}
-        onMenuScrollToBottom={handleMenuScrollToBottom}
-      />
-      {isError && (
-        <div
-          data-testid="repo-dropdown-error"
-          className="text-red-500 text-sm mt-1"
-        >
-          {t("HOME$FAILED_TO_LOAD_REPOSITORIES")}
-        </div>
-      )}
-    </>
-  );
-}

frontend/src/components/common/react-select-async-dropdown.tsx

@@ -1,79 +0,0 @@
-import { useCallback, useMemo } from "react";
-import AsyncSelect from "react-select/async";
-import { cn } from "#/utils/utils";
-import { SelectOptionBase, getCustomStyles } from "./react-select-styles";
-
-export type AsyncSelectOption = SelectOptionBase;
-
-export interface ReactSelectAsyncDropdownProps {
-  loadOptions: (inputValue: string) => Promise<AsyncSelectOption[]>;
-  testId?: string;
-  placeholder?: string;
-  value?: AsyncSelectOption | null;
-  defaultValue?: AsyncSelectOption | null;
-  className?: string;
-  errorMessage?: string;
-  disabled?: boolean;
-  isClearable?: boolean;
-  isLoading?: boolean;
-  cacheOptions?: boolean;
-  defaultOptions?: boolean | AsyncSelectOption[];
-  onChange?: (option: AsyncSelectOption | null) => void;
-  onMenuScrollToBottom?: () => void;
-}
-
-export function ReactSelectAsyncDropdown({
-  loadOptions,
-  testId,
-  placeholder = "Search...",
-  value,
-  defaultValue,
-  className,
-  errorMessage,
-  disabled = false,
-  isClearable = false,
-  isLoading = false,
-  cacheOptions = true,
-  defaultOptions = true,
-  onChange,
-  onMenuScrollToBottom,
-}: ReactSelectAsyncDropdownProps) {
-  const customStyles = useMemo(() => getCustomStyles<AsyncSelectOption>(), []);
-
-  const handleLoadOptions = useCallback(
-    (inputValue: string, callback: (options: AsyncSelectOption[]) => void) => {
-      loadOptions(inputValue)
-        .then((options) => callback(options))
-        .catch(() => callback([]));
-    },
-    [loadOptions],
-  );
-
-  return (
-    <div data-testid={testId} className={cn("w-full", className)}>
-      <AsyncSelect
-        loadOptions={handleLoadOptions}
-        value={value}
-        defaultValue={defaultValue}
-        placeholder={placeholder}
-        isDisabled={disabled}
-        isClearable={isClearable}
-        isLoading={isLoading}
-        cacheOptions={cacheOptions}
-        defaultOptions={defaultOptions}
-        onChange={onChange}
-        onMenuScrollToBottom={onMenuScrollToBottom}
-        styles={customStyles}
-        className="w-full"
-      />
-      {errorMessage && (
-        <p
-          data-testid="repo-dropdown-error"
-          className="text-red-500 text-sm mt-1"
-        >
-          {errorMessage}
-        </p>
-      )}
-    </div>
-  );
-}

frontend/src/components/common/react-select-dropdown.tsx

@@ -1,57 +0,0 @@
-import { useMemo } from "react";
-import Select from "react-select";
-import { cn } from "#/utils/utils";
-import { SelectOptionBase, getCustomStyles } from "./react-select-styles";
-
-export type SelectOption = SelectOptionBase;
-
-export interface ReactSelectDropdownProps {
-  options: SelectOption[];
-  placeholder?: string;
-  value?: SelectOption | null;
-  defaultValue?: SelectOption | null;
-  className?: string;
-  errorMessage?: string;
-  disabled?: boolean;
-  isClearable?: boolean;
-  isSearchable?: boolean;
-  isLoading?: boolean;
-  onChange?: (option: SelectOption | null) => void;
-}
-
-export function ReactSelectDropdown({
-  options,
-  placeholder = "Select option...",
-  value,
-  defaultValue,
-  className,
-  errorMessage,
-  disabled = false,
-  isClearable = false,
-  isSearchable = true,
-  isLoading = false,
-  onChange,
-}: ReactSelectDropdownProps) {
-  const customStyles = useMemo(() => getCustomStyles<SelectOption>(), []);
-
-  return (
-    <div className={cn("w-full", className)}>
-      <Select
-        options={options}
-        value={value}
-        defaultValue={defaultValue}
-        placeholder={placeholder}
-        isDisabled={disabled}
-        isClearable={isClearable}
-        isSearchable={isSearchable}
-        isLoading={isLoading}
-        onChange={onChange}
-        styles={customStyles}
-        className="w-full"
-      />
-      {errorMessage && (
-        <p className="text-red-500 text-sm mt-1">{errorMessage}</p>
-      )}
-    </div>
-  );
-}

frontend/src/components/common/react-select-styles.ts

@@ -1,92 +0,0 @@
-import { StylesConfig } from "react-select";
-
-export interface SelectOptionBase {
-  value: string;
-  label: string;
-}
-
-export const getCustomStyles = <T extends SelectOptionBase>(): StylesConfig<
-  T,
-  false
-> => ({
-  control: (provided, state) => ({
-    ...provided,
-    backgroundColor: state.isDisabled ? "#363636" : "#454545", // darker tertiary when disabled
-    border: "1px solid #717888",
-    borderRadius: "0.125rem",
-    minHeight: "2.5rem",
-    padding: "0 0.5rem",
-    boxShadow: state.isFocused ? "0 0 0 1px #717888" : "none",
-    opacity: state.isDisabled ? 0.6 : 1,
-    cursor: state.isDisabled ? "not-allowed" : "pointer",
-    "&:hover": {
-      borderColor: "#717888",
-    },
-  }),
-  input: (provided) => ({
-    ...provided,
-    color: "#ECEDEE", // content
-  }),
-  placeholder: (provided) => ({
-    ...provided,
-    fontStyle: "italic",
-    color: "#B7BDC2", // tertiary-light
-  }),
-  singleValue: (provided, state) => ({
-    ...provided,
-    color: state.isDisabled ? "#B7BDC2" : "#ECEDEE", // tertiary-light when disabled, content otherwise
-  }),
-  menu: (provided) => ({
-    ...provided,
-    backgroundColor: "#454545", // tertiary
-    border: "1px solid #717888",
-    borderRadius: "0.75rem",
-    overflow: "hidden", // ensure menu items don't overflow rounded corners
-  }),
-  menuList: (provided) => ({
-    ...provided,
-    padding: "0.25rem", // add some padding around menu items
-  }),
-  option: (provided, state) => {
-    let backgroundColor = "transparent";
-    if (state.isSelected) {
-      backgroundColor = "#C9B974"; // primary for selected
-    } else if (state.isFocused) {
-      backgroundColor = "#24272E"; // base-secondary for hover/focus
-    }
-
-    return {
-      ...provided,
-      backgroundColor,
-      color: state.isSelected ? "#000000" : "#ECEDEE", // black text on yellow, white on gray
-      borderRadius: "0.5rem", // rounded menu items
-      margin: "0.125rem 0", // small gap between items
-      "&:hover": {
-        backgroundColor: state.isSelected ? "#C9B974" : "#24272E", // keep yellow if selected, else gray
-        color: state.isSelected ? "#000000" : "#ECEDEE", // maintain text color on hover
-      },
-      "&:active": {
-        backgroundColor: state.isSelected ? "#C9B974" : "#24272E",
-        color: state.isSelected ? "#000000" : "#ECEDEE",
-      },
-    };
-  },
-  clearIndicator: (provided) => ({
-    ...provided,
-    color: "#B7BDC2", // tertiary-light
-    "&:hover": {
-      color: "#ECEDEE", // content
-    },
-  }),
-  dropdownIndicator: (provided) => ({
-    ...provided,
-    color: "#B7BDC2", // tertiary-light
-    "&:hover": {
-      color: "#ECEDEE", // content
-    },
-  }),
-  loadingIndicator: (provided) => ({
-    ...provided,
-    color: "#B7BDC2", // tertiary-light
-  }),
-});

frontend/src/components/features/chat/chat-message.tsx

@@ -9,6 +9,7 @@ import { CopyToClipboardButton } from "#/components/shared/buttons/copy-to-clipb
 import { anchor } from "../markdown/anchor";
 import { OpenHandsSourceType } from "#/types/core/base";
 import { paragraph } from "../markdown/paragraph";
+import { TooltipButton } from "#/components/shared/buttons/tooltip-button";
 
 interface ChatMessageProps {
   type: OpenHandsSourceType;
@@ -16,6 +17,7 @@ interface ChatMessageProps {
   actions?: Array<{
     icon: React.ReactNode;
     onClick: () => void;
+    tooltip?: string;
   }>;
 }
 
@@ -66,17 +68,35 @@ export function ChatMessage({
           "items-center gap-1",
         )}
       >
-        {actions?.map((action, index) => (
-          <button
-            key={index}
-            type="button"
-            onClick={action.onClick}
-            className="button-base p-1 cursor-pointer"
-            aria-label={`Action ${index + 1}`}
-          >
-            {action.icon}
-          </button>
-        ))}
+        {actions?.map((action, index) =>
+          action.tooltip ? (
+            <TooltipButton
+              key={index}
+              tooltip={action.tooltip}
+              ariaLabel={action.tooltip}
+              placement="top"
+            >
+              <button
+                type="button"
+                onClick={action.onClick}
+                className="button-base p-1 cursor-pointer"
+                aria-label={`Action ${index + 1}`}
+              >
+                {action.icon}
+              </button>
+            </TooltipButton>
+          ) : (
+            <button
+              key={index}
+              type="button"
+              onClick={action.onClick}
+              className="button-base p-1 cursor-pointer"
+              aria-label={`Action ${index + 1}`}
+            >
+              {action.icon}
+            </button>
+          ),
+        )}
 
         <CopyToClipboardButton
           isHidden={!isHovering}

frontend/src/components/features/chat/event-content-helpers/get-observation-content.ts

@@ -72,6 +72,9 @@ const getRecallObservationContent = (event: RecallObservation): string => {
     if (event.extras.repo_instructions) {
       content += `\n\n**Repository Instructions:**\n\n${event.extras.repo_instructions}`;
     }
+    if (event.extras.conversation_instructions) {
+      content += `\n\n**Conversation Instructions:**\n\n${event.extras.conversation_instructions}`;
+    }
     if (event.extras.additional_agent_instructions) {
       content += `\n\n**Additional Instructions:**\n\n${event.extras.additional_agent_instructions}`;
     }

frontend/src/components/features/chat/event-message.tsx

@@ -46,6 +46,7 @@ interface EventMessageProps {
   actions?: Array<{
     icon: React.ReactNode;
     onClick: () => void;
+    tooltip?: string;
   }>;
   isInLast10Actions: boolean;
 }

frontend/src/components/features/chat/messages.tsx

@@ -1,4 +1,5 @@
 import React from "react";
+import { useTranslation } from "react-i18next";
 import { createPortal } from "react-dom";
 import { OpenHandsAction } from "#/types/core/actions";
 import { OpenHandsObservation } from "#/types/core/observations";
@@ -24,6 +25,17 @@ import { AgentState } from "#/types/agent-state";
 import { getFirstPRUrl } from "#/utils/parse-pr-url";
 import MemoryIcon from "#/icons/memory_icon.svg?react";
 
+const isErrorEvent = (evt: unknown): evt is { error: true; message: string } =>
+  typeof evt === "object" &&
+  evt !== null &&
+  "error" in evt &&
+  evt.error === true;
+
+const isAgentStatusError = (evt: unknown): boolean =>
+  isOpenHandsEvent(evt) &&
+  isAgentStateChangeObservation(evt) &&
+  evt.extras.agent_state === AgentState.ERROR;
+
 interface MessagesProps {
   messages: (OpenHandsAction | OpenHandsObservation)[];
   isAwaitingUserConfirmation: boolean;
@@ -31,8 +43,11 @@ interface MessagesProps {
 
 export const Messages: React.FC<MessagesProps> = React.memo(
   ({ messages, isAwaitingUserConfirmation }) => {
-    const { createConversationAndSubscribe, isPending } =
-      useCreateConversationAndSubscribeMultiple();
+    const {
+      createConversationAndSubscribe,
+      isPending,
+      unsubscribeFromConversation,
+    } = useCreateConversationAndSubscribeMultiple();
     const { getOptimisticUserMessage } = useOptimisticUserMessage();
     const { conversationId } = useConversationId();
     const { data: conversation } = useUserConversation(conversationId);
@@ -48,6 +63,8 @@ export const Messages: React.FC<MessagesProps> = React.memo(
       EventMicroagentStatus[]
     >([]);
 
+    const { t } = useTranslation();
+
     const actionHasObservationPair = React.useCallback(
       (event: OpenHandsAction | OpenHandsObservation): boolean => {
         if (isOpenHandsAction(event)) {
@@ -93,20 +110,6 @@ export const Messages: React.FC<MessagesProps> = React.memo(
 
     const handleMicroagentEvent = React.useCallback(
       (socketEvent: unknown, microagentConversationId: string) => {
-        // Handle error events
-        const isErrorEvent = (
-          evt: unknown,
-        ): evt is { error: true; message: string } =>
-          typeof evt === "object" &&
-          evt !== null &&
-          "error" in evt &&
-          evt.error === true;
-
-        const isAgentStatusError = (evt: unknown): boolean =>
-          isOpenHandsEvent(evt) &&
-          isAgentStateChangeObservation(evt) &&
-          evt.extras.agent_state === AgentState.ERROR;
-
         if (isErrorEvent(socketEvent) || isAgentStatusError(socketEvent)) {
           setMicroagentStatuses((prev) =>
             prev.map((statusEntry) =>
@@ -119,7 +122,11 @@ export const Messages: React.FC<MessagesProps> = React.memo(
           isOpenHandsEvent(socketEvent) &&
           isAgentStateChangeObservation(socketEvent)
         ) {
-          if (socketEvent.extras.agent_state === AgentState.FINISHED) {
+          // Handle completion states
+          if (
+            socketEvent.extras.agent_state === AgentState.FINISHED ||
+            socketEvent.extras.agent_state === AgentState.AWAITING_USER_INPUT
+          ) {
             setMicroagentStatuses((prev) =>
               prev.map((statusEntry) =>
                 statusEntry.conversationId === microagentConversationId
@@ -127,6 +134,8 @@ export const Messages: React.FC<MessagesProps> = React.memo(
                   : statusEntry,
               ),
             );
+
+            unsubscribeFromConversation(microagentConversationId);
           }
         } else if (
           isOpenHandsEvent(socketEvent) &&
@@ -147,9 +156,27 @@ export const Messages: React.FC<MessagesProps> = React.memo(
               ),
             );
           }
+
+          unsubscribeFromConversation(microagentConversationId);
+        } else {
+          // For any other event, transition from WAITING to CREATING if still waiting
+          setMicroagentStatuses((prev) => {
+            const currentStatus = prev.find(
+              (entry) => entry.conversationId === microagentConversationId,
+            )?.status;
+
+            if (currentStatus === MicroagentStatus.WAITING) {
+              return prev.map((statusEntry) =>
+                statusEntry.conversationId === microagentConversationId
+                  ? { ...statusEntry, status: MicroagentStatus.CREATING }
+                  : statusEntry,
+              );
+            }
+            return prev; // No change needed
+          });
         }
       },
-      [setMicroagentStatuses],
+      [setMicroagentStatuses, unsubscribeFromConversation],
     );
 
     const handleLaunchMicroagent = (
@@ -178,13 +205,13 @@ export const Messages: React.FC<MessagesProps> = React.memo(
         },
         onSuccessCallback: (newConversationId: string) => {
           setShowLaunchMicroagentModal(false);
-          // Update status with conversation ID
+          // Update status with conversation ID - start with WAITING
           setMicroagentStatuses((prev) => [
             ...prev.filter((status) => status.eventId !== selectedEventId),
             {
               eventId: selectedEventId,
               conversationId: newConversationId,
-              status: MicroagentStatus.CREATING,
+              status: MicroagentStatus.WAITING,
             },
           ]);
         },
@@ -219,6 +246,7 @@ export const Messages: React.FC<MessagesProps> = React.memo(
                         setSelectedEventId(message.id);
                         setShowLaunchMicroagentModal(true);
                       },
+                      tooltip: t("MICROAGENT$ADD_TO_MEMORY"),
                     },
                   ]
                 : undefined

frontend/src/components/features/chat/microagent/launch-microagent-modal.tsx

@@ -76,6 +76,10 @@ export function LaunchMicroagentModal({
             </button>
           </div>
 
+          <span className="text-sm text-[#A3A3A3] font-normal leading-5">
+            {t("MICROAGENT$DEFINITION")}
+          </span>
+
           <form
             data-testid="launch-microagent-modal"
             onSubmit={onSubmit}

frontend/src/components/features/chat/microagent/microagent-status-indicator.tsx

@@ -19,6 +19,8 @@ export function MicroagentStatusIndicator({
 
   const getStatusText = () => {
     switch (status) {
+      case MicroagentStatus.WAITING:
+        return t("MICROAGENT$STATUS_WAITING");
       case MicroagentStatus.CREATING:
         return t("MICROAGENT$STATUS_CREATING");
       case MicroagentStatus.COMPLETED:
@@ -35,6 +37,8 @@ export function MicroagentStatusIndicator({
 
   const getStatusIcon = () => {
     switch (status) {
+      case MicroagentStatus.WAITING:
+        return <Spinner size="sm" />;
       case MicroagentStatus.CREATING:
         return <Spinner size="sm" />;
       case MicroagentStatus.COMPLETED:

frontend/src/components/features/chat/microagent/microagent-status-toast.tsx

@@ -10,6 +10,11 @@ interface ConversationCreatedToastProps {
   onClose: () => void;
 }
 
+interface ConversationStartingToastProps {
+  conversationId: string;
+  onClose: () => void;
+}
+
 function ConversationCreatedToast({
   conversationId,
   onClose,
@@ -37,6 +42,33 @@ function ConversationCreatedToast({
   );
 }
 
+function ConversationStartingToast({
+  conversationId,
+  onClose,
+}: ConversationStartingToastProps) {
+  const { t } = useTranslation();
+  return (
+    <div className="flex items-start gap-2">
+      <Spinner size="sm" />
+      <div>
+        {t("MICROAGENT$CONVERSATION_STARTING")}
+        <br />
+        <a
+          href={`/conversations/${conversationId}`}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="underline"
+        >
+          {t("MICROAGENT$VIEW_CONVERSATION")}
+        </a>
+      </div>
+      <button type="button" onClick={onClose}>
+        <CloseIcon />
+      </button>
+    </div>
+  );
+}
+
 interface ConversationFinishedToastProps {
   conversationId: string;
   onClose: () => void;
@@ -78,10 +110,18 @@ function ConversationErroredToast({
   errorMessage,
   onClose,
 }: ConversationErroredToastProps) {
+  const { t } = useTranslation();
+
+  // Check if the error message is a translation key
+  const displayMessage =
+    errorMessage === "MICROAGENT$UNKNOWN_ERROR"
+      ? t(errorMessage)
+      : errorMessage;
+
   return (
     <div className="flex items-start gap-2">
       <SuccessIndicator status="error" />
-      <div>{errorMessage}</div>
+      <div>{displayMessage}</div>
       <button type="button" onClick={onClose}>
         <CloseIcon />
       </button>
@@ -136,3 +176,18 @@ export const renderConversationErroredToast = (
       duration: 5000,
     },
   );
+
+export const renderConversationStartingToast = (conversationId: string) =>
+  toast(
+    (toastInstance) => (
+      <ConversationStartingToast
+        conversationId={conversationId}
+        onClose={() => toast.dismiss(toastInstance.id)}
+      />
+    ),
+    {
+      ...TOAST_OPTIONS,
+      id: `starting-${conversationId}`,
+      duration: 10000, // Show for 10 seconds or until dismissed
+    },
+  );

frontend/src/components/features/controls/controls.tsx

@@ -7,11 +7,10 @@ import { ConversationCard } from "../conversation-panel/conversation-card";
 import { Provider } from "#/types/settings";
 
 interface ControlsProps {
-  setSecurityOpen: (isOpen: boolean) => void;
   showSecurityLock: boolean;
 }
 
-export function Controls({ setSecurityOpen, showSecurityLock }: ControlsProps) {
+export function Controls({ showSecurityLock }: ControlsProps) {
   const { data: conversation } = useActiveConversation();
   const [contextMenuOpen, setContextMenuOpen] = React.useState(false);
 
@@ -21,9 +20,7 @@ export function Controls({ setSecurityOpen, showSecurityLock }: ControlsProps) {
         <AgentControlBar />
         <AgentStatusBar />
 
-        {showSecurityLock && (
-          <SecurityLock onClick={() => setSecurityOpen(true)} />
-        )}
+        {showSecurityLock && <SecurityLock />}
       </div>
 
       <ConversationCard

frontend/src/components/features/controls/security-lock.tsx

@@ -1,17 +1,28 @@
 import { IoLockClosed } from "react-icons/io5";
+import { Tooltip } from "@heroui/react";
+import { useTranslation } from "react-i18next";
+import { Link } from "react-router";
+import { I18nKey } from "#/i18n/declaration";
 
-interface SecurityLockProps {
-  onClick: () => void;
-}
+export function SecurityLock() {
+  const { t } = useTranslation();
 
-export function SecurityLock({ onClick }: SecurityLockProps) {
   return (
-    <div
-      className="cursor-pointer hover:opacity-80 transition-all"
-      style={{ marginRight: "8px" }}
-      onClick={onClick}
+    <Tooltip
+      content={
+        <div className="max-w-xs p-2">
+          {t(I18nKey.SETTINGS$CONFIRMATION_MODE_LOCK_TOOLTIP)}
+        </div>
+      }
+      placement="top"
     >
-      <IoLockClosed size={20} />
-    </div>
+      <Link
+        to="/settings"
+        className="mr-2 cursor-pointer hover:opacity-80 transition-all"
+        aria-label={t(I18nKey.SETTINGS$TITLE)}
+      >
+        <IoLockClosed size={20} />
+      </Link>
+    </Tooltip>
   );
 }

frontend/src/components/features/conversation-panel/confirm-stop-modal.tsx

@@ -23,9 +23,9 @@ export function ConfirmStopModal({
     <ModalBackdrop>
       <ModalBody className="items-start border border-tertiary">
         <div className="flex flex-col gap-2">
-          <BaseModalTitle title={t(I18nKey.CONVERSATION$CONFIRM_STOP)} />
+          <BaseModalTitle title={t(I18nKey.CONVERSATION$CONFIRM_PAUSE)} />
           <BaseModalDescription
-            description={t(I18nKey.CONVERSATION$STOP_WARNING)}
+            description={t(I18nKey.CONVERSATION$PAUSE_WARNING)}
           />
         </div>
         <div

frontend/src/components/features/conversation-panel/conversation-card-context-menu.tsx

@@ -129,7 +129,7 @@ export function ConversationCardContextMenu({
 
       {onStop && (
         <ContextMenuListItem testId="stop-button" onClick={onStop}>
-          <ContextMenuIconText icon={Power} text={t(I18nKey.BUTTON$STOP)} />
+          <ContextMenuIconText icon={Power} text={t(I18nKey.BUTTON$PAUSE)} />
         </ContextMenuListItem>
       )}
 

frontend/src/components/features/conversation-panel/conversation-state-indicator.tsx

@@ -1,4 +1,6 @@
 import { ConversationStatus } from "#/types/conversation-status";
+import ArchivedIcon from "./state-indicators/archived.svg?react";
+import ErrorIcon from "./state-indicators/error.svg?react";
 import RunningIcon from "./state-indicators/running.svg?react";
 import StartingIcon from "./state-indicators/starting.svg?react";
 import StoppedIcon from "./state-indicators/stopped.svg?react";
@@ -9,6 +11,8 @@ const CONVERSATION_STATUS_INDICATORS: Record<ConversationStatus, SVGIcon> = {
   STOPPED: StoppedIcon,
   RUNNING: RunningIcon,
   STARTING: StartingIcon,
+  ARCHIVED: ArchivedIcon,
+  ERROR: ErrorIcon,
 };
 
 interface ConversationStateIndicatorProps {

frontend/src/components/features/conversation-panel/state-indicators/archived.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 0 24 24" width="24px" fill="#A7A9AC"><path d="M0 0h24v24H0V0z" fill="none"/><path d="M17 7h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1 0 1.43-.98 2.63-2.31 2.98l1.46 1.46C20.88 15.61 22 13.95 22 12c0-2.76-2.24-5-5-5zm-1 4h-2.19l2 2H16zM2 4.27l3.11 3.11C3.29 8.12 2 9.91 2 12c0 2.76 2.24 5 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1 0-1.59 1.21-2.9 2.76-3.07L8.73 11H8v2h2.73L13 15.27V17h1.73l4.01 4L20 19.74 3.27 3 2 4.27z"/><path d="M0 24V0" fill="none"/></svg>

frontend/src/components/features/conversation-panel/state-indicators/error.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 0 24 24" width="24px" fill="#e7000b"><path d="M0 0h24v24H0z" fill="none"/><path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 15h-2v-2h2v2zm0-4h-2V7h2v6z"/></svg>

frontend/src/components/features/home/git-branch-dropdown/branch-dropdown-menu.tsx

@@ -0,0 +1,86 @@
+import React from "react";
+import {
+  UseComboboxGetMenuPropsOptions,
+  UseComboboxGetItemPropsOptions,
+} from "downshift";
+import { Branch } from "#/types/git";
+import { DropdownItem } from "../shared/dropdown-item";
+import { GenericDropdownMenu, EmptyState } from "../shared";
+
+export interface BranchDropdownMenuProps {
+  isOpen: boolean;
+  filteredBranches: Branch[];
+  inputValue: string;
+  highlightedIndex: number;
+  selectedItem: Branch | null;
+  getMenuProps: <Options>(
+    options?: UseComboboxGetMenuPropsOptions & Options,
+  ) => any; // eslint-disable-line @typescript-eslint/no-explicit-any
+  getItemProps: <Options>(
+    options: UseComboboxGetItemPropsOptions<Branch> & Options,
+  ) => any; // eslint-disable-line @typescript-eslint/no-explicit-any
+  onScroll: (event: React.UIEvent<HTMLUListElement>) => void;
+  menuRef: React.RefObject<HTMLUListElement | null>;
+}
+
+export function BranchDropdownMenu({
+  isOpen,
+  filteredBranches,
+  inputValue,
+  highlightedIndex,
+  selectedItem,
+  getMenuProps,
+  getItemProps,
+  onScroll,
+  menuRef,
+}: BranchDropdownMenuProps) {
+  const renderItem = (
+    branch: Branch,
+    index: number,
+    currentHighlightedIndex: number,
+    currentSelectedItem: Branch | null,
+    currentGetItemProps: <Options>(
+      options: UseComboboxGetItemPropsOptions<Branch> & Options,
+    ) => any, // eslint-disable-line @typescript-eslint/no-explicit-any
+  ) => (
+    <DropdownItem
+      key={branch.name}
+      item={branch}
+      index={index}
+      isHighlighted={currentHighlightedIndex === index}
+      isSelected={currentSelectedItem?.name === branch.name}
+      getItemProps={currentGetItemProps}
+      getDisplayText={(branchItem) => branchItem.name}
+      getItemKey={(branchItem) => branchItem.name}
+    />
+  );
+
+  const renderEmptyState = (currentInputValue: string) => (
+    <li className="px-3 py-2">
+      <EmptyState
+        inputValue={currentInputValue}
+        searchMessage="No branches found"
+        emptyMessage="No branches available"
+        testId="git-branch-dropdown-empty"
+      />
+    </li>
+  );
+
+  return (
+    <div data-testid="git-branch-dropdown-menu">
+      <GenericDropdownMenu
+        isOpen={isOpen}
+        filteredItems={filteredBranches}
+        inputValue={inputValue}
+        highlightedIndex={highlightedIndex}
+        selectedItem={selectedItem}
+        getMenuProps={getMenuProps}
+        getItemProps={getItemProps}
+        onScroll={onScroll}
+        menuRef={menuRef}
+        renderItem={renderItem}
+        renderEmptyState={renderEmptyState}
+      />
+    </div>
+  );
+}