'
+ )
+ return HTMLResponse(
+ content=content,
+ status_code=status_code,
+ )
diff --git a/enterprise/server/routes/mcp_patch.py b/enterprise/server/routes/mcp_patch.py
new file mode 100644
index 0000000000..a131a986d0
--- /dev/null
+++ b/enterprise/server/routes/mcp_patch.py
@@ -0,0 +1,32 @@
+import os
+
+from fastmcp import Client, FastMCP
+from fastmcp.client.transports import NpxStdioTransport
+
+from openhands.core.logger import openhands_logger as logger
+from openhands.server.routes.mcp import mcp_server
+
+ENABLE_MCP_SEARCH_ENGINE = (
+ os.getenv('ENABLE_MCP_SEARCH_ENGINE', 'false').lower() == 'true'
+)
+
+
+def patch_mcp_server():
+ if not ENABLE_MCP_SEARCH_ENGINE:
+ logger.warning('Tavily search integration is disabled')
+ return
+
+ TAVILY_API_KEY = os.getenv('TAVILY_API_KEY')
+
+ if TAVILY_API_KEY:
+ proxy_client = Client(
+ transport=NpxStdioTransport(
+ package='tavily-mcp@0.2.1', env_vars={'TAVILY_API_KEY': TAVILY_API_KEY}
+ )
+ )
+ proxy_server = FastMCP.as_proxy(proxy_client)
+
+ mcp_server.mount(prefix='tavily', server=proxy_server)
+ logger.info('Tavily search integration initialized successfully')
+ else:
+ logger.warning('Tavily API key not found, skipping search integration')
diff --git a/enterprise/server/routes/readiness.py b/enterprise/server/routes/readiness.py
new file mode 100644
index 0000000000..3bb981d586
--- /dev/null
+++ b/enterprise/server/routes/readiness.py
@@ -0,0 +1,35 @@
+from fastapi import APIRouter, HTTPException, status
+from sqlalchemy.sql import text
+from storage.database import session_maker
+from storage.redis import create_redis_client
+
+from openhands.core.logger import openhands_logger as logger
+
+readiness_router = APIRouter()
+
+
+@readiness_router.get('/ready')
+def is_ready():
+ # Check database connection
+ try:
+ with session_maker() as session:
+ session.execute(text('SELECT 1'))
+ except Exception as e:
+ logger.error(f'Database check failed: {str(e)}')
+ raise HTTPException(
+ status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+ detail=f'Database is not accessible: {str(e)}',
+ )
+
+ # Check Redis connection
+ try:
+ redis_client = create_redis_client()
+ redis_client.ping()
+ except Exception as e:
+ logger.error(f'Redis check failed: {str(e)}')
+ raise HTTPException(
+ status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+ detail=f'Redis cache is not accessible: {str(e)}',
+ )
+
+ return 'OK'
diff --git a/enterprise/server/routes/user.py b/enterprise/server/routes/user.py
new file mode 100644
index 0000000000..9ba37b36e4
--- /dev/null
+++ b/enterprise/server/routes/user.py
@@ -0,0 +1,378 @@
+from typing import Any
+
+from fastapi import APIRouter, Depends, Query, status
+from fastapi.responses import JSONResponse
+from pydantic import SecretStr
+from server.auth.token_manager import TokenManager
+
+from openhands.integrations.provider import (
+ PROVIDER_TOKEN_TYPE,
+)
+from openhands.integrations.service_types import (
+ Branch,
+ PaginatedBranchesResponse,
+ ProviderType,
+ Repository,
+ SuggestedTask,
+ User,
+)
+from openhands.microagent.types import (
+ MicroagentContentResponse,
+ MicroagentResponse,
+)
+from openhands.server.dependencies import get_dependencies
+from openhands.server.routes.git import (
+ get_repository_branches,
+ get_repository_microagent_content,
+ get_repository_microagents,
+ get_suggested_tasks,
+ get_user,
+ get_user_installations,
+ get_user_repositories,
+ search_branches,
+ search_repositories,
+)
+from openhands.server.user_auth import (
+ get_access_token,
+ get_provider_tokens,
+ get_user_id,
+)
+
+saas_user_router = APIRouter(prefix='/api/user', dependencies=get_dependencies())
+token_manager = TokenManager()
+
+
+@saas_user_router.get('/installations', response_model=list[str])
+async def saas_get_user_installations(
+ provider: ProviderType,
+ provider_tokens: PROVIDER_TOKEN_TYPE | None = Depends(get_provider_tokens),
+ access_token: SecretStr | None = Depends(get_access_token),
+ user_id: str | None = Depends(get_user_id),
+):
+ if not provider_tokens:
+ retval = await _check_idp(
+ access_token=access_token,
+ default_value=[],
+ )
+ if retval is not None:
+ return retval
+
+ return await get_user_installations(
+ provider=provider,
+ provider_tokens=provider_tokens,
+ access_token=access_token,
+ user_id=user_id,
+ )
+
+
+@saas_user_router.get('/repositories', response_model=list[Repository])
+async def saas_get_user_repositories(
+ sort: str = 'pushed',
+ selected_provider: ProviderType | None = None,
+ page: int | None = None,
+ per_page: int | None = None,
+ installation_id: str | None = None,
+ provider_tokens: PROVIDER_TOKEN_TYPE | None = Depends(get_provider_tokens),
+ access_token: SecretStr | None = Depends(get_access_token),
+ user_id: str | None = Depends(get_user_id),
+) -> list[Repository] | JSONResponse:
+ if not provider_tokens:
+ retval = await _check_idp(
+ access_token=access_token,
+ default_value=[],
+ )
+ if retval is not None:
+ return retval
+
+ return await get_user_repositories(
+ sort=sort,
+ selected_provider=selected_provider,
+ page=page,
+ per_page=per_page,
+ installation_id=installation_id,
+ provider_tokens=provider_tokens,
+ access_token=access_token,
+ user_id=user_id,
+ )
+
+
+@saas_user_router.get('/info', response_model=User)
+async def saas_get_user(
+ provider_tokens: PROVIDER_TOKEN_TYPE | None = Depends(get_provider_tokens),
+ access_token: SecretStr | None = Depends(get_access_token),
+ user_id: str | None = Depends(get_user_id),
+) -> User | JSONResponse:
+ if not provider_tokens:
+ if not access_token:
+ return JSONResponse(
+ content='User is not authenticated.',
+ status_code=status.HTTP_401_UNAUTHORIZED,
+ )
+ user_info = await token_manager.get_user_info(access_token.get_secret_value())
+ if not user_info:
+ return JSONResponse(
+ content='Failed to retrieve user_info.',
+ status_code=status.HTTP_401_UNAUTHORIZED,
+ )
+ retval = await _check_idp(
+ access_token=access_token,
+ default_value=User(
+ id=(user_info.get('sub') if user_info else '') or '',
+ login=(user_info.get('preferred_username') if user_info else '') or '',
+ avatar_url='',
+ email=user_info.get('email') if user_info else None,
+ ),
+ user_info=user_info,
+ )
+ if retval is not None:
+ return retval
+
+ return await get_user(
+ provider_tokens=provider_tokens, access_token=access_token, user_id=user_id
+ )
+
+
+@saas_user_router.get('/search/repositories', response_model=list[Repository])
+async def saas_search_repositories(
+ query: str,
+ per_page: int = 5,
+ sort: str = 'stars',
+ order: str = 'desc',
+ provider_tokens: PROVIDER_TOKEN_TYPE | None = Depends(get_provider_tokens),
+ access_token: SecretStr | None = Depends(get_access_token),
+ user_id: str | None = Depends(get_user_id),
+) -> list[Repository] | JSONResponse:
+ if not provider_tokens:
+ retval = await _check_idp(
+ access_token=access_token,
+ default_value=[],
+ )
+ if retval is not None:
+ return retval
+
+ return await search_repositories(
+ query=query,
+ per_page=per_page,
+ sort=sort,
+ order=order,
+ provider_tokens=provider_tokens,
+ access_token=access_token,
+ user_id=user_id,
+ )
+
+
+@saas_user_router.get('/suggested-tasks', response_model=list[SuggestedTask])
+async def saas_get_suggested_tasks(
+ provider_tokens: PROVIDER_TOKEN_TYPE | None = Depends(get_provider_tokens),
+ access_token: SecretStr | None = Depends(get_access_token),
+ user_id: str | None = Depends(get_user_id),
+) -> list[SuggestedTask] | JSONResponse:
+ """Get suggested tasks for the authenticated user across their most recently pushed repositories.
+
+ Returns:
+ - PRs owned by the user
+ - Issues assigned to the user.
+ """
+ if not provider_tokens:
+ retval = await _check_idp(
+ access_token=access_token,
+ default_value=[],
+ )
+ if retval is not None:
+ return retval
+
+ return await get_suggested_tasks(
+ provider_tokens=provider_tokens, access_token=access_token, user_id=user_id
+ )
+
+
+@saas_user_router.get('/repository/branches', response_model=PaginatedBranchesResponse)
+async def saas_get_repository_branches(
+ repository: str,
+ page: int = 1,
+ per_page: int = 30,
+ provider_tokens: PROVIDER_TOKEN_TYPE | None = Depends(get_provider_tokens),
+ access_token: SecretStr | None = Depends(get_access_token),
+ user_id: str | None = Depends(get_user_id),
+) -> PaginatedBranchesResponse | JSONResponse:
+ """Get branches for a repository.
+
+ Args:
+ repository: The repository name in the format 'owner/repo'
+
+ Returns:
+ A list of branches for the repository
+ """
+ if not provider_tokens:
+ retval = await _check_idp(
+ access_token=access_token,
+ default_value=[],
+ )
+ if retval is not None:
+ return retval
+
+ return await get_repository_branches(
+ repository=repository,
+ page=page,
+ per_page=per_page,
+ provider_tokens=provider_tokens,
+ access_token=access_token,
+ user_id=user_id,
+ )
+
+
+@saas_user_router.get('/search/branches', response_model=list[Branch])
+async def saas_search_branches(
+ repository: str,
+ query: str,
+ per_page: int = 30,
+ selected_provider: ProviderType | None = None,
+ provider_tokens: PROVIDER_TOKEN_TYPE | None = Depends(get_provider_tokens),
+ access_token: SecretStr | None = Depends(get_access_token),
+ user_id: str | None = Depends(get_user_id),
+) -> list[Branch] | JSONResponse:
+ if not provider_tokens:
+ retval = await _check_idp(
+ access_token=access_token,
+ default_value=[],
+ )
+ if retval is not None:
+ return retval
+
+ return await search_branches(
+ repository=repository,
+ query=query,
+ per_page=per_page,
+ selected_provider=selected_provider,
+ provider_tokens=provider_tokens,
+ access_token=access_token,
+ user_id=user_id,
+ )
+
+
+@saas_user_router.get(
+ '/repository/{repository_name:path}/microagents',
+ response_model=list[MicroagentResponse],
+)
+async def saas_get_repository_microagents(
+ repository_name: str,
+ provider_tokens: PROVIDER_TOKEN_TYPE | None = Depends(get_provider_tokens),
+ access_token: SecretStr | None = Depends(get_access_token),
+ user_id: str | None = Depends(get_user_id),
+) -> list[MicroagentResponse] | JSONResponse:
+ """Scan the microagents directory of a repository and return the list of microagents.
+
+ The microagents directory location depends on the git provider and actual repository name:
+ - If git provider is not GitLab and actual repository name is ".openhands": scans "microagents" folder
+ - If git provider is GitLab and actual repository name is "openhands-config": scans "microagents" folder
+ - Otherwise: scans ".openhands/microagents" folder
+
+ Note: This API returns microagent metadata without content for performance.
+ Use the separate content API to fetch individual microagent content.
+
+ Args:
+ repository_name: Repository name in the format 'owner/repo' or 'domain/owner/repo'
+ provider_tokens: Provider tokens for authentication
+ access_token: Access token for external authentication
+ user_id: User ID for authentication
+
+ Returns:
+ List of microagents found in the repository's microagents directory (without content)
+ """
+ if not provider_tokens:
+ retval = await _check_idp(
+ access_token=access_token,
+ default_value=[],
+ )
+ if retval is not None:
+ return retval
+
+ return await get_repository_microagents(
+ repository_name=repository_name,
+ provider_tokens=provider_tokens,
+ access_token=access_token,
+ user_id=user_id,
+ )
+
+
+@saas_user_router.get(
+ '/repository/{repository_name:path}/microagents/content',
+ response_model=MicroagentContentResponse,
+)
+async def saas_get_repository_microagent_content(
+ repository_name: str,
+ file_path: str = Query(
+ ..., description='Path to the microagent file within the repository'
+ ),
+ provider_tokens: PROVIDER_TOKEN_TYPE | None = Depends(get_provider_tokens),
+ access_token: SecretStr | None = Depends(get_access_token),
+ user_id: str | None = Depends(get_user_id),
+) -> MicroagentContentResponse | JSONResponse:
+ """Fetch the content of a specific microagent file from a repository.
+
+ Args:
+ repository_name: Repository name in the format 'owner/repo' or 'domain/owner/repo'
+ file_path: Query parameter - Path to the microagent file within the repository
+ provider_tokens: Provider tokens for authentication
+ access_token: Access token for external authentication
+ user_id: User ID for authentication
+
+ Returns:
+ Microagent file content and metadata
+
+ Example:
+ GET /api/user/repository/owner/repo/microagents/content?file_path=.openhands/microagents/my-agent.md
+ """
+ if not provider_tokens:
+ retval = await _check_idp(
+ access_token=access_token,
+ default_value=MicroagentContentResponse(content='', path=''),
+ )
+ if retval is not None:
+ return retval
+
+ return await get_repository_microagent_content(
+ repository_name=repository_name,
+ file_path=file_path,
+ provider_tokens=provider_tokens,
+ access_token=access_token,
+ user_id=user_id,
+ )
+
+
+async def _check_idp(
+ access_token: SecretStr | None,
+ default_value: Any,
+ user_info: dict | None = None,
+):
+ if not access_token:
+ return JSONResponse(
+ content='User is not authenticated.',
+ status_code=status.HTTP_401_UNAUTHORIZED,
+ )
+ user_info = (
+ user_info
+ if user_info
+ else await token_manager.get_user_info(access_token.get_secret_value())
+ )
+ if not user_info:
+ return JSONResponse(
+ content='Failed to retrieve user_info.',
+ status_code=status.HTTP_401_UNAUTHORIZED,
+ )
+ idp: str | None = user_info.get('identity_provider')
+ if not idp:
+ return JSONResponse(
+ content='IDP not found.',
+ status_code=status.HTTP_401_UNAUTHORIZED,
+ )
+ if ':' in idp:
+ idp, _ = idp.rsplit(':', 1)
+
+ # Will return empty dict if IDP doesn't support provider tokens
+ if not await token_manager.get_idp_tokens_from_keycloak(
+ access_token.get_secret_value(), ProviderType(idp)
+ ):
+ return default_value
+
+ return None
diff --git a/enterprise/server/saas_monitoring_listener.py b/enterprise/server/saas_monitoring_listener.py
new file mode 100644
index 0000000000..1b687f04c8
--- /dev/null
+++ b/enterprise/server/saas_monitoring_listener.py
@@ -0,0 +1,75 @@
+from prometheus_client import Counter, Histogram
+from server.logger import logger
+
+from openhands.core.config.openhands_config import OpenHandsConfig
+from openhands.core.schema.agent import AgentState
+from openhands.events.event import Event
+from openhands.events.observation import (
+ AgentStateChangedObservation,
+)
+from openhands.server.monitoring import MonitoringListener
+
+AGENT_STATUS_ERROR_COUNT = Counter(
+ 'saas_agent_status_errors', 'Agent Status change events to status error'
+)
+CREATE_CONVERSATION_COUNT = Counter(
+ 'saas_create_conversation', 'Create conversation attempts'
+)
+AGENT_SESSION_START_HISTOGRAM = Histogram(
+ 'saas_agent_session_start',
+ 'AgentSession starts with success and duration',
+ labelnames=['success'],
+)
+
+
+class SaaSMonitoringListener(MonitoringListener):
+ """
+ Forward app signals to Prometheus.
+ """
+
+ def on_session_event(self, event: Event) -> None:
+ """
+ Track metrics about events being added to a Session's EventStream.
+ """
+ if (
+ isinstance(event, AgentStateChangedObservation)
+ and event.agent_state == AgentState.ERROR
+ ):
+ AGENT_STATUS_ERROR_COUNT.inc()
+ logger.info(
+ 'Tracking agent status error',
+ extra={'signal': 'saas_agent_status_errors'},
+ )
+
+ def on_agent_session_start(self, success: bool, duration: float) -> None:
+ """
+ Track an agent session start.
+ Success is true if startup completed without error.
+ Duration is start time in seconds observed by AgentSession.
+ """
+ AGENT_SESSION_START_HISTOGRAM.labels(success=success).observe(duration)
+ logger.info(
+ 'Tracking agent session start',
+ extra={
+ 'signal': 'saas_agent_session_start',
+ 'success': success,
+ 'duration': duration,
+ },
+ )
+
+ def on_create_conversation(self) -> None:
+ """
+ Track the beginning of conversation creation.
+ Does not currently capture whether it succeed.
+ """
+ CREATE_CONVERSATION_COUNT.inc()
+ logger.info(
+ 'Tracking create conversation', extra={'signal': 'saas_create_conversation'}
+ )
+
+ @classmethod
+ def get_instance(
+ cls,
+ config: OpenHandsConfig,
+ ) -> 'SaaSMonitoringListener':
+ return cls()
diff --git a/enterprise/server/saas_nested_conversation_manager.py b/enterprise/server/saas_nested_conversation_manager.py
new file mode 100644
index 0000000000..1f1af3045b
--- /dev/null
+++ b/enterprise/server/saas_nested_conversation_manager.py
@@ -0,0 +1,960 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from enum import Enum
+from types import MappingProxyType
+from typing import Any, cast
+
+import httpx
+import socketio
+from server.constants import PERMITTED_CORS_ORIGINS, WEB_HOST
+from server.utils.conversation_callback_utils import (
+ process_event,
+ update_conversation_metadata,
+)
+from sqlalchemy import orm
+from storage.api_key_store import ApiKeyStore
+from storage.database import session_maker
+from storage.stored_conversation_metadata import StoredConversationMetadata
+
+from openhands.controller.agent import Agent
+from openhands.core.config import LLMConfig, OpenHandsConfig
+from openhands.core.config.mcp_config import MCPConfig, MCPSHTTPServerConfig
+from openhands.core.logger import openhands_logger as logger
+from openhands.events.action import MessageAction
+from openhands.events.event_store import EventStore
+from openhands.events.serialization.event import event_to_dict
+from openhands.integrations.provider import PROVIDER_TOKEN_TYPE, ProviderHandler
+from openhands.runtime.impl.remote.remote_runtime import RemoteRuntime
+from openhands.runtime.runtime_status import RuntimeStatus
+from openhands.server.config.server_config import ServerConfig
+from openhands.server.constants import ROOM_KEY
+from openhands.server.conversation_manager.conversation_manager import (
+ ConversationManager,
+)
+from openhands.server.data_models.agent_loop_info import AgentLoopInfo
+from openhands.server.monitoring import MonitoringListener
+from openhands.server.session import Session
+from openhands.server.session.conversation import ServerConversation
+from openhands.server.session.conversation_init_data import ConversationInitData
+from openhands.storage.conversation.conversation_store import ConversationStore
+from openhands.storage.data_models.conversation_metadata import ConversationMetadata
+from openhands.storage.data_models.conversation_status import ConversationStatus
+from openhands.storage.data_models.settings import Settings
+from openhands.storage.files import FileStore
+from openhands.storage.locations import (
+ get_conversation_event_filename,
+ get_conversation_events_dir,
+)
+from openhands.utils.async_utils import call_sync_from_async
+from openhands.utils.import_utils import get_impl
+from openhands.utils.shutdown_listener import should_continue
+from openhands.utils.utils import create_registry_and_conversation_stats
+
+# Pattern for accessing runtime pods externally
+RUNTIME_URL_PATTERN = os.getenv(
+ 'RUNTIME_URL_PATTERN', 'https://{runtime_id}.prod-runtime.all-hands.dev'
+)
+
+# Pattern for base URL for the runtime
+RUNTIME_CONVERSATION_URL = RUNTIME_URL_PATTERN + '/api/conversations/{conversation_id}'
+
+# Time in seconds before a Redis entry is considered expired if not refreshed
+_REDIS_ENTRY_TIMEOUT_SECONDS = 300
+
+# Time in seconds between pulls
+_POLLING_INTERVAL = 10
+
+# Timeout for http operations
+_HTTP_TIMEOUT = 15
+
+
+class EventRetrieval(Enum):
+ """Determine mode for getting events out of the nested runtime back into the main app."""
+
+ WEBHOOK_PUSH = 'WEBHOOK_PUSH'
+ POLLING = 'POLLING'
+ NONE = 'NONE'
+
+
+@dataclass
+class SaasNestedConversationManager(ConversationManager):
+ """Conversation manager where the agent loops exist inside the remote containers."""
+
+ sio: socketio.AsyncServer
+ config: OpenHandsConfig
+ server_config: ServerConfig
+ file_store: FileStore
+ event_retrieval: EventRetrieval
+ _conversation_store_class: type[ConversationStore] | None = None
+ _event_polling_task: asyncio.Task | None = None
+ _runtime_container_image: str | None = None
+
+ async def __aenter__(self):
+ if self.event_retrieval == EventRetrieval.POLLING:
+ self._event_polling_task = asyncio.create_task(self._poll_events())
+ return self
+
+ async def __aexit__(self, exc_type, exc_value, traceback):
+ if self._event_polling_task:
+ self._event_polling_task.cancel()
+ self._event_polling_task = None
+
+ async def attach_to_conversation(
+ self, sid: str, user_id: str | None = None
+ ) -> ServerConversation | None:
+ # Not supported - clients should connect directly to the nested server!
+ raise ValueError('unsupported_operation')
+
+ async def detach_from_conversation(self, conversation: ServerConversation):
+ # Not supported - clients should connect directly to the nested server!
+ raise ValueError('unsupported_operation')
+
+ async def join_conversation(
+ self,
+ sid: str,
+ connection_id: str,
+ settings: Settings,
+ user_id: str | None,
+ ) -> AgentLoopInfo:
+ # Not supported - clients should connect directly to the nested server!
+ raise ValueError('unsupported_operation')
+
+ def get_agent_session(self, sid: str):
+ raise ValueError('unsupported_operation')
+
+ async def get_running_agent_loops(
+ self, user_id: str | None = None, filter_to_sids: set[str] | None = None
+ ) -> set[str]:
+ """
+ Get the running agent loops directly from the remote runtime.
+ """
+ conversation_ids = await self._get_all_running_conversation_ids()
+
+ if filter_to_sids is not None:
+ conversation_ids = {
+ conversation_id
+ for conversation_id in conversation_ids
+ if conversation_id in filter_to_sids
+ }
+
+ if user_id:
+ user_conversation_ids = await call_sync_from_async(
+ self._get_recent_conversation_ids_for_user, user_id
+ )
+ conversation_ids = conversation_ids.intersection(user_conversation_ids)
+
+ return conversation_ids
+
+ async def is_agent_loop_running(self, sid: str) -> bool:
+ """Check if an agent loop is running for the given session ID."""
+ runtime = await self._get_runtime(sid)
+ if runtime is None:
+ return False
+ result = runtime.get('status') == 'running'
+ return result
+
+ async def get_connections(
+ self, user_id: str | None = None, filter_to_sids: set[str] | None = None
+ ) -> dict[str, str]:
+ # We don't monitor connections outside the nested server, though we could introduce an API for this.
+ results: dict[str, str] = {}
+ return results
+
+ async def maybe_start_agent_loop(
+ self,
+ sid: str,
+ settings: Settings,
+ user_id: str, # type: ignore[override]
+ initial_user_msg: MessageAction | None = None,
+ replay_json: str | None = None,
+ ) -> AgentLoopInfo:
+ # First we check redis to see if we are already starting - or the runtime will tell us the session is stopped
+ redis = self._get_redis_client()
+ key = self._get_redis_conversation_key(user_id, sid)
+ starting = await redis.get(key)
+
+ runtime = await self._get_runtime(sid)
+
+ nested_url = None
+ session_api_key = None
+ status = ConversationStatus.STOPPED
+ event_store = EventStore(sid, self.file_store, user_id)
+ if runtime:
+ nested_url = self._get_nested_url_for_runtime(runtime['runtime_id'], sid)
+ session_api_key = runtime.get('session_api_key')
+ status_str = (runtime.get('status') or 'stopped').upper()
+ if status_str in ConversationStatus:
+ status = ConversationStatus[status_str]
+ if status is ConversationStatus.STOPPED and starting:
+ status = ConversationStatus.STARTING
+
+ if status is ConversationStatus.STOPPED:
+ # Mark the agentloop as starting in redis
+ await redis.set(key, 1, ex=_REDIS_ENTRY_TIMEOUT_SECONDS)
+
+ # Start the agent loop in the background
+ asyncio.create_task(
+ self._start_agent_loop(
+ sid, settings, user_id, initial_user_msg, replay_json
+ )
+ )
+
+ return AgentLoopInfo(
+ conversation_id=sid,
+ url=nested_url,
+ session_api_key=session_api_key,
+ event_store=event_store,
+ status=status,
+ )
+
+ async def _start_agent_loop(
+ self, sid, settings, user_id, initial_user_msg=None, replay_json=None
+ ):
+ try:
+ logger.info(f'starting_agent_loop:{sid}', extra={'session_id': sid})
+ await self.ensure_num_conversations_below_limit(sid, user_id)
+ provider_handler = self._get_provider_handler(settings)
+ runtime = await self._create_runtime(
+ sid, user_id, settings, provider_handler
+ )
+ await runtime.connect()
+
+ if not self._runtime_container_image:
+ self._runtime_container_image = getattr(
+ runtime,
+ 'container_image',
+ self.config.sandbox.runtime_container_image,
+ )
+
+ session_api_key = runtime.session.headers['X-Session-API-Key']
+
+ await self._start_conversation(
+ sid,
+ user_id,
+ settings,
+ initial_user_msg,
+ replay_json,
+ runtime.runtime_url,
+ session_api_key,
+ )
+ finally:
+ # remove the starting entry from redis
+ redis = self._get_redis_client()
+ key = self._get_redis_conversation_key(user_id, sid)
+ await redis.delete(key)
+
+ async def _start_conversation(
+ self,
+ sid: str,
+ user_id: str,
+ settings: Settings,
+ initial_user_msg: MessageAction | None,
+ replay_json: str | None,
+ api_url: str,
+ session_api_key: str,
+ ):
+ logger.info('starting_nested_conversation', extra={'sid': sid})
+ async with httpx.AsyncClient(
+ headers={
+ 'X-Session-API-Key': session_api_key,
+ }
+ ) as client:
+ await self._setup_nested_settings(client, api_url, settings)
+ await self._setup_provider_tokens(client, api_url, settings)
+ await self._setup_custom_secrets(client, api_url, settings.custom_secrets) # type: ignore
+ await self._setup_experiment_config(client, api_url, sid, user_id)
+ await self._create_nested_conversation(
+ client, api_url, sid, user_id, settings, initial_user_msg, replay_json
+ )
+ await self._wait_for_conversation_ready(client, api_url, sid)
+
+ async def _setup_experiment_config(
+ self, client: httpx.AsyncClient, api_url: str, sid: str, user_id: str
+ ):
+ # Prevent circular import
+ from openhands.experiments.experiment_manager import (
+ ExperimentConfig,
+ ExperimentManagerImpl,
+ )
+
+ config: OpenHandsConfig = ExperimentManagerImpl.run_config_variant_test(
+ user_id, sid, self.config
+ )
+
+ experiment_config = ExperimentConfig(
+ config={
+ 'system_prompt_filename': config.get_agent_config(
+ config.default_agent
+ ).system_prompt_filename
+ }
+ )
+
+ response = await client.post(
+ f'{api_url}/api/conversations/{sid}/exp-config',
+ json=experiment_config.model_dump(),
+ )
+ response.raise_for_status()
+
+ async def _setup_nested_settings(
+ self, client: httpx.AsyncClient, api_url: str, settings: Settings
+ ) -> None:
+ """Setup the settings for the nested conversation."""
+ settings_json = settings.model_dump(context={'expose_secrets': True})
+ settings_json.pop('custom_secrets', None)
+ settings_json.pop('git_provider_tokens', None)
+ if settings_json.get('git_provider'):
+ settings_json['git_provider'] = settings_json['git_provider'].value
+ settings_json.pop('secrets_store', None)
+ response = await client.post(f'{api_url}/api/settings', json=settings_json)
+ response.raise_for_status()
+
+ async def _setup_provider_tokens(
+ self, client: httpx.AsyncClient, api_url: str, settings: Settings
+ ):
+ """Setup provider tokens for the nested conversation."""
+ provider_handler = self._get_provider_handler(settings)
+ provider_tokens = provider_handler.provider_tokens
+ if provider_tokens:
+ provider_tokens_json = {
+ k.value: {
+ 'token': v.token.get_secret_value(),
+ 'user_id': v.user_id,
+ 'host': v.host,
+ }
+ for k, v in provider_tokens.items()
+ if v.token
+ }
+ response = await client.post(
+ f'{api_url}/api/add-git-providers',
+ json={
+ 'provider_tokens': provider_tokens_json,
+ },
+ )
+ response.raise_for_status()
+
+ async def _setup_custom_secrets(
+ self,
+ client: httpx.AsyncClient,
+ api_url: str,
+ custom_secrets: MappingProxyType[str, Any] | None,
+ ):
+ """Setup custom secrets for the nested conversation."""
+ if custom_secrets:
+ for key, secret in custom_secrets.items():
+ response = await client.post(
+ f'{api_url}/api/secrets',
+ json={
+ 'name': key,
+ 'description': secret.description,
+ 'value': secret.secret.get_secret_value(),
+ },
+ )
+ response.raise_for_status()
+
+ def _get_mcp_config(self, user_id: str) -> MCPConfig | None:
+ api_key_store = ApiKeyStore.get_instance()
+ mcp_api_key = api_key_store.retrieve_mcp_api_key(user_id)
+ if not mcp_api_key:
+ mcp_api_key = api_key_store.create_api_key(user_id, 'MCP_API_KEY', None)
+ if not mcp_api_key:
+ return None
+ web_host = os.environ.get('WEB_HOST', 'app.all-hands.dev')
+ shttp_servers = [
+ MCPSHTTPServerConfig(url=f'https://{web_host}/mcp/mcp', api_key=mcp_api_key)
+ ]
+ return MCPConfig(shttp_servers=shttp_servers)
+
+ async def _create_nested_conversation(
+ self,
+ client: httpx.AsyncClient,
+ api_url: str,
+ sid: str,
+ user_id: str,
+ settings: Settings,
+ initial_user_msg: MessageAction | None,
+ replay_json: str | None,
+ ):
+ """Create the nested conversation."""
+ init_conversation: dict[str, Any] = {
+ 'initial_user_msg': initial_user_msg.content if initial_user_msg else None,
+ 'image_urls': [],
+ 'replay_json': replay_json,
+ 'conversation_id': sid,
+ }
+
+ mcp_config = self._get_mcp_config(user_id)
+ if mcp_config:
+ # Merge with any MCP config from settings
+ if settings.mcp_config:
+ mcp_config = mcp_config.merge(settings.mcp_config)
+ # Check again since theoretically merge could return None.
+ if mcp_config:
+ init_conversation['mcp_config'] = mcp_config.model_dump()
+
+ if isinstance(settings, ConversationInitData):
+ init_conversation['repository'] = settings.selected_repository
+ init_conversation['selected_branch'] = settings.selected_branch
+ init_conversation['git_provider'] = (
+ settings.git_provider.value if settings.git_provider else None
+ )
+ init_conversation['conversation_instructions'] = (
+ settings.conversation_instructions
+ )
+
+ response = await client.post(
+ f'{api_url}/api/conversations', json=init_conversation
+ )
+ logger.info(f'_start_agent_loop:{response.status_code}:{response.json()}')
+ response.raise_for_status()
+
+ async def _wait_for_conversation_ready(
+ self, client: httpx.AsyncClient, api_url: str, sid: str
+ ):
+ """Wait for the conversation to be ready by checking the events endpoint."""
+ # TODO: Find out why /api/conversations/{sid} returns RUNNING when events are not available
+ for _ in range(5):
+ try:
+ logger.info('checking_events_endpoint_running', extra={'sid': sid})
+ response = await client.get(f'{api_url}/api/conversations/{sid}/events')
+ if response.is_success:
+ logger.info('events_endpoint_is_running', extra={'sid': sid})
+ break
+ except Exception:
+ logger.warning('events_endpoint_not_ready', extra={'sid': sid})
+ await asyncio.sleep(5)
+
+ async def send_to_event_stream(self, connection_id: str, data: dict):
+ # Not supported - clients should connect directly to the nested server!
+ raise ValueError('unsupported_operation')
+
+ async def request_llm_completion(
+ self,
+ sid: str,
+ service_id: str,
+ llm_config: LLMConfig,
+ messages: list[dict[str, str]],
+ ) -> str:
+ # Not supported - clients should connect directly to the nested server!
+ raise ValueError('unsupported_operation')
+
+ async def send_event_to_conversation(self, sid: str, data: dict):
+ runtime = await self._get_runtime(sid)
+ if runtime is None:
+ raise ValueError(f'no_such_conversation:{sid}')
+ nested_url = self._get_nested_url_for_runtime(runtime['runtime_id'], sid)
+ async with httpx.AsyncClient(
+ headers={
+ 'X-Session-API-Key': runtime['session_api_key'],
+ }
+ ) as client:
+ response = await client.post(f'{nested_url}/events', json=data)
+ response.raise_for_status()
+
+ async def disconnect_from_session(self, connection_id: str):
+ # Not supported - clients should connect directly to the nested server!
+ raise ValueError('unsupported_operation')
+
+ async def close_session(self, sid: str):
+ logger.info('close_session', extra={'sid': sid})
+ runtime = await self._get_runtime(sid)
+ if runtime is None:
+ logger.info('no_session_to_close', extra={'sid': sid})
+ return
+ async with self._httpx_client() as client:
+ response = await client.post(
+ f'{self.remote_runtime_api_url}/pause',
+ json={'runtime_id': runtime['runtime_id']},
+ )
+ if not response.is_success:
+ logger.info(
+ 'failed_to_close_session',
+ {
+ 'sid': sid,
+ 'status_code': response.status_code,
+ 'detail': (response.content or b'').decode(),
+ },
+ )
+
+ def _get_user_id_from_conversation(self, conversation_id: str) -> str:
+ """
+ Get user_id from conversation_id.
+ """
+
+ with session_maker() as session:
+ conversation_metadata = (
+ session.query(StoredConversationMetadata)
+ .filter(StoredConversationMetadata.conversation_id == conversation_id)
+ .first()
+ )
+
+ if not conversation_metadata:
+ raise ValueError(f'No conversation found {conversation_id}')
+
+ return conversation_metadata.user_id
+
+ async def _get_runtime_status_from_nested_runtime(
+ self, session_api_key: Any | None, nested_url: str, conversation_id: str
+ ) -> RuntimeStatus | None:
+ """Get runtime status from the nested runtime via API call.
+
+ Args:
+ session_api_key: The session API key for authentication
+ nested_url: The base URL of the nested runtime
+ conversation_id: The conversation ID for logging purposes
+
+ Returns:
+ The runtime status if available, None otherwise
+ """
+ try:
+ if not session_api_key:
+ return None
+
+ async with httpx.AsyncClient(
+ headers={
+ 'X-Session-API-Key': session_api_key,
+ }
+ ) as client:
+ # Query the nested runtime for conversation info
+ response = await client.get(nested_url)
+ if response.status_code == 200:
+ conversation_data = response.json()
+ runtime_status_str = conversation_data.get('runtime_status')
+ if runtime_status_str:
+ # Convert string back to RuntimeStatus enum
+ return RuntimeStatus(runtime_status_str)
+ else:
+ logger.debug(
+ f'Failed to get conversation info for {conversation_id}: {response.status_code}'
+ )
+ except ValueError:
+ logger.debug(f'Invalid runtime status value: {runtime_status_str}')
+ except Exception as e:
+ logger.debug(f'Could not get runtime status for {conversation_id}: {e}')
+
+ return None
+
+ async def get_agent_loop_info(
+ self, user_id: str | None = None, filter_to_sids: set[str] | None = None
+ ) -> list[AgentLoopInfo]:
+ if filter_to_sids is not None and not filter_to_sids:
+ return []
+
+ results = []
+ conversation_ids = set()
+
+ # Get starting agent loops from redis...
+ if user_id:
+ pattern = self._get_redis_conversation_key(user_id, '*')
+ else:
+ pattern = self._get_redis_conversation_key('*', '*')
+ redis = self._get_redis_client()
+ async for key in redis.scan_iter(pattern):
+ conversation_user_id, conversation_id = key.decode().split(':')[1:]
+ conversation_ids.add(conversation_id)
+ if filter_to_sids is None or conversation_id in filter_to_sids:
+ results.append(
+ AgentLoopInfo(
+ conversation_id=conversation_id,
+ url=None,
+ session_api_key=None,
+ event_store=EventStore(
+ conversation_id, self.file_store, conversation_user_id
+ ),
+ status=ConversationStatus.STARTING,
+ )
+ )
+
+ # Get running agent loops from runtime api
+ if filter_to_sids and len(filter_to_sids) == 1:
+ runtimes = []
+ runtime = await self._get_runtime(next(iter(filter_to_sids)))
+ if runtime:
+ runtimes.append(runtime)
+ else:
+ runtimes = await self._get_runtimes()
+ for runtime in runtimes:
+ conversation_id = runtime['session_id']
+ if conversation_id in conversation_ids:
+ continue
+ if filter_to_sids is not None and conversation_id not in filter_to_sids:
+ continue
+
+ user_id_for_convo = user_id
+ if not user_id_for_convo:
+ try:
+ user_id_for_convo = await call_sync_from_async(
+ self._get_user_id_from_conversation, conversation_id
+ )
+ except Exception:
+ continue
+
+ nested_url = self._get_nested_url_for_runtime(
+ runtime['runtime_id'], conversation_id
+ )
+ session_api_key = runtime.get('session_api_key')
+
+ # Get runtime status from nested runtime
+ runtime_status = await self._get_runtime_status_from_nested_runtime(
+ session_api_key, nested_url, conversation_id
+ )
+
+ agent_loop_info = AgentLoopInfo(
+ conversation_id=conversation_id,
+ url=nested_url,
+ session_api_key=session_api_key,
+ event_store=EventStore(
+ sid=conversation_id,
+ file_store=self.file_store,
+ user_id=user_id_for_convo,
+ ),
+ status=self._parse_status(runtime),
+ runtime_status=runtime_status,
+ )
+ results.append(agent_loop_info)
+
+ return results
+
+ @classmethod
+ def get_instance(
+ cls,
+ sio: socketio.AsyncServer,
+ config: OpenHandsConfig,
+ file_store: FileStore,
+ server_config: ServerConfig,
+ monitoring_listener: MonitoringListener,
+ ) -> ConversationManager:
+ if 'localhost' in WEB_HOST:
+ event_retrieval = EventRetrieval.POLLING
+ else:
+ event_retrieval = EventRetrieval.WEBHOOK_PUSH
+ return SaasNestedConversationManager(
+ sio=sio,
+ config=config,
+ server_config=server_config,
+ file_store=file_store,
+ event_retrieval=event_retrieval,
+ )
+
+ @property
+ def remote_runtime_api_url(self):
+ return self.config.sandbox.remote_runtime_api_url
+
+ async def _get_conversation_store(self, user_id: str | None) -> ConversationStore:
+ conversation_store_class = self._conversation_store_class
+ if not conversation_store_class:
+ self._conversation_store_class = conversation_store_class = get_impl(
+ ConversationStore, # type: ignore
+ self.server_config.conversation_store_class,
+ )
+ store = await conversation_store_class.get_instance(self.config, user_id) # type: ignore
+ return store
+
+ async def ensure_num_conversations_below_limit(self, sid: str, user_id: str):
+ response_ids = await self.get_running_agent_loops(user_id)
+ if len(response_ids) >= self.config.max_concurrent_conversations:
+ logger.info(
+ f'too_many_sessions_for:{user_id or ""}',
+ extra={'session_id': sid, 'user_id': user_id},
+ )
+ # Get the conversations sorted (oldest first)
+ conversation_store = await self._get_conversation_store(user_id)
+ conversations = await conversation_store.get_all_metadata(response_ids)
+ conversations.sort(key=_last_updated_at_key, reverse=True)
+
+ while len(conversations) >= self.config.max_concurrent_conversations:
+ oldest_conversation_id = conversations.pop().conversation_id
+ logger.debug(
+ f'closing_from_too_many_sessions:{user_id or ""}:{oldest_conversation_id}',
+ extra={'session_id': oldest_conversation_id, 'user_id': user_id},
+ )
+ # Send status message to client and close session.
+ status_update_dict = {
+ 'status_update': True,
+ 'type': 'error',
+ 'id': 'AGENT_ERROR$TOO_MANY_CONVERSATIONS',
+ 'message': 'Too many conversations at once. If you are still using this one, try reactivating it by prompting the agent to continue',
+ }
+ await self.sio.emit(
+ 'oh_event',
+ status_update_dict,
+ to=ROOM_KEY.format(sid=oldest_conversation_id),
+ )
+ await self.close_session(oldest_conversation_id)
+
+ def _get_provider_handler(self, settings: Settings):
+ provider_tokens = None
+ if isinstance(settings, ConversationInitData):
+ provider_tokens = settings.git_provider_tokens
+ provider_handler = ProviderHandler(
+ provider_tokens=provider_tokens
+ or cast(PROVIDER_TOKEN_TYPE, MappingProxyType({}))
+ )
+ return provider_handler
+
+ async def _create_runtime(
+ self,
+ sid: str,
+ user_id: str,
+ settings: Settings,
+ provider_handler: ProviderHandler,
+ ):
+ llm_registry, conversation_stats, config = (
+ create_registry_and_conversation_stats(self.config, sid, user_id, settings)
+ )
+
+ # This session is created here only because it is the easiest way to get a runtime, which
+ # is the easiest way to create the needed docker container
+ session = Session(
+ sid=sid,
+ llm_registry=llm_registry,
+ conversation_stats=conversation_stats,
+ file_store=self.file_store,
+ config=self.config,
+ sio=self.sio,
+ user_id=user_id,
+ )
+ llm_registry.retry_listner = session._notify_on_llm_retry
+ agent_cls = settings.agent or self.config.default_agent
+ agent_config = self.config.get_agent_config(agent_cls)
+ agent = Agent.get_cls(agent_cls)(agent_config, llm_registry)
+
+ config = self.config.model_copy(deep=True)
+ env_vars = config.sandbox.runtime_startup_env_vars
+ env_vars['CONVERSATION_MANAGER_CLASS'] = (
+ 'openhands.server.conversation_manager.standalone_conversation_manager.StandaloneConversationManager'
+ )
+ env_vars['LOG_JSON'] = '1'
+ env_vars['SERVE_FRONTEND'] = '0'
+ env_vars['RUNTIME'] = 'local'
+ # TODO: In the long term we may come up with a more secure strategy for user management within the nested runtime.
+ env_vars['USER'] = 'openhands' if config.run_as_openhands else 'root'
+ env_vars['PERMITTED_CORS_ORIGINS'] = ','.join(PERMITTED_CORS_ORIGINS)
+ env_vars['port'] = '60000'
+ # TODO: These values are static in the runtime-api project, but do not get copied into the runtime ENV
+ env_vars['VSCODE_PORT'] = '60001'
+ env_vars['WORK_PORT_1'] = '12000'
+ env_vars['WORK_PORT_2'] = '12001'
+ # We need to be able to specify the nested conversation id within the nested runtime
+ env_vars['ALLOW_SET_CONVERSATION_ID'] = '1'
+ env_vars['FILE_STORE_PATH'] = '/workspace/.openhands/file_store'
+ env_vars['WORKSPACE_BASE'] = '/workspace/project'
+ env_vars['WORKSPACE_MOUNT_PATH_IN_SANDBOX'] = '/workspace/project'
+ env_vars['SANDBOX_CLOSE_DELAY'] = '0'
+ env_vars['SKIP_DEPENDENCY_CHECK'] = '1'
+ env_vars['INITIAL_NUM_WARM_SERVERS'] = '1'
+ env_vars['INIT_GIT_IN_EMPTY_WORKSPACE'] = '1'
+
+ # We need this for LLM traces tracking to identify the source of the LLM calls
+ env_vars['WEB_HOST'] = WEB_HOST
+ if self.event_retrieval == EventRetrieval.WEBHOOK_PUSH:
+ # If we are retrieving events using push, we tell the nested runtime about the webhook.
+ # The nested runtime will automatically authenticate using the SESSION_API_KEY
+ env_vars['FILE_STORE_WEB_HOOK_URL'] = (
+ f'{PERMITTED_CORS_ORIGINS[0]}/event-webhook/batch'
+ )
+ # Enable batched webhook mode for better performance
+ env_vars['FILE_STORE_WEB_HOOK_BATCH'] = '1'
+
+ if self._runtime_container_image:
+ config.sandbox.runtime_container_image = self._runtime_container_image
+
+ runtime = RemoteRuntime(
+ config=config,
+ event_stream=None, # type: ignore[arg-type]
+ sid=sid,
+ plugins=agent.sandbox_plugins,
+ # env_vars=env_vars,
+ # status_callback: Callable[..., None] | None = None,
+ attach_to_existing=False,
+ headless_mode=False,
+ user_id=user_id,
+ # git_provider_tokens: PROVIDER_TOKEN_TYPE | None = None,
+ main_module='openhands.server',
+ llm_registry=llm_registry,
+ )
+
+ # TODO: This is a hack. The setup_initial_env method directly calls the methods on the action
+ # execution server, even though there are not any variables to set. In the nested env, there
+ # is currently no direct access to the action execution server, so we should either add a
+ # check and not invoke the endpoint if there are no variables, or find a way to access the
+ # action execution server directly (e.g.: Merge the action execution server with the app
+ # server for local runtimes)
+ runtime.setup_initial_env = lambda: None # type:ignore
+
+ return runtime
+
+ @contextlib.asynccontextmanager
+ async def _httpx_client(self):
+ async with httpx.AsyncClient(
+ headers={'X-API-Key': self.config.sandbox.api_key or ''},
+ timeout=_HTTP_TIMEOUT,
+ ) as client:
+ yield client
+
+ async def _get_runtimes(self) -> list[dict]:
+ async with self._httpx_client() as client:
+ response = await client.get(f'{self.remote_runtime_api_url}/list')
+ response_json = response.json()
+ runtimes = response_json['runtimes']
+ return runtimes
+
+ async def _get_all_running_conversation_ids(self) -> set[str]:
+ runtimes = await self._get_runtimes()
+ conversation_ids = {
+ runtime['session_id']
+ for runtime in runtimes
+ if runtime.get('status') == 'running'
+ }
+ return conversation_ids
+
+ def _get_recent_conversation_ids_for_user(self, user_id: str) -> set[str]:
+ with session_maker() as session:
+ # Only include conversations updated in the past week
+ one_week_ago = datetime.now(UTC) - timedelta(days=7)
+ query = session.query(StoredConversationMetadata.conversation_id).filter(
+ StoredConversationMetadata.user_id == user_id,
+ StoredConversationMetadata.last_updated_at >= one_week_ago,
+ )
+ user_conversation_ids = set(query)
+ return user_conversation_ids
+
+ async def _get_runtime(self, sid: str) -> dict | None:
+ async with self._httpx_client() as client:
+ response = await client.get(f'{self.remote_runtime_api_url}/sessions/{sid}')
+ if not response.is_success:
+ return None
+ response_json = response.json()
+
+ # Hack: This endpoint doesn't return the session_id
+ response_json['session_id'] = sid
+
+ return response_json
+
+ def _parse_status(self, runtime: dict):
+ # status is one of running, stoppped, paused, error, starting
+ status = (runtime.get('status') or '').upper()
+ if status == 'PAUSED':
+ return ConversationStatus.STOPPED
+ elif status == 'STOPPED':
+ return ConversationStatus.ARCHIVED
+ if status in ConversationStatus:
+ return ConversationStatus[status]
+ return ConversationStatus.STOPPED
+
+ def _get_nested_url_for_runtime(self, runtime_id: str, conversation_id: str):
+ return RUNTIME_CONVERSATION_URL.format(
+ runtime_id=runtime_id, conversation_id=conversation_id
+ )
+
+ def _get_redis_client(self):
+ return getattr(self.sio.manager, 'redis', None)
+
+ def _get_redis_conversation_key(self, user_id: str, conversation_id: str):
+ return f'ohcnv:{user_id}:{conversation_id}'
+
+ async def _poll_events(self):
+ """Poll events in nested runtimes. This is primarily used in debug / single server environments"""
+ while should_continue():
+ try:
+ await asyncio.sleep(_POLLING_INTERVAL)
+ agent_loop_infos = await self.get_agent_loop_info()
+
+ with session_maker() as session:
+ for agent_loop_info in agent_loop_infos:
+ if agent_loop_info.status != ConversationStatus.RUNNING:
+ continue
+ try:
+ await self._poll_agent_loop_events(agent_loop_info, session)
+ except Exception as e:
+ logger.exception(f'error_polling_events:{str(e)}')
+ except Exception as e:
+ try:
+ asyncio.get_running_loop()
+ logger.exception(f'error_polling_events:{str(e)}')
+ except RuntimeError:
+ # Loop has been shut down, exit gracefully
+ return
+
+ async def _poll_agent_loop_events(
+ self, agent_loop_info: AgentLoopInfo, session: orm.Session
+ ):
+ """This method is typically only run in localhost, where the webhook callbacks from the remote runtime are unavailable"""
+ if agent_loop_info.status != ConversationStatus.RUNNING:
+ return
+ conversation_id = agent_loop_info.conversation_id
+ conversation_metadata = (
+ session.query(StoredConversationMetadata)
+ .filter(StoredConversationMetadata.conversation_id == conversation_id)
+ .first()
+ )
+ if conversation_metadata is None:
+ # Conversation is running in different server
+ return
+
+ user_id = conversation_metadata.user_id
+
+ # Get the id of the next event which is not present
+ events_dir = get_conversation_events_dir(
+ agent_loop_info.conversation_id, user_id
+ )
+ try:
+ event_file_names = self.file_store.list(events_dir)
+ except FileNotFoundError:
+ event_file_names = []
+ start_id = (
+ max(
+ (
+ _get_id_from_filename(event_file_name)
+ for event_file_name in event_file_names
+ ),
+ default=-1,
+ )
+ + 1
+ )
+
+ # Copy over any missing events and update the conversation metadata
+ last_updated_at = conversation_metadata.last_updated_at
+ if agent_loop_info.event_store:
+ for event in agent_loop_info.event_store.search_events(start_id=start_id):
+ # What would the handling be if no event.timestamp? Can that happen?
+ if event.timestamp:
+ timestamp = datetime.fromisoformat(event.timestamp)
+ last_updated_at = max(last_updated_at, timestamp)
+ contents = json.dumps(event_to_dict(event))
+ path = get_conversation_event_filename(
+ conversation_id, event.id, user_id
+ )
+ self.file_store.write(path, contents)
+
+ # Process the event using shared logic from event_webhook
+ subpath = f'events/{event.id}.json'
+ await process_event(
+ user_id, conversation_id, subpath, event_to_dict(event)
+ )
+
+ # Update conversation metadata using shared logic
+ metadata_content = {
+ 'last_updated_at': last_updated_at.isoformat() if last_updated_at else None,
+ }
+ update_conversation_metadata(conversation_id, metadata_content)
+
+
+def _last_updated_at_key(conversation: ConversationMetadata) -> float:
+ last_updated_at = conversation.last_updated_at
+ if last_updated_at is None:
+ return 0.0
+ return last_updated_at.timestamp()
+
+
+def _get_id_from_filename(filename: str) -> int:
+ try:
+ return int(filename.split('/')[-1].split('.')[0])
+ except ValueError:
+ logger.warning(f'get id from filename ({filename}) failed.')
+ return -1
diff --git a/enterprise/server/utils/__init__.py b/enterprise/server/utils/__init__.py
new file mode 100644
index 0000000000..2fd67179c4
--- /dev/null
+++ b/enterprise/server/utils/__init__.py
@@ -0,0 +1 @@
+# Server utilities package
diff --git a/enterprise/server/utils/conversation_callback_utils.py b/enterprise/server/utils/conversation_callback_utils.py
new file mode 100644
index 0000000000..dc36b0c703
--- /dev/null
+++ b/enterprise/server/utils/conversation_callback_utils.py
@@ -0,0 +1,296 @@
+import base64
+import json
+import pickle
+from datetime import datetime
+
+from server.logger import logger
+from storage.conversation_callback import (
+ CallbackStatus,
+ ConversationCallback,
+ ConversationCallbackProcessor,
+)
+from storage.conversation_work import ConversationWork
+from storage.database import session_maker
+from storage.stored_conversation_metadata import StoredConversationMetadata
+
+from openhands.core.config import load_openhands_config
+from openhands.core.schema.agent import AgentState
+from openhands.events.event_store import EventStore
+from openhands.events.observation.agent import AgentStateChangedObservation
+from openhands.events.serialization.event import event_from_dict
+from openhands.server.services.conversation_stats import ConversationStats
+from openhands.storage import get_file_store
+from openhands.storage.files import FileStore
+from openhands.storage.locations import (
+ get_conversation_agent_state_filename,
+ get_conversation_dir,
+)
+from openhands.utils.async_utils import call_sync_from_async
+
+config = load_openhands_config()
+file_store = get_file_store(config.file_store, config.file_store_path)
+
+
+async def process_event(
+ user_id: str, conversation_id: str, subpath: str, content: dict
+):
+ """
+ Process a conversation event and invoke any registered callbacks.
+
+ Args:
+ user_id: The user ID associated with the conversation
+ conversation_id: The conversation ID
+ subpath: The event subpath
+ content: The event content
+ """
+ logger.debug(
+ 'process_event',
+ extra={
+ 'user_id': user_id,
+ 'conversation_id': conversation_id,
+ 'content': content,
+ },
+ )
+ write_path = get_conversation_dir(conversation_id, user_id) + subpath
+
+ # This writes to the google cloud storage, so we do this in a background thread to not block the main runloop...
+ await call_sync_from_async(file_store.write, write_path, json.dumps(content))
+
+ event = event_from_dict(content)
+ if isinstance(event, AgentStateChangedObservation):
+ # Load and invoke all active callbacks for this conversation
+ await invoke_conversation_callbacks(conversation_id, event)
+
+ # Update active working seconds if agent state is not Running
+ if event.agent_state != AgentState.RUNNING:
+ event_store = EventStore(conversation_id, file_store, user_id)
+ update_active_working_seconds(
+ event_store, conversation_id, user_id, file_store
+ )
+
+
+async def invoke_conversation_callbacks(
+ conversation_id: str, observation: AgentStateChangedObservation
+):
+ """
+ Load and invoke all active callbacks for a conversation.
+
+ Args:
+ conversation_id: The conversation ID to process callbacks for
+ observation: The AgentStateChangedObservation that triggered the callback
+ """
+ with session_maker() as session:
+ callbacks = (
+ session.query(ConversationCallback)
+ .filter(
+ ConversationCallback.conversation_id == conversation_id,
+ ConversationCallback.status == CallbackStatus.ACTIVE,
+ )
+ .all()
+ )
+
+ for callback in callbacks:
+ try:
+ processor = callback.get_processor()
+ await processor.__call__(callback, observation)
+ logger.info(
+ 'callback_invoked_successfully',
+ extra={
+ 'conversation_id': conversation_id,
+ 'callback_id': callback.id,
+ 'processor_type': callback.processor_type,
+ },
+ )
+ except Exception as e:
+ logger.error(
+ 'callback_invocation_failed',
+ extra={
+ 'conversation_id': conversation_id,
+ 'callback_id': callback.id,
+ 'processor_type': callback.processor_type,
+ 'error': str(e),
+ },
+ )
+ # Mark callback as error status
+ callback.status = CallbackStatus.ERROR
+ callback.updated_at = datetime.now()
+
+ session.commit()
+
+
+def update_conversation_metadata(conversation_id: str, content: dict):
+ """
+ Update conversation metadata with new content.
+
+ Args:
+ conversation_id: The conversation ID to update
+ content: The metadata content to update
+ """
+ logger.debug(
+ 'update_conversation_metadata',
+ extra={
+ 'conversation_id': conversation_id,
+ 'content': content,
+ },
+ )
+ with session_maker() as session:
+ conversation = (
+ session.query(StoredConversationMetadata)
+ .filter(StoredConversationMetadata.conversation_id == conversation_id)
+ .first()
+ )
+ conversation.title = content.get('title') or conversation.title
+ conversation.last_updated_at = datetime.now()
+ conversation.accumulated_cost = (
+ content.get('accumulated_cost') or conversation.accumulated_cost
+ )
+ conversation.prompt_tokens = (
+ content.get('prompt_tokens') or conversation.prompt_tokens
+ )
+ conversation.completion_tokens = (
+ content.get('completion_tokens') or conversation.completion_tokens
+ )
+ conversation.total_tokens = (
+ content.get('total_tokens') or conversation.total_tokens
+ )
+ session.commit()
+
+
+def register_callback_processor(
+ conversation_id: str, processor: ConversationCallbackProcessor
+) -> int:
+ """
+ Register a callback processor for a conversation.
+
+ Args:
+ conversation_id: The conversation ID to register the callback for
+ processor: The ConversationCallbackProcessor instance to register
+
+ Returns:
+ int: The ID of the created callback
+ """
+ with session_maker() as session:
+ callback = ConversationCallback(
+ conversation_id=conversation_id, status=CallbackStatus.ACTIVE
+ )
+ callback.set_processor(processor)
+ session.add(callback)
+ session.commit()
+ return callback.id
+
+
+def update_active_working_seconds(
+ event_store: EventStore, conversation_id: str, user_id: str, file_store: FileStore
+):
+ """
+ Calculate and update the total active working seconds for a conversation.
+
+ This function reads all events for the conversation, looks for AgentStateChanged
+ observations, and calculates the total time spent in a running state.
+
+ Args:
+ event_store: The EventStore instance for reading events
+ conversation_id: The conversation ID to process
+ user_id: The user ID associated with the conversation
+ file_store: The FileStore instance for accessing conversation data
+ """
+ try:
+ # Get all events for the conversation
+ events = list(event_store.get_events())
+
+ # Track agent state changes and calculate running time
+ running_start_time = None
+ total_running_seconds = 0.0
+
+ for event in events:
+ if isinstance(event, AgentStateChangedObservation) and event.timestamp:
+ event_timestamp = datetime.fromisoformat(event.timestamp).timestamp()
+
+ if event.agent_state == AgentState.RUNNING:
+ # Agent started running
+ if running_start_time is None:
+ running_start_time = event_timestamp
+ elif running_start_time is not None:
+ # Agent stopped running, calculate duration
+ duration = event_timestamp - running_start_time
+ total_running_seconds += duration
+ running_start_time = None
+
+ # If agent is still running at the end, don't count that time yet
+ # (it will be counted when the agent stops)
+
+ # Create or update the conversation_work record
+ with session_maker() as session:
+ conversation_work = (
+ session.query(ConversationWork)
+ .filter(ConversationWork.conversation_id == conversation_id)
+ .first()
+ )
+
+ if conversation_work:
+ # Update existing record
+ conversation_work.seconds = total_running_seconds
+ conversation_work.updated_at = datetime.now().isoformat()
+ else:
+ # Create new record
+ conversation_work = ConversationWork(
+ conversation_id=conversation_id,
+ user_id=user_id,
+ seconds=total_running_seconds,
+ )
+ session.add(conversation_work)
+
+ session.commit()
+
+ logger.info(
+ 'updated_active_working_seconds',
+ extra={
+ 'conversation_id': conversation_id,
+ 'user_id': user_id,
+ 'total_seconds': total_running_seconds,
+ },
+ )
+
+ except Exception as e:
+ logger.error(
+ 'failed_to_update_active_working_seconds',
+ extra={
+ 'conversation_id': conversation_id,
+ 'user_id': user_id,
+ 'error': str(e),
+ },
+ )
+
+
+def update_agent_state(user_id: str, conversation_id: str, content: bytes):
+ """
+ Update agent state file for a conversation.
+
+ Args:
+ user_id: The user ID associated with the conversation
+ conversation_id: The conversation ID
+ content: The agent state content as bytes
+ """
+ logger.debug(
+ 'update_agent_state',
+ extra={
+ 'user_id': user_id,
+ 'conversation_id': conversation_id,
+ 'content_size': len(content),
+ },
+ )
+ write_path = get_conversation_agent_state_filename(conversation_id, user_id)
+ file_store.write(write_path, content)
+
+
+def update_conversation_stats(user_id: str, conversation_id: str, content: bytes):
+ existing_convo_stats = ConversationStats(
+ file_store=file_store, conversation_id=conversation_id, user_id=user_id
+ )
+
+ incoming_convo_stats = ConversationStats(None, conversation_id, None)
+ pickled = base64.b64decode(content)
+ incoming_convo_stats.restored_metrics = pickle.loads(pickled)
+
+ # Merging automatically saves to file store
+ existing_convo_stats.merge_and_save(incoming_convo_stats)
diff --git a/enterprise/storage/__init__.py b/enterprise/storage/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/enterprise/storage/api_key.py b/enterprise/storage/api_key.py
new file mode 100644
index 0000000000..dd9d557c5a
--- /dev/null
+++ b/enterprise/storage/api_key.py
@@ -0,0 +1,19 @@
+from sqlalchemy import Column, DateTime, Integer, String, text
+from storage.base import Base
+
+
+class ApiKey(Base):
+ """
+ Represents an API key for a user.
+ """
+
+ __tablename__ = 'api_keys'
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ key = Column(String(255), nullable=False, unique=True, index=True)
+ user_id = Column(String(255), nullable=False, index=True)
+ name = Column(String(255), nullable=True)
+ created_at = Column(
+ DateTime, server_default=text('CURRENT_TIMESTAMP'), nullable=False
+ )
+ last_used_at = Column(DateTime, nullable=True)
+ expires_at = Column(DateTime, nullable=True)
diff --git a/enterprise/storage/api_key_store.py b/enterprise/storage/api_key_store.py
new file mode 100644
index 0000000000..162ed415c1
--- /dev/null
+++ b/enterprise/storage/api_key_store.py
@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import secrets
+import string
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from sqlalchemy import update
+from sqlalchemy.orm import sessionmaker
+from storage.api_key import ApiKey
+from storage.database import session_maker
+
+from openhands.core.logger import openhands_logger as logger
+
+
+@dataclass
+class ApiKeyStore:
+ session_maker: sessionmaker
+
+ def generate_api_key(self, length: int = 32) -> str:
+ """Generate a random API key."""
+ alphabet = string.ascii_letters + string.digits
+ return ''.join(secrets.choice(alphabet) for _ in range(length))
+
+ def create_api_key(
+ self, user_id: str, name: str | None = None, expires_at: datetime | None = None
+ ) -> str:
+ """Create a new API key for a user.
+
+ Args:
+ user_id: The ID of the user to create the key for
+ name: Optional name for the key
+ expires_at: Optional expiration date for the key
+
+ Returns:
+ The generated API key
+ """
+ api_key = self.generate_api_key()
+
+ with self.session_maker() as session:
+ key_record = ApiKey(
+ key=api_key, user_id=user_id, name=name, expires_at=expires_at
+ )
+ session.add(key_record)
+ session.commit()
+
+ return api_key
+
+ def validate_api_key(self, api_key: str) -> str | None:
+ """Validate an API key and return the associated user_id if valid."""
+ now = datetime.now(UTC)
+
+ with self.session_maker() as session:
+ key_record = session.query(ApiKey).filter(ApiKey.key == api_key).first()
+
+ if not key_record:
+ return None
+
+ # Check if the key has expired
+ if key_record.expires_at and key_record.expires_at < now:
+ logger.info(f'API key has expired: {key_record.id}')
+ return None
+
+ # Update last_used_at timestamp
+ session.execute(
+ update(ApiKey)
+ .where(ApiKey.id == key_record.id)
+ .values(last_used_at=now)
+ )
+ session.commit()
+
+ return key_record.user_id
+
+ def delete_api_key(self, api_key: str) -> bool:
+ """Delete an API key by the key value."""
+ with self.session_maker() as session:
+ key_record = session.query(ApiKey).filter(ApiKey.key == api_key).first()
+
+ if not key_record:
+ return False
+
+ session.delete(key_record)
+ session.commit()
+
+ return True
+
+ def delete_api_key_by_id(self, key_id: int) -> bool:
+ """Delete an API key by its ID."""
+ with self.session_maker() as session:
+ key_record = session.query(ApiKey).filter(ApiKey.id == key_id).first()
+
+ if not key_record:
+ return False
+
+ session.delete(key_record)
+ session.commit()
+
+ return True
+
+ def list_api_keys(self, user_id: str) -> list[dict]:
+ """List all API keys for a user."""
+ with self.session_maker() as session:
+ keys = session.query(ApiKey).filter(ApiKey.user_id == user_id).all()
+
+ return [
+ {
+ 'id': key.id,
+ 'name': key.name,
+ 'created_at': key.created_at,
+ 'last_used_at': key.last_used_at,
+ 'expires_at': key.expires_at,
+ }
+ for key in keys
+ if 'MCP_API_KEY' != key.name
+ ]
+
+ def retrieve_mcp_api_key(self, user_id: str) -> str | None:
+ with self.session_maker() as session:
+ keys: list[ApiKey] = (
+ session.query(ApiKey).filter(ApiKey.user_id == user_id).all()
+ )
+ for key in keys:
+ if key.name == 'MCP_API_KEY':
+ return key.key
+
+ return None
+
+ @classmethod
+ def get_instance(cls) -> ApiKeyStore:
+ """Get an instance of the ApiKeyStore."""
+ logger.debug('api_key_store.get_instance')
+ return ApiKeyStore(session_maker)
diff --git a/enterprise/storage/auth_token_store.py b/enterprise/storage/auth_token_store.py
new file mode 100644
index 0000000000..2a37595e7f
--- /dev/null
+++ b/enterprise/storage/auth_token_store.py
@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Awaitable, Callable, Dict
+
+from sqlalchemy import select, update
+from sqlalchemy.orm import sessionmaker
+from storage.auth_tokens import AuthTokens
+from storage.database import a_session_maker
+
+from openhands.core.logger import openhands_logger as logger
+from openhands.integrations.service_types import ProviderType
+
+
+@dataclass
+class AuthTokenStore:
+ keycloak_user_id: str
+ idp: ProviderType
+ a_session_maker: sessionmaker
+
+ @property
+ def identity_provider_value(self) -> str:
+ return self.idp.value
+
+ async def store_tokens(
+ self,
+ access_token: str,
+ refresh_token: str,
+ access_token_expires_at: int,
+ refresh_token_expires_at: int,
+ ) -> None:
+ """Store auth tokens in the database.
+
+ Args:
+ access_token: The access token to store
+ refresh_token: The refresh token to store
+ access_token_expires_at: Expiration time for access token (seconds since epoch)
+ refresh_token_expires_at: Expiration time for refresh token (seconds since epoch)
+ """
+ async with self.a_session_maker() as session:
+ async with session.begin(): # Explicitly start a transaction
+ result = await session.execute(
+ select(AuthTokens).where(
+ AuthTokens.keycloak_user_id == self.keycloak_user_id,
+ AuthTokens.identity_provider == self.identity_provider_value,
+ )
+ )
+ token_record = result.scalars().first()
+
+ if token_record:
+ token_record.access_token = access_token
+ token_record.refresh_token = refresh_token
+ token_record.access_token_expires_at = access_token_expires_at
+ token_record.refresh_token_expires_at = refresh_token_expires_at
+ else:
+ token_record = AuthTokens(
+ keycloak_user_id=self.keycloak_user_id,
+ identity_provider=self.identity_provider_value,
+ access_token=access_token,
+ refresh_token=refresh_token,
+ access_token_expires_at=access_token_expires_at,
+ refresh_token_expires_at=refresh_token_expires_at,
+ )
+ session.add(token_record)
+
+ await session.commit() # Commit after transaction block
+
+ async def load_tokens(
+ self,
+ check_expiration_and_refresh: Callable[
+ [ProviderType, str, int, int], Awaitable[Dict[str, str | int]]
+ ]
+ | None = None,
+ ) -> Dict[str, str | int] | None:
+ """
+ Load authentication tokens from the database and refresh them if necessary.
+
+ This method retrieves the current authentication tokens for the user and checks if they have expired.
+ It uses the provided `check_expiration_and_refresh` function to determine if the tokens need
+ to be refreshed and to refresh the tokens if needed.
+
+ The method ensures that only one refresh operation is performed per refresh token by using a
+ row-level lock on the token record.
+
+ The method is designed to handle race conditions where multiple requests might attempt to refresh
+ the same token simultaneously, ensuring that only one refresh call occurs per refresh token.
+
+ Args:
+ check_expiration_and_refresh (Callable, optional): A function that checks if the tokens have expired
+ and attempts to refresh them. It should return a dictionary containing the new access_token, refresh_token,
+ and their respective expiration timestamps. If no refresh is needed, it should return `None`.
+
+ Returns:
+ Dict[str, str | int] | None:
+ A dictionary containing the access_token, refresh_token, access_token_expires_at,
+ and refresh_token_expires_at. If no token record is found, returns `None`.
+ """
+ async with self.a_session_maker() as session:
+ async with session.begin(): # Ensures transaction management
+ # Lock the row while we check if we need to refresh the tokens.
+ # There is a race condition where 2 or more calls can load tokens simultaneously.
+ # If it turns out the loaded tokens are expired, then there will be multiple
+ # refresh token calls with the same refresh token. Most IDPs only allow one refresh
+ # per refresh token. This lock ensure that only one refresh call occurs per refresh token
+ result = await session.execute(
+ select(AuthTokens)
+ .filter(
+ AuthTokens.keycloak_user_id == self.keycloak_user_id,
+ AuthTokens.identity_provider == self.identity_provider_value,
+ )
+ .with_for_update()
+ )
+ token_record = result.scalars().one_or_none()
+
+ if not token_record:
+ return None
+
+ token_refresh = (
+ await check_expiration_and_refresh(
+ self.idp,
+ token_record.refresh_token,
+ token_record.access_token_expires_at,
+ token_record.refresh_token_expires_at,
+ )
+ if check_expiration_and_refresh
+ else None
+ )
+
+ if token_refresh:
+ await session.execute(
+ update(AuthTokens)
+ .where(AuthTokens.id == token_record.id)
+ .values(
+ access_token=token_refresh['access_token'],
+ refresh_token=token_refresh['refresh_token'],
+ access_token_expires_at=token_refresh[
+ 'access_token_expires_at'
+ ],
+ refresh_token_expires_at=token_refresh[
+ 'refresh_token_expires_at'
+ ],
+ )
+ )
+ await session.commit()
+
+ return (
+ token_refresh
+ if token_refresh
+ else {
+ 'access_token': token_record.access_token,
+ 'refresh_token': token_record.refresh_token,
+ 'access_token_expires_at': token_record.access_token_expires_at,
+ 'refresh_token_expires_at': token_record.refresh_token_expires_at,
+ }
+ )
+
+ async def is_access_token_valid(self) -> bool:
+ """Check if the access token is still valid.
+
+ Returns:
+ True if the access token exists and is not expired, False otherwise
+ """
+ tokens = await self.load_tokens()
+ if not tokens:
+ return False
+
+ access_token_expires_at = tokens['access_token_expires_at']
+ current_time = int(time.time())
+
+ # Return True if the token is not expired (with a small buffer)
+ return int(access_token_expires_at) > (current_time + 30)
+
+ async def is_refresh_token_valid(self) -> bool:
+ """Check if the refresh token is still valid.
+
+ Returns:
+ True if the refresh token exists and is not expired, False otherwise
+ """
+ tokens = await self.load_tokens()
+ if not tokens:
+ return False
+
+ refresh_token_expires_at = tokens['refresh_token_expires_at']
+ current_time = int(time.time())
+
+ # Return True if the token is not expired (with a small buffer)
+ return int(refresh_token_expires_at) > (current_time + 30)
+
+ @classmethod
+ async def get_instance(
+ cls, keycloak_user_id: str, idp: ProviderType
+ ) -> AuthTokenStore:
+ """Get an instance of the AuthTokenStore.
+
+ Args:
+ config: The application configuration
+ keycloak_user_id: The Keycloak user ID
+
+ Returns:
+ An instance of AuthTokenStore
+ """
+ logger.debug(f'auth_token_store.get_instance::{keycloak_user_id}')
+ if keycloak_user_id:
+ keycloak_user_id = str(keycloak_user_id)
+ return AuthTokenStore(
+ keycloak_user_id=keycloak_user_id, idp=idp, a_session_maker=a_session_maker
+ )
diff --git a/enterprise/storage/auth_tokens.py b/enterprise/storage/auth_tokens.py
new file mode 100644
index 0000000000..c73a3f6302
--- /dev/null
+++ b/enterprise/storage/auth_tokens.py
@@ -0,0 +1,26 @@
+from sqlalchemy import BigInteger, Column, Identity, Index, Integer, String
+from storage.base import Base
+
+
+class AuthTokens(Base): # type: ignore
+ __tablename__ = 'auth_tokens'
+ id = Column(Integer, Identity(), primary_key=True)
+ keycloak_user_id = Column(String, nullable=False, index=True)
+ identity_provider = Column(String, nullable=False)
+ access_token = Column(String, nullable=False)
+ refresh_token = Column(String, nullable=False)
+ access_token_expires_at = Column(
+ BigInteger, nullable=False
+ ) # Time since epoch in seconds
+ refresh_token_expires_at = Column(
+ BigInteger, nullable=False
+ ) # Time since epoch in seconds
+
+ __table_args__ = (
+ Index(
+ 'idx_auth_tokens_keycloak_user_identity_provider',
+ 'keycloak_user_id',
+ 'identity_provider',
+ unique=True,
+ ),
+ )
diff --git a/enterprise/storage/base.py b/enterprise/storage/base.py
new file mode 100644
index 0000000000..6b37477f56
--- /dev/null
+++ b/enterprise/storage/base.py
@@ -0,0 +1,7 @@
+"""
+Unified SQLAlchemy declarative base for all models.
+"""
+
+from sqlalchemy.orm import declarative_base
+
+Base = declarative_base()
diff --git a/enterprise/storage/billing_session.py b/enterprise/storage/billing_session.py
new file mode 100644
index 0000000000..77dbd271b5
--- /dev/null
+++ b/enterprise/storage/billing_session.py
@@ -0,0 +1,45 @@
+from datetime import UTC, datetime
+
+from sqlalchemy import DECIMAL, Column, DateTime, Enum, String
+from storage.base import Base
+
+
+class BillingSession(Base): # type: ignore
+ """
+ Represents a Stripe billing session for credit purchases.
+ Tracks the status of payment transactions and associated user information.
+ """
+
+ __tablename__ = 'billing_sessions'
+
+ id = Column(String, primary_key=True)
+ user_id = Column(String, nullable=False)
+ status = Column(
+ Enum(
+ 'in_progress',
+ 'completed',
+ 'cancelled',
+ 'error',
+ name='billing_session_status_enum',
+ ),
+ default='in_progress',
+ )
+ billing_session_type = Column(
+ Enum(
+ 'DIRECT_PAYMENT',
+ 'MONTHLY_SUBSCRIPTION',
+ name='billing_session_type_enum',
+ ),
+ nullable=False,
+ default='DIRECT_PAYMENT',
+ )
+ price = Column(DECIMAL(19, 4), nullable=False)
+ price_code = Column(String, nullable=False)
+ created_at = Column(
+ DateTime(timezone=True),
+ default=lambda: datetime.now(UTC), # type: ignore[attr-defined]
+ )
+ updated_at = Column(
+ DateTime(timezone=True),
+ default=lambda: datetime.now(UTC), # type: ignore[attr-defined]
+ )
diff --git a/enterprise/storage/billing_session_type.py b/enterprise/storage/billing_session_type.py
new file mode 100644
index 0000000000..86ecbff62e
--- /dev/null
+++ b/enterprise/storage/billing_session_type.py
@@ -0,0 +1,6 @@
+from enum import Enum
+
+
+class BillingSessionType(Enum):
+ DIRECT_PAYMENT = 'DIRECT_PAYMENT'
+ MONTHLY_SUBSCRIPTION = 'MONTHLY_SUBSCRIPTION'
diff --git a/enterprise/storage/conversation_callback.py b/enterprise/storage/conversation_callback.py
new file mode 100644
index 0000000000..25f13d8d8f
--- /dev/null
+++ b/enterprise/storage/conversation_callback.py
@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+from enum import Enum
+from typing import Type
+
+from pydantic import BaseModel, ConfigDict
+from sqlalchemy import Column, DateTime, ForeignKey, Integer, String, Text, text
+from sqlalchemy import Enum as SQLEnum
+from storage.base import Base
+
+from openhands.events.observation.agent import AgentStateChangedObservation
+from openhands.utils.import_utils import get_impl
+
+
+class ConversationCallbackProcessor(BaseModel, ABC):
+ """
+ Abstract base class for conversation callback processors.
+
+ Conversation processors are invoked when events occur in a conversation
+ to perform additional processing, notifications, or integrations.
+ """
+
+ model_config = ConfigDict(
+ # Allow extra fields for flexibility
+ extra='allow',
+ # Allow arbitrary types
+ arbitrary_types_allowed=True,
+ )
+
+ @abstractmethod
+ async def __call__(
+ self,
+ callback: ConversationCallback,
+ observation: AgentStateChangedObservation,
+ ) -> None:
+ """
+ Process a conversation event.
+
+ Args:
+ conversation_id: The ID of the conversation to process
+ observation: The AgentStateChangedObservation that triggered the callback
+ callback: The conversation callback
+ """
+
+
+class CallbackStatus(Enum):
+ """Status of a conversation callback."""
+
+ ACTIVE = 'ACTIVE'
+ COMPLETED = 'COMPLETED'
+ ERROR = 'ERROR'
+
+
+class ConversationCallback(Base): # type: ignore
+ """
+ Model for storing conversation callbacks that process conversation events.
+ """
+
+ __tablename__ = 'conversation_callbacks'
+
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ conversation_id = Column(
+ String,
+ ForeignKey('conversation_metadata.conversation_id'),
+ nullable=False,
+ index=True,
+ )
+ status = Column(
+ SQLEnum(CallbackStatus), nullable=False, default=CallbackStatus.ACTIVE
+ )
+ processor_type = Column(String, nullable=False)
+ processor_json = Column(Text, nullable=False)
+ created_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
+ updated_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ onupdate=datetime.now,
+ nullable=False,
+ )
+
+ def get_processor(self) -> ConversationCallbackProcessor:
+ """
+ Get the processor instance from the stored processor type and JSON data.
+
+ Returns:
+ ConversationCallbackProcessor: The processor instance
+ """
+ # Import the processor class dynamically
+ processor_type: Type[ConversationCallbackProcessor] = get_impl(
+ ConversationCallbackProcessor, self.processor_type
+ )
+ processor = processor_type.model_validate_json(self.processor_json)
+ return processor
+
+ def set_processor(self, processor: ConversationCallbackProcessor) -> None:
+ """
+ Set the processor instance, storing its type and JSON representation.
+
+ Args:
+ processor: The ConversationCallbackProcessor instance to store
+ """
+ self.processor_type = (
+ f'{processor.__class__.__module__}.{processor.__class__.__name__}'
+ )
+ self.processor_json = processor.model_dump_json()
diff --git a/enterprise/storage/conversation_work.py b/enterprise/storage/conversation_work.py
new file mode 100644
index 0000000000..b8e9f785cc
--- /dev/null
+++ b/enterprise/storage/conversation_work.py
@@ -0,0 +1,27 @@
+from datetime import UTC, datetime
+
+from sqlalchemy import Column, Float, Index, Integer, String
+from storage.base import Base
+
+
+class ConversationWork(Base): # type: ignore
+ __tablename__ = 'conversation_work'
+
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ conversation_id = Column(String, nullable=False, unique=True, index=True)
+ user_id = Column(String, nullable=False, index=True)
+ seconds = Column(Float, nullable=False, default=0.0)
+ created_at = Column(
+ String, default=lambda: datetime.now(UTC).isoformat(), nullable=False
+ )
+ updated_at = Column(
+ String,
+ default=lambda: datetime.now(UTC).isoformat(),
+ onupdate=lambda: datetime.now(UTC).isoformat(),
+ nullable=False,
+ )
+
+ # Create composite index for efficient queries
+ __table_args__ = (
+ Index('ix_conversation_work_user_conversation', 'user_id', 'conversation_id'),
+ )
diff --git a/enterprise/storage/database.py b/enterprise/storage/database.py
new file mode 100644
index 0000000000..61e490554f
--- /dev/null
+++ b/enterprise/storage/database.py
@@ -0,0 +1,111 @@
+import asyncio
+import os
+
+from google.cloud.sql.connector import Connector
+from sqlalchemy import create_engine
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.pool import NullPool
+from sqlalchemy.util import await_only
+
+DB_HOST = os.environ.get('DB_HOST', 'localhost') # for non-GCP environments
+DB_PORT = os.environ.get('DB_PORT', '5432') # for non-GCP environments
+DB_USER = os.environ.get('DB_USER', 'postgres')
+DB_PASS = os.environ.get('DB_PASS', 'postgres').strip()
+DB_NAME = os.environ.get('DB_NAME', 'openhands')
+
+GCP_DB_INSTANCE = os.environ.get('GCP_DB_INSTANCE') # for GCP environments
+GCP_PROJECT = os.environ.get('GCP_PROJECT')
+GCP_REGION = os.environ.get('GCP_REGION')
+
+POOL_SIZE = int(os.environ.get('DB_POOL_SIZE', '25'))
+MAX_OVERFLOW = int(os.environ.get('DB_MAX_OVERFLOW', '10'))
+
+
+def _get_db_engine():
+ if GCP_DB_INSTANCE: # GCP environments
+
+ def get_db_connection():
+ connector = Connector()
+ instance_string = f'{GCP_PROJECT}:{GCP_REGION}:{GCP_DB_INSTANCE}'
+ return connector.connect(
+ instance_string, 'pg8000', user=DB_USER, password=DB_PASS, db=DB_NAME
+ )
+
+ return create_engine(
+ 'postgresql+pg8000://',
+ creator=get_db_connection,
+ pool_size=POOL_SIZE,
+ max_overflow=MAX_OVERFLOW,
+ pool_pre_ping=True,
+ )
+ else:
+ host_string = (
+ f'postgresql+pg8000://{DB_USER}:{DB_PASS}@{DB_HOST}:{DB_PORT}/{DB_NAME}'
+ )
+ return create_engine(
+ host_string,
+ pool_size=POOL_SIZE,
+ max_overflow=MAX_OVERFLOW,
+ pool_pre_ping=True,
+ )
+
+
+async def async_creator():
+ loop = asyncio.get_running_loop()
+ async with Connector(loop=loop) as connector:
+ conn = await connector.connect_async(
+ f'{GCP_PROJECT}:{GCP_REGION}:{GCP_DB_INSTANCE}', # Cloud SQL instance connection name"
+ 'asyncpg',
+ user=DB_USER,
+ password=DB_PASS,
+ db=DB_NAME,
+ )
+ return conn
+
+
+def _get_async_db_engine():
+ if GCP_DB_INSTANCE: # GCP environments
+
+ def adapted_creator():
+ dbapi = engine.dialect.dbapi
+ from sqlalchemy.dialects.postgresql.asyncpg import (
+ AsyncAdapt_asyncpg_connection,
+ )
+
+ return AsyncAdapt_asyncpg_connection(
+ dbapi,
+ await_only(async_creator()),
+ prepared_statement_cache_size=100,
+ )
+
+ # create async connection pool with wrapped creator
+ return create_async_engine(
+ 'postgresql+asyncpg://',
+ creator=adapted_creator,
+ # Use NullPool to disable connection pooling and avoid event loop issues
+ poolclass=NullPool,
+ )
+ else:
+ host_string = (
+ f'postgresql+asyncpg://{DB_USER}:{DB_PASS}@{DB_HOST}:{DB_PORT}/{DB_NAME}'
+ )
+ return create_async_engine(
+ host_string,
+ # Use NullPool to disable connection pooling and avoid event loop issues
+ poolclass=NullPool,
+ )
+
+
+engine = _get_db_engine()
+session_maker = sessionmaker(bind=engine)
+
+a_engine = _get_async_db_engine()
+a_session_maker = sessionmaker(
+ bind=a_engine,
+ class_=AsyncSession,
+ expire_on_commit=False,
+ # Configure the session to use the same connection for all operations in a transaction
+ # This helps prevent the "Task got Future attached to a different loop" error
+ future=True,
+)
diff --git a/enterprise/storage/experiment_assignment.py b/enterprise/storage/experiment_assignment.py
new file mode 100644
index 0000000000..f648fa8a03
--- /dev/null
+++ b/enterprise/storage/experiment_assignment.py
@@ -0,0 +1,41 @@
+"""
+Database model for experiment assignments.
+
+This model tracks which experiments a conversation is assigned to and what variant
+they received from PostHog feature flags.
+"""
+
+import uuid
+from datetime import UTC, datetime
+
+from sqlalchemy import Column, DateTime, String, UniqueConstraint
+from storage.base import Base
+
+
+class ExperimentAssignment(Base): # type: ignore
+ __tablename__ = 'experiment_assignments'
+
+ id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+ conversation_id = Column(String, nullable=True, index=True)
+ experiment_name = Column(String, nullable=False)
+ variant = Column(String, nullable=False)
+
+ created_at = Column(
+ DateTime(timezone=True),
+ default=lambda: datetime.now(UTC), # type: ignore[attr-defined]
+ nullable=False,
+ )
+ updated_at = Column(
+ DateTime(timezone=True),
+ default=lambda: datetime.now(UTC), # type: ignore[attr-defined]
+ onupdate=lambda: datetime.now(UTC), # type: ignore[attr-defined]
+ nullable=False,
+ )
+
+ __table_args__ = (
+ UniqueConstraint(
+ 'conversation_id',
+ 'experiment_name',
+ name='uq_experiment_assignments_conversation_experiment',
+ ),
+ )
diff --git a/enterprise/storage/experiment_assignment_store.py b/enterprise/storage/experiment_assignment_store.py
new file mode 100644
index 0000000000..283315e13f
--- /dev/null
+++ b/enterprise/storage/experiment_assignment_store.py
@@ -0,0 +1,52 @@
+"""
+Store for managing experiment assignments.
+
+This store handles creating and updating experiment assignments for conversations.
+"""
+
+from sqlalchemy.dialects.postgresql import insert
+from storage.database import session_maker
+from storage.experiment_assignment import ExperimentAssignment
+
+from openhands.core.logger import openhands_logger as logger
+
+
+class ExperimentAssignmentStore:
+ """Store for managing experiment assignments."""
+
+ def update_experiment_variant(
+ self,
+ conversation_id: str,
+ experiment_name: str,
+ variant: str,
+ ) -> None:
+ """
+ Update the variant for a specific experiment.
+
+ Args:
+ conversation_id: The conversation ID
+ experiment_name: The name of the experiment
+ variant: The variant assigned
+ """
+ with session_maker() as session:
+ # Use PostgreSQL's INSERT ... ON CONFLICT DO NOTHING to handle unique constraint
+ stmt = insert(ExperimentAssignment).values(
+ conversation_id=conversation_id,
+ experiment_name=experiment_name,
+ variant=variant,
+ )
+ stmt = stmt.on_conflict_do_nothing(
+ constraint='uq_experiment_assignments_conversation_experiment'
+ )
+
+ session.execute(stmt)
+ session.commit()
+
+ logger.info(
+ 'experiment_assignment_store:upserted_variant',
+ extra={
+ 'conversation_id': conversation_id,
+ 'experiment_name': experiment_name,
+ 'variant': variant,
+ },
+ )
diff --git a/enterprise/storage/feedback.py b/enterprise/storage/feedback.py
new file mode 100644
index 0000000000..5e2145f961
--- /dev/null
+++ b/enterprise/storage/feedback.py
@@ -0,0 +1,29 @@
+from sqlalchemy import JSON, Column, DateTime, Enum, Integer, String, Text
+from sqlalchemy.sql import func
+from storage.base import Base
+
+
+class Feedback(Base): # type: ignore
+ __tablename__ = 'feedback'
+
+ id = Column(String, primary_key=True)
+ version = Column(String, nullable=False)
+ email = Column(String, nullable=False)
+ polarity = Column(
+ Enum('positive', 'negative', name='polarity_enum'), nullable=False
+ )
+ permissions = Column(
+ Enum('public', 'private', name='permissions_enum'), nullable=False
+ )
+ trajectory = Column(JSON, nullable=True)
+
+
+class ConversationFeedback(Base): # type: ignore
+ __tablename__ = 'conversation_feedback'
+
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ conversation_id = Column(String, nullable=False, index=True)
+ event_id = Column(Integer, nullable=True)
+ rating = Column(Integer, nullable=False)
+ reason = Column(Text, nullable=True)
+ created_at = Column(DateTime, nullable=False, server_default=func.now())
diff --git a/enterprise/storage/github_app_installation.py b/enterprise/storage/github_app_installation.py
new file mode 100644
index 0000000000..8432f2a5fc
--- /dev/null
+++ b/enterprise/storage/github_app_installation.py
@@ -0,0 +1,22 @@
+from sqlalchemy import Column, DateTime, Integer, String, text
+from storage.base import Base
+
+
+class GithubAppInstallation(Base): # type: ignore
+ """
+ Represents a Github App Installation with associated token.
+ """
+
+ __tablename__ = 'github_app_installations'
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ installation_id = Column(String, nullable=False)
+ encrypted_token = Column(String, nullable=False)
+ created_at = Column(
+ DateTime, server_default=text('CURRENT_TIMESTAMP'), nullable=False
+ )
+ updated_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ onupdate=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
diff --git a/enterprise/storage/gitlab_webhook.py b/enterprise/storage/gitlab_webhook.py
new file mode 100644
index 0000000000..ce58c3f55e
--- /dev/null
+++ b/enterprise/storage/gitlab_webhook.py
@@ -0,0 +1,42 @@
+import sys
+from enum import IntEnum
+
+from sqlalchemy import ARRAY, Boolean, Column, DateTime, Integer, String, Text, text
+from storage.base import Base
+
+
+class WebhookStatus(IntEnum):
+ PENDING = 0 # Conditions for installation webhook need checking
+ VERIFIED = 1 # Conditions are met for installing webhook
+ RATE_LIMITED = 2 # API was rate limited, failed to check
+ INVALID = 3 # Unexpected error occur when checking (keycloak connection, etc)
+
+
+class GitlabWebhook(Base): # type: ignore
+ """
+ Represents a Gitlab webhook configuration for a repository or group.
+ """
+
+ __tablename__ = 'gitlab_webhook'
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ group_id = Column(String, nullable=True)
+ project_id = Column(String, nullable=True)
+ user_id = Column(String, nullable=False)
+ webhook_exists = Column(Boolean, nullable=False)
+ webhook_url = Column(String, nullable=True)
+ webhook_secret = Column(String, nullable=True)
+ webhook_uuid = Column(String, nullable=True)
+ # Use Text for tests (SQLite compatibility) and ARRAY for production (PostgreSQL)
+ scopes = Column(Text if 'pytest' in sys.modules else ARRAY(Text), nullable=True)
+ last_synced = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ onupdate=text('CURRENT_TIMESTAMP'),
+ nullable=True,
+ )
+
+ def __repr__(self) -> str:
+ return (
+ f'
'
+ )
diff --git a/enterprise/storage/gitlab_webhook_store.py b/enterprise/storage/gitlab_webhook_store.py
new file mode 100644
index 0000000000..22d660fc0f
--- /dev/null
+++ b/enterprise/storage/gitlab_webhook_store.py
@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from integrations.types import GitLabResourceType
+from sqlalchemy import and_, asc, select, text, update
+from sqlalchemy.dialects.postgresql import insert
+from sqlalchemy.orm import sessionmaker
+from storage.database import a_session_maker
+from storage.gitlab_webhook import GitlabWebhook
+
+from openhands.core.logger import openhands_logger as logger
+
+
+@dataclass
+class GitlabWebhookStore:
+ a_session_maker: sessionmaker = a_session_maker
+
+ @staticmethod
+ def determine_resource_type(
+ webhook: GitlabWebhook,
+ ) -> tuple[GitLabResourceType, str]:
+ if not (webhook.group_id or webhook.project_id):
+ raise ValueError('Either project_id or group_id must be provided')
+
+ if webhook.group_id and webhook.project_id:
+ raise ValueError('Only one of project_id or group_id should be provided')
+
+ if webhook.group_id:
+ return (GitLabResourceType.GROUP, webhook.group_id)
+ return (GitLabResourceType.PROJECT, webhook.project_id)
+
+ async def store_webhooks(self, project_details: list[GitlabWebhook]) -> None:
+ """Store list of project details in db using UPSERT pattern
+
+ Args:
+ project_details: List of GitlabWebhook objects to store
+
+ Notes:
+ 1. Uses UPSERT (INSERT ... ON CONFLICT) to efficiently handle duplicates
+ 2. Leverages database-level constraints for uniqueness
+ 3. Performs the operation in a single database transaction
+ """
+ if not project_details:
+ return
+
+ async with self.a_session_maker() as session:
+ async with session.begin():
+ # Convert GitlabWebhook objects to dictionaries for the insert
+ # Using __dict__ and filtering out SQLAlchemy internal attributes and 'id'
+ values = [
+ {
+ k: v
+ for k, v in webhook.__dict__.items()
+ if not k.startswith('_') and k != 'id'
+ }
+ for webhook in project_details
+ ]
+
+ if values:
+ # Separate values into groups and projects
+ group_values = [v for v in values if v.get('group_id')]
+ project_values = [v for v in values if v.get('project_id')]
+
+ # Batch insert for groups
+ if group_values:
+ stmt = insert(GitlabWebhook).values(group_values)
+ stmt = stmt.on_conflict_do_nothing(index_elements=['group_id'])
+ await session.execute(stmt)
+
+ # Batch insert for projects
+ if project_values:
+ stmt = insert(GitlabWebhook).values(project_values)
+ stmt = stmt.on_conflict_do_nothing(
+ index_elements=['project_id']
+ )
+ await session.execute(stmt)
+
+ async def update_webhook(self, webhook: GitlabWebhook, update_fields: dict) -> None:
+ """Update a webhook entry based on project_id or group_id.
+
+ Args:
+ webhook: GitlabWebhook object containing the updated fields and either project_id or group_id
+ as the identifier. Only one of project_id or group_id should be non-null.
+
+ Raises:
+ ValueError: If neither project_id nor group_id is provided, or if both are provided.
+ """
+
+ resource_type, resource_id = GitlabWebhookStore.determine_resource_type(webhook)
+ async with self.a_session_maker() as session:
+ async with session.begin():
+ stmt = (
+ update(GitlabWebhook).where(GitlabWebhook.project_id == resource_id)
+ if resource_type == GitLabResourceType.PROJECT
+ else update(GitlabWebhook).where(
+ GitlabWebhook.group_id == resource_id
+ )
+ ).values(**update_fields)
+
+ await session.execute(stmt)
+
+ async def delete_webhook(self, webhook: GitlabWebhook) -> None:
+ """Delete a webhook entry based on project_id or group_id.
+
+ Args:
+ webhook: GitlabWebhook object containing either project_id or group_id
+ as the identifier. Only one of project_id or group_id should be non-null.
+
+ Raises:
+ ValueError: If neither project_id nor group_id is provided, or if both are provided.
+ """
+
+ resource_type, resource_id = GitlabWebhookStore.determine_resource_type(webhook)
+
+ logger.info(
+ 'Attempting to delete webhook',
+ extra={
+ 'resource_type': resource_type.value,
+ 'resource_id': resource_id,
+ 'user_id': getattr(webhook, 'user_id', None),
+ },
+ )
+
+ async with self.a_session_maker() as session:
+ async with session.begin():
+ # Create query based on the identifier provided
+ if resource_type == GitLabResourceType.PROJECT:
+ query = GitlabWebhook.__table__.delete().where(
+ GitlabWebhook.project_id == resource_id
+ )
+ else: # has_group_id must be True based on validation
+ query = GitlabWebhook.__table__.delete().where(
+ GitlabWebhook.group_id == resource_id
+ )
+
+ result = await session.execute(query)
+ rows_deleted = result.rowcount
+
+ if rows_deleted > 0:
+ logger.info(
+ 'Successfully deleted webhook',
+ extra={
+ 'resource_type': resource_type.value,
+ 'resource_id': resource_id,
+ 'rows_deleted': rows_deleted,
+ 'user_id': getattr(webhook, 'user_id', None),
+ },
+ )
+ else:
+ logger.warning(
+ 'No webhook found to delete',
+ extra={
+ 'resource_type': resource_type.value,
+ 'resource_id': resource_id,
+ 'user_id': getattr(webhook, 'user_id', None),
+ },
+ )
+
+ async def update_last_synced(self, webhook: GitlabWebhook) -> None:
+ """Update the last_synced timestamp for a webhook to current time.
+
+ This should be called after processing a webhook to ensure it's not
+ immediately reprocessed in the next batch.
+
+ Args:
+ webhook: GitlabWebhook object containing either project_id or group_id
+ as the identifier. Only one of project_id or group_id should be non-null.
+
+ Raises:
+ ValueError: If neither project_id nor group_id is provided, or if both are provided.
+ """
+ await self.update_webhook(webhook, {'last_synced': text('CURRENT_TIMESTAMP')})
+
+ async def filter_rows(
+ self,
+ limit: int = 100,
+ ) -> list[GitlabWebhook]:
+ """Retrieve rows that need processing (webhook doesn't exist on resource).
+
+ Args:
+ limit: Maximum number of rows to retrieve (default: 100)
+
+ Returns:
+ List of GitlabWebhook objects that need processing
+ """
+
+ async with self.a_session_maker() as session:
+ query = (
+ select(GitlabWebhook)
+ .where(GitlabWebhook.webhook_exists.is_(False))
+ .order_by(asc(GitlabWebhook.last_synced))
+ .limit(limit)
+ )
+ result = await session.execute(query)
+ webhooks = result.scalars().all()
+
+ return list(webhooks)
+
+ async def get_webhook_secret(self, webhook_uuid: str, user_id: str) -> str | None:
+ """
+ Get's webhook secret given the webhook uuid and admin keycloak user id
+ """
+ async with self.a_session_maker() as session:
+ query = (
+ select(GitlabWebhook)
+ .where(
+ and_(
+ GitlabWebhook.user_id == user_id,
+ GitlabWebhook.webhook_uuid == webhook_uuid,
+ )
+ )
+ .limit(1)
+ )
+
+ result = await session.execute(query)
+ webhooks: list[GitlabWebhook] = list(result.scalars().all())
+
+ if len(webhooks):
+ return webhooks[0].webhook_secret
+ return None
+
+ @classmethod
+ async def get_instance(cls) -> GitlabWebhookStore:
+ """Get an instance of the GitlabWebhookStore.
+
+ Returns:
+ An instance of GitlabWebhookStore
+ """
+ return GitlabWebhookStore(a_session_maker)
diff --git a/enterprise/storage/jira_conversation.py b/enterprise/storage/jira_conversation.py
new file mode 100644
index 0000000000..9b6fd0e295
--- /dev/null
+++ b/enterprise/storage/jira_conversation.py
@@ -0,0 +1,23 @@
+from sqlalchemy import Column, DateTime, Integer, String, text
+from storage.base import Base
+
+
+class JiraConversation(Base): # type: ignore
+ __tablename__ = 'jira_conversations'
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ conversation_id = Column(String, nullable=False, index=True)
+ issue_id = Column(String, nullable=False, index=True)
+ issue_key = Column(String, nullable=False, index=True)
+ parent_id = Column(String, nullable=True)
+ jira_user_id = Column(Integer, nullable=False, index=True)
+ created_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
+ updated_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ onupdate=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
diff --git a/enterprise/storage/jira_dc_conversation.py b/enterprise/storage/jira_dc_conversation.py
new file mode 100644
index 0000000000..347e5e6068
--- /dev/null
+++ b/enterprise/storage/jira_dc_conversation.py
@@ -0,0 +1,23 @@
+from sqlalchemy import Column, DateTime, Integer, String, text
+from storage.base import Base
+
+
+class JiraDcConversation(Base): # type: ignore
+ __tablename__ = 'jira_dc_conversations'
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ conversation_id = Column(String, nullable=False, index=True)
+ issue_id = Column(String, nullable=False, index=True)
+ issue_key = Column(String, nullable=False, index=True)
+ parent_id = Column(String, nullable=True)
+ jira_dc_user_id = Column(Integer, nullable=False, index=True)
+ created_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
+ updated_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ onupdate=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
diff --git a/enterprise/storage/jira_dc_integration_store.py b/enterprise/storage/jira_dc_integration_store.py
new file mode 100644
index 0000000000..c336795330
--- /dev/null
+++ b/enterprise/storage/jira_dc_integration_store.py
@@ -0,0 +1,262 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from storage.database import session_maker
+from storage.jira_dc_conversation import JiraDcConversation
+from storage.jira_dc_user import JiraDcUser
+from storage.jira_dc_workspace import JiraDcWorkspace
+
+from openhands.core.logger import openhands_logger as logger
+
+
+@dataclass
+class JiraDcIntegrationStore:
+ async def create_workspace(
+ self,
+ name: str,
+ admin_user_id: str,
+ encrypted_webhook_secret: str,
+ svc_acc_email: str,
+ encrypted_svc_acc_api_key: str,
+ status: str = 'active',
+ ) -> JiraDcWorkspace:
+ """Create a new Jira DC workspace with encrypted sensitive data."""
+
+ with session_maker() as session:
+ workspace = JiraDcWorkspace(
+ name=name.lower(),
+ admin_user_id=admin_user_id,
+ webhook_secret=encrypted_webhook_secret,
+ svc_acc_email=svc_acc_email,
+ svc_acc_api_key=encrypted_svc_acc_api_key,
+ status=status,
+ )
+ session.add(workspace)
+ session.commit()
+ session.refresh(workspace)
+ logger.info(f'[Jira DC] Created workspace {workspace.name}')
+ return workspace
+
+ async def update_workspace(
+ self,
+ id: int,
+ encrypted_webhook_secret: Optional[str] = None,
+ svc_acc_email: Optional[str] = None,
+ encrypted_svc_acc_api_key: Optional[str] = None,
+ status: Optional[str] = None,
+ ) -> JiraDcWorkspace:
+ """Update an existing Jira DC workspace with encrypted sensitive data."""
+ with session_maker() as session:
+ # Find existing workspace by ID
+ workspace = (
+ session.query(JiraDcWorkspace).filter(JiraDcWorkspace.id == id).first()
+ )
+
+ if not workspace:
+ raise ValueError(f'Workspace with ID "{id}" not found')
+
+ if encrypted_webhook_secret is not None:
+ workspace.webhook_secret = encrypted_webhook_secret
+
+ if svc_acc_email is not None:
+ workspace.svc_acc_email = svc_acc_email
+
+ if encrypted_svc_acc_api_key is not None:
+ workspace.svc_acc_api_key = encrypted_svc_acc_api_key
+
+ if status is not None:
+ workspace.status = status
+
+ session.commit()
+ session.refresh(workspace)
+
+ logger.info(f'[Jira DC] Updated workspace {workspace.name}')
+ return workspace
+
+ async def create_workspace_link(
+ self,
+ keycloak_user_id: str,
+ jira_dc_user_id: str,
+ jira_dc_workspace_id: int,
+ status: str = 'active',
+ ) -> JiraDcUser:
+ """Create a new Jira DC workspace link."""
+
+ jira_dc_user = JiraDcUser(
+ keycloak_user_id=keycloak_user_id,
+ jira_dc_user_id=jira_dc_user_id,
+ jira_dc_workspace_id=jira_dc_workspace_id,
+ status=status,
+ )
+
+ with session_maker() as session:
+ session.add(jira_dc_user)
+ session.commit()
+ session.refresh(jira_dc_user)
+
+ logger.info(
+ f'[Jira DC] Created user {jira_dc_user.id} for workspace {jira_dc_workspace_id}'
+ )
+ return jira_dc_user
+
+ async def get_workspace_by_id(self, workspace_id: int) -> Optional[JiraDcWorkspace]:
+ """Retrieve workspace by ID."""
+ with session_maker() as session:
+ return (
+ session.query(JiraDcWorkspace)
+ .filter(JiraDcWorkspace.id == workspace_id)
+ .first()
+ )
+
+ async def get_workspace_by_name(
+ self, workspace_name: str
+ ) -> Optional[JiraDcWorkspace]:
+ """Retrieve workspace by name."""
+ with session_maker() as session:
+ return (
+ session.query(JiraDcWorkspace)
+ .filter(JiraDcWorkspace.name == workspace_name.lower())
+ .first()
+ )
+
+ async def get_user_by_active_workspace(
+ self, keycloak_user_id: str
+ ) -> Optional[JiraDcUser]:
+ """Retrieve user by Keycloak user ID."""
+
+ with session_maker() as session:
+ return (
+ session.query(JiraDcUser)
+ .filter(
+ JiraDcUser.keycloak_user_id == keycloak_user_id,
+ JiraDcUser.status == 'active',
+ )
+ .first()
+ )
+
+ async def get_user_by_keycloak_id_and_workspace(
+ self, keycloak_user_id: str, jira_dc_workspace_id: int
+ ) -> Optional[JiraDcUser]:
+ """Get Jira DC user by Keycloak user ID and workspace ID."""
+ with session_maker() as session:
+ return (
+ session.query(JiraDcUser)
+ .filter(
+ JiraDcUser.keycloak_user_id == keycloak_user_id,
+ JiraDcUser.jira_dc_workspace_id == jira_dc_workspace_id,
+ )
+ .first()
+ )
+
+ async def get_active_user(
+ self, jira_dc_user_id: str, jira_dc_workspace_id: int
+ ) -> Optional[JiraDcUser]:
+ """Get Jira DC user by Keycloak user ID and workspace ID."""
+ with session_maker() as session:
+ return (
+ session.query(JiraDcUser)
+ .filter(
+ JiraDcUser.jira_dc_user_id == jira_dc_user_id,
+ JiraDcUser.jira_dc_workspace_id == jira_dc_workspace_id,
+ JiraDcUser.status == 'active',
+ )
+ .first()
+ )
+
+ async def get_active_user_by_keycloak_id_and_workspace(
+ self, keycloak_user_id: str, jira_dc_workspace_id: int
+ ) -> Optional[JiraDcUser]:
+ """Get Jira DC user by Keycloak user ID and workspace ID."""
+ with session_maker() as session:
+ return (
+ session.query(JiraDcUser)
+ .filter(
+ JiraDcUser.keycloak_user_id == keycloak_user_id,
+ JiraDcUser.jira_dc_workspace_id == jira_dc_workspace_id,
+ JiraDcUser.status == 'active',
+ )
+ .first()
+ )
+
+ async def update_user_integration_status(
+ self, keycloak_user_id: str, status: str
+ ) -> JiraDcUser:
+ """Update the status of a Jira DC user mapping."""
+
+ with session_maker() as session:
+ user = (
+ session.query(JiraDcUser)
+ .filter(JiraDcUser.keycloak_user_id == keycloak_user_id)
+ .first()
+ )
+
+ if not user:
+ raise ValueError(
+ f"User with keycloak_user_id '{keycloak_user_id}' not found"
+ )
+
+ user.status = status
+ session.commit()
+ session.refresh(user)
+ logger.info(f'[Jira DC] Updated user {keycloak_user_id} status to {status}')
+ return user
+
+ async def deactivate_workspace(self, workspace_id: int):
+ """Deactivate the workspace and all user links for a given workspace."""
+ with session_maker() as session:
+ users = (
+ session.query(JiraDcUser)
+ .filter(
+ JiraDcUser.jira_dc_workspace_id == workspace_id,
+ JiraDcUser.status == 'active',
+ )
+ .all()
+ )
+
+ for user in users:
+ user.status = 'inactive'
+ session.add(user)
+
+ workspace = (
+ session.query(JiraDcWorkspace)
+ .filter(JiraDcWorkspace.id == workspace_id)
+ .first()
+ )
+ if workspace:
+ workspace.status = 'inactive'
+ session.add(workspace)
+
+ session.commit()
+
+ logger.info(
+ f'[Jira DC] Deactivated all user links for workspace {workspace_id}'
+ )
+
+ async def create_conversation(
+ self, jira_dc_conversation: JiraDcConversation
+ ) -> None:
+ """Create a new Jira DC conversation record."""
+ with session_maker() as session:
+ session.add(jira_dc_conversation)
+ session.commit()
+
+ async def get_user_conversations_by_issue_id(
+ self, issue_id: str, jira_dc_user_id: int
+ ) -> JiraDcConversation | None:
+ """Get a Jira DC conversation by issue ID and jira dc user ID."""
+ with session_maker() as session:
+ return (
+ session.query(JiraDcConversation)
+ .filter(
+ JiraDcConversation.issue_id == issue_id,
+ JiraDcConversation.jira_dc_user_id == jira_dc_user_id,
+ )
+ .first()
+ )
+
+ @classmethod
+ def get_instance(cls) -> JiraDcIntegrationStore:
+ """Get an instance of the JiraDcIntegrationStore."""
+ return JiraDcIntegrationStore()
diff --git a/enterprise/storage/jira_dc_user.py b/enterprise/storage/jira_dc_user.py
new file mode 100644
index 0000000000..b8d95336a2
--- /dev/null
+++ b/enterprise/storage/jira_dc_user.py
@@ -0,0 +1,22 @@
+from sqlalchemy import Column, DateTime, Integer, String, text
+from storage.base import Base
+
+
+class JiraDcUser(Base): # type: ignore
+ __tablename__ = 'jira_dc_users'
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ keycloak_user_id = Column(String, nullable=False, index=True)
+ jira_dc_user_id = Column(String, nullable=False, index=True)
+ jira_dc_workspace_id = Column(Integer, nullable=False, index=True)
+ status = Column(String, nullable=False)
+ created_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
+ updated_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ onupdate=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
diff --git a/enterprise/storage/jira_dc_workspace.py b/enterprise/storage/jira_dc_workspace.py
new file mode 100644
index 0000000000..1ed05dbd3c
--- /dev/null
+++ b/enterprise/storage/jira_dc_workspace.py
@@ -0,0 +1,24 @@
+from sqlalchemy import Column, DateTime, Integer, String, text
+from storage.base import Base
+
+
+class JiraDcWorkspace(Base): # type: ignore
+ __tablename__ = 'jira_dc_workspaces'
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ name = Column(String, nullable=False)
+ admin_user_id = Column(String, nullable=False)
+ webhook_secret = Column(String, nullable=False)
+ svc_acc_email = Column(String, nullable=False)
+ svc_acc_api_key = Column(String, nullable=False)
+ status = Column(String, nullable=False)
+ created_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
+ updated_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ onupdate=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
diff --git a/enterprise/storage/jira_integration_store.py b/enterprise/storage/jira_integration_store.py
new file mode 100644
index 0000000000..73d7da57f1
--- /dev/null
+++ b/enterprise/storage/jira_integration_store.py
@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from storage.database import session_maker
+from storage.jira_conversation import JiraConversation
+from storage.jira_user import JiraUser
+from storage.jira_workspace import JiraWorkspace
+
+from openhands.core.logger import openhands_logger as logger
+
+
+@dataclass
+class JiraIntegrationStore:
+ async def create_workspace(
+ self,
+ name: str,
+ jira_cloud_id: str,
+ admin_user_id: str,
+ encrypted_webhook_secret: str,
+ svc_acc_email: str,
+ encrypted_svc_acc_api_key: str,
+ status: str = 'active',
+ ) -> JiraWorkspace:
+ """Create a new Jira workspace with encrypted sensitive data."""
+
+ workspace = JiraWorkspace(
+ name=name.lower(),
+ jira_cloud_id=jira_cloud_id,
+ admin_user_id=admin_user_id,
+ webhook_secret=encrypted_webhook_secret,
+ svc_acc_email=svc_acc_email,
+ svc_acc_api_key=encrypted_svc_acc_api_key,
+ status=status,
+ )
+
+ with session_maker() as session:
+ session.add(workspace)
+ session.commit()
+ session.refresh(workspace)
+
+ logger.info(f'[Jira] Created workspace {workspace.name}')
+ return workspace
+
+ async def update_workspace(
+ self,
+ id: int,
+ jira_cloud_id: Optional[str] = None,
+ encrypted_webhook_secret: Optional[str] = None,
+ svc_acc_email: Optional[str] = None,
+ encrypted_svc_acc_api_key: Optional[str] = None,
+ status: Optional[str] = None,
+ ) -> JiraWorkspace:
+ """Update an existing Jira workspace with encrypted sensitive data."""
+ with session_maker() as session:
+ # Find existing workspace by ID
+ workspace = (
+ session.query(JiraWorkspace).filter(JiraWorkspace.id == id).first()
+ )
+
+ if not workspace:
+ raise ValueError(f'Workspace with ID "{id}" not found')
+
+ if jira_cloud_id is not None:
+ workspace.jira_cloud_id = jira_cloud_id
+
+ if encrypted_webhook_secret is not None:
+ workspace.webhook_secret = encrypted_webhook_secret
+
+ if svc_acc_email is not None:
+ workspace.svc_acc_email = svc_acc_email
+
+ if encrypted_svc_acc_api_key is not None:
+ workspace.svc_acc_api_key = encrypted_svc_acc_api_key
+
+ if status is not None:
+ workspace.status = status
+
+ session.commit()
+ session.refresh(workspace)
+
+ logger.info(f'[Jira] Updated workspace {workspace.name}')
+ return workspace
+
+ async def create_workspace_link(
+ self,
+ keycloak_user_id: str,
+ jira_user_id: str,
+ jira_workspace_id: int,
+ status: str = 'active',
+ ) -> JiraUser:
+ """Create a new Jira workspace link."""
+
+ jira_user = JiraUser(
+ keycloak_user_id=keycloak_user_id,
+ jira_user_id=jira_user_id,
+ jira_workspace_id=jira_workspace_id,
+ status=status,
+ )
+
+ with session_maker() as session:
+ session.add(jira_user)
+ session.commit()
+ session.refresh(jira_user)
+
+ logger.info(
+ f'[Jira] Created user {jira_user.id} for workspace {jira_workspace_id}'
+ )
+ return jira_user
+
+ async def get_workspace_by_id(self, workspace_id: int) -> Optional[JiraWorkspace]:
+ """Retrieve workspace by ID."""
+ with session_maker() as session:
+ return (
+ session.query(JiraWorkspace)
+ .filter(JiraWorkspace.id == workspace_id)
+ .first()
+ )
+
+ async def get_workspace_by_name(
+ self, workspace_name: str
+ ) -> Optional[JiraWorkspace]:
+ """Retrieve workspace by name."""
+ with session_maker() as session:
+ return (
+ session.query(JiraWorkspace)
+ .filter(JiraWorkspace.name == workspace_name.lower())
+ .first()
+ )
+
+ async def get_user_by_active_workspace(
+ self, keycloak_user_id: str
+ ) -> Optional[JiraUser]:
+ """Get Jira user by Keycloak user ID."""
+ with session_maker() as session:
+ return (
+ session.query(JiraUser)
+ .filter(
+ JiraUser.keycloak_user_id == keycloak_user_id,
+ JiraUser.status == 'active',
+ )
+ .first()
+ )
+
+ async def get_user_by_keycloak_id_and_workspace(
+ self, keycloak_user_id: str, jira_workspace_id: int
+ ) -> Optional[JiraUser]:
+ """Get Jira user by Keycloak user ID and workspace ID."""
+ with session_maker() as session:
+ return (
+ session.query(JiraUser)
+ .filter(
+ JiraUser.keycloak_user_id == keycloak_user_id,
+ JiraUser.jira_workspace_id == jira_workspace_id,
+ )
+ .first()
+ )
+
+ async def get_active_user(
+ self, jira_user_id: str, jira_workspace_id: int
+ ) -> Optional[JiraUser]:
+ """Get Jira user by Keycloak user ID and workspace ID."""
+ with session_maker() as session:
+ return (
+ session.query(JiraUser)
+ .filter(
+ JiraUser.jira_user_id == jira_user_id,
+ JiraUser.jira_workspace_id == jira_workspace_id,
+ JiraUser.status == 'active',
+ )
+ .first()
+ )
+
+ async def update_user_integration_status(
+ self, keycloak_user_id: str, status: str
+ ) -> JiraUser:
+ """Update Jira user integration status."""
+ with session_maker() as session:
+ jira_user = (
+ session.query(JiraUser)
+ .filter(JiraUser.keycloak_user_id == keycloak_user_id)
+ .first()
+ )
+
+ if not jira_user:
+ raise ValueError(
+ f'Jira user not found for Keycloak ID: {keycloak_user_id}'
+ )
+
+ jira_user.status = status
+ session.commit()
+ session.refresh(jira_user)
+
+ logger.info(f'[Jira] Updated user {keycloak_user_id} status to {status}')
+ return jira_user
+
+ async def deactivate_workspace(self, workspace_id: int):
+ """Deactivate the workspace and all user links for a given workspace."""
+ with session_maker() as session:
+ users = (
+ session.query(JiraUser)
+ .filter(
+ JiraUser.jira_workspace_id == workspace_id,
+ JiraUser.status == 'active',
+ )
+ .all()
+ )
+
+ for user in users:
+ user.status = 'inactive'
+ session.add(user)
+
+ workspace = (
+ session.query(JiraWorkspace)
+ .filter(JiraWorkspace.id == workspace_id)
+ .first()
+ )
+ if workspace:
+ workspace.status = 'inactive'
+ session.add(workspace)
+
+ session.commit()
+
+ logger.info(f'[Jira] Deactivated all user links for workspace {workspace_id}')
+
+ async def create_conversation(self, jira_conversation: JiraConversation) -> None:
+ """Create a new Jira conversation record."""
+ with session_maker() as session:
+ session.add(jira_conversation)
+ session.commit()
+
+ async def get_user_conversations_by_issue_id(
+ self, issue_id: str, jira_user_id: int
+ ) -> JiraConversation | None:
+ """Get a Jira conversation by issue ID and jira user ID."""
+ with session_maker() as session:
+ return (
+ session.query(JiraConversation)
+ .filter(
+ JiraConversation.issue_id == issue_id,
+ JiraConversation.jira_user_id == jira_user_id,
+ )
+ .first()
+ )
+
+ @classmethod
+ def get_instance(cls) -> JiraIntegrationStore:
+ """Get an instance of the JiraIntegrationStore."""
+ return JiraIntegrationStore()
diff --git a/enterprise/storage/jira_user.py b/enterprise/storage/jira_user.py
new file mode 100644
index 0000000000..5fcde8b4d0
--- /dev/null
+++ b/enterprise/storage/jira_user.py
@@ -0,0 +1,22 @@
+from sqlalchemy import Column, DateTime, Integer, String, text
+from storage.base import Base
+
+
+class JiraUser(Base): # type: ignore
+ __tablename__ = 'jira_users'
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ keycloak_user_id = Column(String, nullable=False, index=True)
+ jira_user_id = Column(String, nullable=False, index=True)
+ jira_workspace_id = Column(Integer, nullable=False, index=True)
+ status = Column(String, nullable=False)
+ created_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
+ updated_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ onupdate=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
diff --git a/enterprise/storage/jira_workspace.py b/enterprise/storage/jira_workspace.py
new file mode 100644
index 0000000000..828d872fc4
--- /dev/null
+++ b/enterprise/storage/jira_workspace.py
@@ -0,0 +1,25 @@
+from sqlalchemy import Column, DateTime, Integer, String, text
+from storage.base import Base
+
+
+class JiraWorkspace(Base): # type: ignore
+ __tablename__ = 'jira_workspaces'
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ name = Column(String, nullable=False)
+ jira_cloud_id = Column(String, nullable=False)
+ admin_user_id = Column(String, nullable=False)
+ webhook_secret = Column(String, nullable=False)
+ svc_acc_email = Column(String, nullable=False)
+ svc_acc_api_key = Column(String, nullable=False)
+ status = Column(String, nullable=False)
+ created_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
+ updated_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ onupdate=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
diff --git a/enterprise/storage/linear_conversation.py b/enterprise/storage/linear_conversation.py
new file mode 100644
index 0000000000..d911a69459
--- /dev/null
+++ b/enterprise/storage/linear_conversation.py
@@ -0,0 +1,23 @@
+from sqlalchemy import Column, DateTime, Integer, String, text
+from storage.base import Base
+
+
+class LinearConversation(Base): # type: ignore
+ __tablename__ = 'linear_conversations'
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ conversation_id = Column(String, nullable=False, index=True)
+ issue_id = Column(String, nullable=False, index=True)
+ issue_key = Column(String, nullable=False, index=True)
+ parent_id = Column(String, nullable=True)
+ linear_user_id = Column(Integer, nullable=False, index=True)
+ created_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
+ updated_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ onupdate=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
diff --git a/enterprise/storage/linear_integration_store.py b/enterprise/storage/linear_integration_store.py
new file mode 100644
index 0000000000..30f2eff624
--- /dev/null
+++ b/enterprise/storage/linear_integration_store.py
@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from storage.database import session_maker
+from storage.linear_conversation import LinearConversation
+from storage.linear_user import LinearUser
+from storage.linear_workspace import LinearWorkspace
+
+from openhands.core.logger import openhands_logger as logger
+
+
+@dataclass
+class LinearIntegrationStore:
+ async def create_workspace(
+ self,
+ name: str,
+ linear_org_id: str,
+ admin_user_id: str,
+ encrypted_webhook_secret: str,
+ svc_acc_email: str,
+ encrypted_svc_acc_api_key: str,
+ status: str = 'active',
+ ) -> LinearWorkspace:
+ """Create a new Linear workspace with encrypted sensitive data."""
+
+ workspace = LinearWorkspace(
+ name=name.lower(),
+ linear_org_id=linear_org_id,
+ admin_user_id=admin_user_id,
+ webhook_secret=encrypted_webhook_secret,
+ svc_acc_email=svc_acc_email,
+ svc_acc_api_key=encrypted_svc_acc_api_key,
+ status=status,
+ )
+
+ with session_maker() as session:
+ session.add(workspace)
+ session.commit()
+ session.refresh(workspace)
+
+ logger.info(f'[Linear] Created workspace {workspace.name}')
+ return workspace
+
+ async def update_workspace(
+ self,
+ id: int,
+ linear_org_id: Optional[str] = None,
+ encrypted_webhook_secret: Optional[str] = None,
+ svc_acc_email: Optional[str] = None,
+ encrypted_svc_acc_api_key: Optional[str] = None,
+ status: Optional[str] = None,
+ ) -> LinearWorkspace:
+ """Update an existing Linear workspace with encrypted sensitive data."""
+ with session_maker() as session:
+ # Find existing workspace by ID
+ workspace = (
+ session.query(LinearWorkspace).filter(LinearWorkspace.id == id).first()
+ )
+
+ if not workspace:
+ raise ValueError(f'Workspace with ID "{id}" not found')
+
+ if linear_org_id is not None:
+ workspace.linear_org_id = linear_org_id
+
+ if encrypted_webhook_secret is not None:
+ workspace.webhook_secret = encrypted_webhook_secret
+
+ if svc_acc_email is not None:
+ workspace.svc_acc_email = svc_acc_email
+
+ if encrypted_svc_acc_api_key is not None:
+ workspace.svc_acc_api_key = encrypted_svc_acc_api_key
+
+ if status is not None:
+ workspace.status = status
+
+ session.commit()
+ session.refresh(workspace)
+
+ logger.info(f'[Linear] Updated workspace {workspace.name}')
+ return workspace
+
+ async def create_workspace_link(
+ self,
+ keycloak_user_id: str,
+ linear_user_id: str,
+ linear_workspace_id: int,
+ status: str = 'active',
+ ) -> LinearUser:
+ """Create a new Linear workspace link."""
+ linear_user = LinearUser(
+ keycloak_user_id=keycloak_user_id,
+ linear_user_id=linear_user_id,
+ linear_workspace_id=linear_workspace_id,
+ status=status,
+ )
+
+ with session_maker() as session:
+ session.add(linear_user)
+ session.commit()
+ session.refresh(linear_user)
+
+ logger.info(
+ f'[Linear] Created user {linear_user.id} for workspace {linear_workspace_id}'
+ )
+ return linear_user
+
+ async def get_workspace_by_id(self, workspace_id: int) -> Optional[LinearWorkspace]:
+ """Retrieve workspace by ID."""
+ with session_maker() as session:
+ return (
+ session.query(LinearWorkspace)
+ .filter(LinearWorkspace.id == workspace_id)
+ .first()
+ )
+
+ async def get_workspace_by_name(
+ self, workspace_name: str
+ ) -> Optional[LinearWorkspace]:
+ """Retrieve workspace by name."""
+ with session_maker() as session:
+ return (
+ session.query(LinearWorkspace)
+ .filter(LinearWorkspace.name == workspace_name.lower())
+ .first()
+ )
+
+ async def get_user_by_active_workspace(
+ self, keycloak_user_id: str
+ ) -> LinearUser | None:
+ """Get Linear user by Keycloak user ID."""
+ with session_maker() as session:
+ return (
+ session.query(LinearUser)
+ .filter(
+ LinearUser.keycloak_user_id == keycloak_user_id,
+ LinearUser.status == 'active',
+ )
+ .first()
+ )
+
+ async def get_user_by_keycloak_id_and_workspace(
+ self, keycloak_user_id: str, linear_workspace_id: int
+ ) -> Optional[LinearUser]:
+ """Get Linear user by Keycloak user ID and workspace ID."""
+ with session_maker() as session:
+ return (
+ session.query(LinearUser)
+ .filter(
+ LinearUser.keycloak_user_id == keycloak_user_id,
+ LinearUser.linear_workspace_id == linear_workspace_id,
+ )
+ .first()
+ )
+
+ async def get_active_user(
+ self, linear_user_id: str, linear_workspace_id: int
+ ) -> Optional[LinearUser]:
+ """Get Linear user by Keycloak user ID and workspace ID."""
+ with session_maker() as session:
+ return (
+ session.query(LinearUser)
+ .filter(
+ LinearUser.linear_user_id == linear_user_id,
+ LinearUser.linear_workspace_id == linear_workspace_id,
+ LinearUser.status == 'active',
+ )
+ .first()
+ )
+
+ async def update_user_integration_status(
+ self, keycloak_user_id: str, status: str
+ ) -> LinearUser:
+ """Update Linear user integration status."""
+ with session_maker() as session:
+ linear_user = (
+ session.query(LinearUser)
+ .filter(LinearUser.keycloak_user_id == keycloak_user_id)
+ .first()
+ )
+
+ if not linear_user:
+ raise ValueError(
+ f'Linear user not found for Keycloak ID: {keycloak_user_id}'
+ )
+
+ linear_user.status = status
+ session.commit()
+ session.refresh(linear_user)
+
+ logger.info(f'[Linear] Updated user {keycloak_user_id} status to {status}')
+ return linear_user
+
+ async def deactivate_workspace(self, workspace_id: int):
+ """Deactivate the workspace and all user links for a given workspace."""
+ with session_maker() as session:
+ users = (
+ session.query(LinearUser)
+ .filter(
+ LinearUser.linear_workspace_id == workspace_id,
+ LinearUser.status == 'active',
+ )
+ .all()
+ )
+
+ for user in users:
+ user.status = 'inactive'
+ session.add(user)
+
+ workspace = (
+ session.query(LinearWorkspace)
+ .filter(LinearWorkspace.id == workspace_id)
+ .first()
+ )
+ if workspace:
+ workspace.status = 'inactive'
+ session.add(workspace)
+
+ session.commit()
+
+ logger.info(f'[Jira] Deactivated all user links for workspace {workspace_id}')
+
+ async def create_conversation(
+ self, linear_conversation: LinearConversation
+ ) -> None:
+ """Create a new Linear conversation record."""
+ with session_maker() as session:
+ session.add(linear_conversation)
+ session.commit()
+
+ async def get_user_conversations_by_issue_id(
+ self, issue_id: str, linear_user_id: int
+ ) -> LinearConversation | None:
+ """Get a Linear conversation by issue ID and linear user ID."""
+ with session_maker() as session:
+ return (
+ session.query(LinearConversation)
+ .filter(
+ LinearConversation.issue_id == issue_id,
+ LinearConversation.linear_user_id == linear_user_id,
+ )
+ .first()
+ )
+
+ @classmethod
+ def get_instance(cls) -> LinearIntegrationStore:
+ """Get an instance of the LinearIntegrationStore."""
+ return LinearIntegrationStore()
diff --git a/enterprise/storage/linear_user.py b/enterprise/storage/linear_user.py
new file mode 100644
index 0000000000..a3ff2de43f
--- /dev/null
+++ b/enterprise/storage/linear_user.py
@@ -0,0 +1,22 @@
+from sqlalchemy import Column, DateTime, Integer, String, text
+from storage.base import Base
+
+
+class LinearUser(Base): # type: ignore
+ __tablename__ = 'linear_users'
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ keycloak_user_id = Column(String, nullable=False, index=True)
+ linear_user_id = Column(String, nullable=False, index=True)
+ linear_workspace_id = Column(Integer, nullable=False, index=True)
+ status = Column(String, nullable=False)
+ created_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
+ updated_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ onupdate=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
diff --git a/enterprise/storage/linear_workspace.py b/enterprise/storage/linear_workspace.py
new file mode 100644
index 0000000000..0f7774c685
--- /dev/null
+++ b/enterprise/storage/linear_workspace.py
@@ -0,0 +1,25 @@
+from sqlalchemy import Column, DateTime, Integer, String, text
+from storage.base import Base
+
+
+class LinearWorkspace(Base): # type: ignore
+ __tablename__ = 'linear_workspaces'
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ name = Column(String, nullable=False)
+ linear_org_id = Column(String, nullable=False)
+ admin_user_id = Column(String, nullable=False)
+ webhook_secret = Column(String, nullable=False)
+ svc_acc_email = Column(String, nullable=False)
+ svc_acc_api_key = Column(String, nullable=False)
+ status = Column(String, nullable=False)
+ created_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
+ updated_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ onupdate=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
diff --git a/enterprise/storage/maintenance_task.py b/enterprise/storage/maintenance_task.py
new file mode 100644
index 0000000000..d5567343ce
--- /dev/null
+++ b/enterprise/storage/maintenance_task.py
@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+from enum import Enum
+from typing import Type
+
+from pydantic import BaseModel, ConfigDict
+from sqlalchemy import Column, DateTime, Integer, String, Text, text
+from sqlalchemy import Enum as SQLEnum
+from sqlalchemy.dialects.postgresql import JSON
+from storage.base import Base
+
+from openhands.utils.import_utils import get_impl
+
+
+class MaintenanceTaskProcessor(BaseModel, ABC):
+ """
+ Abstract base class for maintenance task processors.
+
+ Maintenance processors are invoked to perform background maintenance
+ tasks such as upgrading user settings, cleaning up data, etc.
+ """
+
+ model_config = ConfigDict(
+ # Allow extra fields for flexibility
+ extra='allow',
+ # Allow arbitrary types
+ arbitrary_types_allowed=True,
+ )
+
+ @abstractmethod
+ async def __call__(self, task: MaintenanceTask) -> dict:
+ """
+ Process a maintenance task.
+
+ Args:
+ task: The maintenance task to process
+
+ Returns:
+ dict: Information about the task execution to store in the info column
+ """
+
+
+class MaintenanceTaskStatus(Enum):
+ """Status of a maintenance task."""
+
+ INACTIVE = 'INACTIVE'
+ PENDING = 'PENDING'
+ WORKING = 'WORKING'
+ COMPLETED = 'COMPLETED'
+ ERROR = 'ERROR'
+
+
+class MaintenanceTask(Base): # type: ignore
+ """
+ Model for storing maintenance tasks that perform background operations.
+ """
+
+ __tablename__ = 'maintenance_tasks'
+
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ status = Column(
+ SQLEnum(MaintenanceTaskStatus),
+ nullable=False,
+ default=MaintenanceTaskStatus.INACTIVE,
+ )
+ processor_type = Column(String, nullable=False)
+ processor_json = Column(Text, nullable=False)
+ delay = Column(Integer, server_default='0')
+ started_at = Column(DateTime, nullable=True)
+ info = Column(JSON, nullable=True)
+ created_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
+ updated_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ onupdate=datetime.now,
+ nullable=False,
+ )
+
+ def get_processor(self) -> MaintenanceTaskProcessor:
+ """
+ Get the processor instance from the stored processor type and JSON data.
+
+ Returns:
+ MaintenanceTaskProcessor: The processor instance
+ """
+ # Import the processor class dynamically
+ processor_type: Type[MaintenanceTaskProcessor] = get_impl(
+ MaintenanceTaskProcessor, self.processor_type
+ )
+ processor = processor_type.model_validate_json(self.processor_json)
+ return processor
+
+ def set_processor(self, processor: MaintenanceTaskProcessor) -> None:
+ """
+ Set the processor instance, storing its type and JSON representation.
+
+ Args:
+ processor: The MaintenanceTaskProcessor instance to store
+ """
+ self.processor_type = (
+ f'{processor.__class__.__module__}.{processor.__class__.__name__}'
+ )
+ self.processor_json = processor.model_dump_json()
diff --git a/enterprise/storage/offline_token_store.py b/enterprise/storage/offline_token_store.py
new file mode 100644
index 0000000000..869481125f
--- /dev/null
+++ b/enterprise/storage/offline_token_store.py
@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sqlalchemy.orm import sessionmaker
+from storage.database import session_maker
+from storage.stored_offline_token import StoredOfflineToken
+
+from openhands.core.config.openhands_config import OpenHandsConfig
+from openhands.core.logger import openhands_logger as logger
+
+
+@dataclass
+class OfflineTokenStore:
+ user_id: str
+ session_maker: sessionmaker
+ config: OpenHandsConfig
+
+ async def store_token(self, offline_token: str) -> None:
+ """Store an offline token in the database."""
+ with self.session_maker() as session:
+ token_record = (
+ session.query(StoredOfflineToken)
+ .filter(StoredOfflineToken.user_id == self.user_id)
+ .first()
+ )
+
+ if token_record:
+ token_record.offline_token = offline_token
+ else:
+ token_record = StoredOfflineToken(
+ user_id=self.user_id, offline_token=offline_token
+ )
+ session.add(token_record)
+ session.commit()
+
+ async def load_token(self) -> str | None:
+ """Load an offline token from the database."""
+ with self.session_maker() as session:
+ token_record = (
+ session.query(StoredOfflineToken)
+ .filter(StoredOfflineToken.user_id == self.user_id)
+ .first()
+ )
+
+ if not token_record:
+ return None
+
+ return token_record.offline_token
+
+ @classmethod
+ async def get_instance(
+ cls, config: OpenHandsConfig, user_id: str
+ ) -> OfflineTokenStore:
+ """Get an instance of the OfflineTokenStore."""
+ logger.debug(f'offline_token_store.get_instance::{user_id}')
+ if user_id:
+ user_id = str(user_id)
+ return OfflineTokenStore(user_id, session_maker, config)
diff --git a/enterprise/storage/openhands_pr.py b/enterprise/storage/openhands_pr.py
new file mode 100644
index 0000000000..5a2ae6acb3
--- /dev/null
+++ b/enterprise/storage/openhands_pr.py
@@ -0,0 +1,67 @@
+from integrations.types import PRStatus
+from sqlalchemy import (
+ Boolean,
+ Column,
+ DateTime,
+ Enum,
+ Identity,
+ Integer,
+ String,
+ text,
+)
+from storage.base import Base
+
+
+class OpenhandsPR(Base): # type: ignore
+ """
+ Represents a pull request created by OpenHands.
+ """
+
+ __tablename__ = 'openhands_prs'
+ id = Column(Integer, Identity(), primary_key=True)
+ repo_id = Column(String, nullable=False, index=True)
+ repo_name = Column(String, nullable=False)
+ pr_number = Column(Integer, nullable=False, index=True)
+ status = Column(
+ Enum(PRStatus),
+ nullable=False,
+ index=True,
+ )
+ provider = Column(String, nullable=False)
+ installation_id = Column(String, nullable=True)
+ private = Column(Boolean, nullable=True)
+
+ # PR metrics columns (optional fields as all providers may not include this information, and will require post processing to enrich)
+ num_reviewers = Column(Integer, nullable=True)
+ num_commits = Column(Integer, nullable=True)
+ num_review_comments = Column(Integer, nullable=True)
+ num_general_comments = Column(Integer, nullable=True)
+ num_changed_files = Column(Integer, nullable=True)
+ num_additions = Column(Integer, nullable=True)
+ num_deletions = Column(Integer, nullable=True)
+ merged = Column(Boolean, nullable=True)
+
+ # Fields that will definitely require post processing to enrich
+ openhands_helped_author = Column(Boolean, nullable=True)
+ num_openhands_commits = Column(Integer, nullable=True)
+ num_openhands_review_comments = Column(Integer, nullable=True)
+ num_openhands_general_comments = Column(Integer, nullable=True)
+
+ # Attributes to track progress on enrichment
+ processed = Column(Boolean, nullable=False, server_default=text('FALSE'))
+ process_attempts = Column(
+ Integer, nullable=False, server_default=text('0')
+ ) # Max attempts in case we hit rate limits or information is no longer accessible
+ updated_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ ) # To buffer between attempts
+ closed_at = Column(
+ DateTime,
+ nullable=False,
+ ) # Timestamp when the PR was closed
+ created_at = Column(
+ DateTime,
+ nullable=False,
+ ) # Timestamp when the PR was created
diff --git a/enterprise/storage/openhands_pr_store.py b/enterprise/storage/openhands_pr_store.py
new file mode 100644
index 0000000000..7bc52369f4
--- /dev/null
+++ b/enterprise/storage/openhands_pr_store.py
@@ -0,0 +1,158 @@
+from dataclasses import dataclass
+from datetime import datetime
+
+from sqlalchemy import and_, desc
+from sqlalchemy.orm import sessionmaker
+from storage.database import session_maker
+from storage.openhands_pr import OpenhandsPR
+
+from openhands.core.logger import openhands_logger as logger
+from openhands.integrations.service_types import ProviderType
+
+
+@dataclass
+class OpenhandsPRStore:
+ session_maker: sessionmaker
+
+ def insert_pr(self, pr: OpenhandsPR) -> None:
+ """
+ Insert a new PR or delete and recreate if repo_id and pr_number already exist.
+ """
+ with self.session_maker() as session:
+ # Check if PR already exists
+ existing_pr = (
+ session.query(OpenhandsPR)
+ .filter(
+ OpenhandsPR.repo_id == pr.repo_id,
+ OpenhandsPR.pr_number == pr.pr_number,
+ OpenhandsPR.provider == pr.provider,
+ )
+ .first()
+ )
+
+ if existing_pr:
+ # Delete existing PR
+ session.delete(existing_pr)
+ session.flush()
+
+ session.add(pr)
+ session.commit()
+
+ def increment_process_attempts(self, repo_id: str, pr_number: int) -> bool:
+ """
+ Increment the process attempts counter for a PR.
+
+ Args:
+ repo_id: Repository identifier
+ pr_number: Pull request number
+
+ Returns:
+ True if PR was found and updated, False otherwise
+ """
+ with self.session_maker() as session:
+ pr = (
+ session.query(OpenhandsPR)
+ .filter(
+ OpenhandsPR.repo_id == repo_id, OpenhandsPR.pr_number == pr_number
+ )
+ .first()
+ )
+
+ if pr:
+ pr.process_attempts += 1
+ session.merge(pr)
+ session.commit()
+ return True
+ return False
+
+ def update_pr_openhands_stats(
+ self,
+ repo_id: str,
+ pr_number: int,
+ original_updated_at: datetime,
+ openhands_helped_author: bool,
+ num_openhands_commits: int,
+ num_openhands_review_comments: int,
+ num_openhands_general_comments: int,
+ ) -> bool:
+ """
+ Update OpenHands statistics for a PR with row-level locking and timestamp validation.
+
+ Args:
+ repo_id: Repository identifier
+ pr_number: Pull request number
+ original_updated_at: Original updated_at timestamp to check for concurrent modifications
+ openhands_helped_author: Whether OpenHands helped the author (1+ commits)
+ num_openhands_commits: Number of commits by OpenHands
+ num_openhands_review_comments: Number of review comments by OpenHands
+ num_openhands_general_comments: Number of PR comments (not review comments) by OpenHands
+
+ Returns:
+ True if PR was found and updated, False if not found or timestamp changed
+ """
+ with self.session_maker() as session:
+ # Use row-level locking to prevent concurrent modifications
+ pr: OpenhandsPR | None = (
+ session.query(OpenhandsPR)
+ .filter(
+ OpenhandsPR.repo_id == repo_id, OpenhandsPR.pr_number == pr_number
+ )
+ .with_for_update()
+ .first()
+ )
+
+ if not pr:
+ # Current PR snapshot is stale
+ logger.warning('Did not find PR {pr_number} for repo {repo_id}')
+ return False
+
+ # Check if the updated_at timestamp has changed (indicating concurrent modification)
+ if pr.updated_at != original_updated_at:
+ # Abort transaction - the PR was modified by another process
+ session.rollback()
+ return False
+
+ # Update the OpenHands statistics
+ pr.openhands_helped_author = openhands_helped_author
+ pr.num_openhands_commits = num_openhands_commits
+ pr.num_openhands_review_comments = num_openhands_review_comments
+ pr.num_openhands_general_comments = num_openhands_general_comments
+ pr.processed = True
+
+ session.merge(pr)
+ session.commit()
+ return True
+
+ def get_unprocessed_prs(
+ self, limit: int = 50, max_retries: int = 3
+ ) -> list[OpenhandsPR]:
+ """
+ Get unprocessed PR entries from the OpenhandsPR table.
+
+ Args:
+ limit: Maximum number of PRs to retrieve (default: 50)
+
+ Returns:
+ List of OpenhandsPR objects that need processing
+ """
+ with self.session_maker() as session:
+ unprocessed_prs = (
+ session.query(OpenhandsPR)
+ .filter(
+ and_(
+ ~OpenhandsPR.processed,
+ OpenhandsPR.process_attempts < max_retries,
+ OpenhandsPR.provider == ProviderType.GITHUB.value,
+ )
+ )
+ .order_by(desc(OpenhandsPR.updated_at))
+ .limit(limit)
+ .all()
+ )
+
+ return unprocessed_prs
+
+ @classmethod
+ def get_instance(cls):
+ """Get an instance of the OpenhandsPRStore."""
+ return OpenhandsPRStore(session_maker)
diff --git a/enterprise/storage/proactive_conversation_store.py b/enterprise/storage/proactive_conversation_store.py
new file mode 100644
index 0000000000..cab626bd3c
--- /dev/null
+++ b/enterprise/storage/proactive_conversation_store.py
@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import Callable
+
+from integrations.github.github_types import (
+ WorkflowRun,
+ WorkflowRunGroup,
+ WorkflowRunStatus,
+)
+from sqlalchemy import and_, delete, select, update
+from sqlalchemy.orm import sessionmaker
+from storage.database import a_session_maker
+from storage.proactive_convos import ProactiveConversation
+
+from openhands.core.logger import openhands_logger as logger
+from openhands.integrations.service_types import ProviderType
+
+
+@dataclass
+class ProactiveConversationStore:
+ a_session_maker: sessionmaker = a_session_maker
+
+ def get_repo_id(self, provider: ProviderType, repo_id):
+ return f'{provider.value}##{repo_id}'
+
+ async def store_workflow_information(
+ self,
+ provider: ProviderType,
+ repo_id: str,
+ incoming_commit: str,
+ workflow: WorkflowRun,
+ pr_number: int,
+ get_all_workflows: Callable,
+ ) -> WorkflowRunGroup | None:
+ """
+ 1. Get the workflow based on repo_id, pr_number, commit
+ 2. If the field doesn't exist
+ - Fetch the workflow statuses and store them
+ - Create a new record
+ 3. Check the incoming workflow run payload, and update statuses based on its fields
+ 4. If all statuses are completed with at least one failure, return WorkflowGroup information else None
+
+ This method uses an explicit transaction with row-level locking to ensure
+ thread safety when multiple processes access the same database rows.
+ """
+
+ should_send = False
+ provider_repo_id = self.get_repo_id(provider, repo_id)
+
+ final_workflow_group = None
+
+ async with self.a_session_maker() as session:
+ # Start an explicit transaction with row-level locking
+ async with session.begin():
+ # Get the existing proactive conversation entry with FOR UPDATE lock
+ # This ensures exclusive access to these rows during the transaction
+ stmt = (
+ select(ProactiveConversation)
+ .where(
+ and_(
+ ProactiveConversation.repo_id == provider_repo_id,
+ ProactiveConversation.pr_number == pr_number,
+ ProactiveConversation.commit == incoming_commit,
+ )
+ )
+ .with_for_update() # This adds the row-level lock
+ )
+ result = await session.execute(stmt)
+ commit_entry = result.scalars().first()
+
+ # Interaction is complete, do not duplicate event
+ if commit_entry and commit_entry.conversation_starter_sent:
+ return None
+
+ # Get current workflow statuses
+ workflow_runs = (
+ get_all_workflows()
+ if not commit_entry
+ else commit_entry.workflow_runs
+ )
+
+ workflow_run_group = (
+ workflow_runs
+ if isinstance(workflow_runs, WorkflowRunGroup)
+ else WorkflowRunGroup(**workflow_runs)
+ )
+
+ # Update with latest incoming workflow information
+ workflow_run_group.runs[workflow.id] = workflow
+
+ statuses = [
+ workflow.status for _, workflow in workflow_run_group.runs.items()
+ ]
+
+ is_none_pending = all(
+ status != WorkflowRunStatus.PENDING for status in statuses
+ )
+
+ if is_none_pending:
+ should_send = WorkflowRunStatus.FAILURE in statuses
+
+ if should_send:
+ final_workflow_group = workflow_run_group
+
+ if commit_entry:
+ # Update existing entry (either with workflow status updates, or marking as comment sent)
+ await session.execute(
+ update(ProactiveConversation)
+ .where(
+ ProactiveConversation.repo_id == provider_repo_id,
+ ProactiveConversation.pr_number == pr_number,
+ ProactiveConversation.commit == incoming_commit,
+ )
+ .values(
+ workflow_runs=workflow_run_group.model_dump(),
+ conversation_starter_sent=should_send,
+ )
+ )
+ else:
+ convo_record = ProactiveConversation(
+ repo_id=provider_repo_id,
+ pr_number=pr_number,
+ commit=incoming_commit,
+ workflow_runs=workflow_run_group.model_dump(),
+ conversation_starter_sent=should_send,
+ )
+ session.add(convo_record)
+
+ return final_workflow_group
+
+ async def clean_old_convos(self, older_than_minutes=30):
+ """
+ Clean up proactive conversation records that are older than the specified time.
+
+ Args:
+ older_than_minutes: Number of minutes. Records older than this will be deleted.
+ Defaults to 30 minutes.
+ """
+
+ # Calculate the cutoff time (current time - older_than_minutes)
+ cutoff_time = datetime.now(UTC) - timedelta(minutes=older_than_minutes)
+
+ async with self.a_session_maker() as session:
+ async with session.begin():
+ # Delete records older than the cutoff time
+ delete_stmt = delete(ProactiveConversation).where(
+ ProactiveConversation.last_updated_at < cutoff_time
+ )
+ result = await session.execute(delete_stmt)
+
+ # Log the number of deleted records
+ deleted_count = result.rowcount
+ logger.info(
+ f'Deleted {deleted_count} proactive conversation records older than {older_than_minutes} minutes'
+ )
+
+ @classmethod
+ async def get_instance(cls) -> ProactiveConversationStore:
+ """Get an instance of the GitlabWebhookStore.
+
+ Returns:
+ An instance of GitlabWebhookStore
+ """
+ return ProactiveConversationStore(a_session_maker)
diff --git a/enterprise/storage/proactive_convos.py b/enterprise/storage/proactive_convos.py
new file mode 100644
index 0000000000..d82c5fce39
--- /dev/null
+++ b/enterprise/storage/proactive_convos.py
@@ -0,0 +1,18 @@
+from datetime import UTC, datetime
+
+from sqlalchemy import JSON, Boolean, Column, DateTime, Integer, String
+from storage.base import Base
+
+
+class ProactiveConversation(Base):
+ __tablename__ = 'proactive_conversation_table'
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ repo_id = Column(String, nullable=False)
+ pr_number = Column(Integer, nullable=False)
+ workflow_runs = Column(JSON, nullable=False)
+ commit = Column(String, nullable=False)
+ conversation_starter_sent = Column(Boolean, nullable=False, default=False)
+ last_updated_at = Column(
+ DateTime(timezone=True),
+ default=lambda: datetime.now(UTC),
+ )
diff --git a/enterprise/storage/redis.py b/enterprise/storage/redis.py
new file mode 100644
index 0000000000..3e43730bde
--- /dev/null
+++ b/enterprise/storage/redis.py
@@ -0,0 +1,23 @@
+import os
+
+import redis
+
+# Redis configuration
+REDIS_HOST = os.environ.get('REDIS_HOST', 'localhost')
+REDIS_PORT = int(os.environ.get('REDIS_PORT', '6379'))
+REDIS_PASSWORD = os.environ.get('REDIS_PASSWORD', '')
+REDIS_DB = int(os.environ.get('REDIS_DB', '0'))
+
+
+def create_redis_client():
+ return redis.Redis(
+ host=REDIS_HOST,
+ port=REDIS_PORT,
+ password=REDIS_PASSWORD,
+ db=REDIS_DB,
+ socket_timeout=2,
+ )
+
+
+def get_redis_authed_url():
+ return f'redis://:{REDIS_PASSWORD}@{REDIS_HOST}:{REDIS_PORT}/{REDIS_DB}'
diff --git a/enterprise/storage/repository_store.py b/enterprise/storage/repository_store.py
new file mode 100644
index 0000000000..54db6b2548
--- /dev/null
+++ b/enterprise/storage/repository_store.py
@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sqlalchemy.orm import sessionmaker
+from storage.database import session_maker
+from storage.stored_repository import StoredRepository
+
+from openhands.core.config.openhands_config import OpenHandsConfig
+
+
+@dataclass
+class RepositoryStore:
+ session_maker: sessionmaker
+ config: OpenHandsConfig
+
+ def store_projects(self, repositories: list[StoredRepository]) -> None:
+ """
+ Store repositories in database
+
+ 1. Make sure to store repositories if its ID doesn't exist
+ 2. If repository ID already exists, make sure to only update the repo is_public and repo_name fields
+
+ This implementation uses batch operations for better performance with large numbers of repositories.
+ """
+ if not repositories:
+ return
+
+ with self.session_maker() as session:
+ # Extract all repo_ids to check
+ repo_ids = [r.repo_id for r in repositories]
+
+ # Get all existing repositories in a single query
+ existing_repos = {
+ r.repo_id: r
+ for r in session.query(StoredRepository).filter(
+ StoredRepository.repo_id.in_(repo_ids)
+ )
+ }
+
+ # Process all repositories
+ for repo in repositories:
+ if repo.repo_id in existing_repos:
+ # Update only is_public and repo_name fields for existing repositories
+ existing_repo = existing_repos[repo.repo_id]
+ existing_repo.is_public = repo.is_public
+ existing_repo.repo_name = repo.repo_name
+ else:
+ # Add new repository to the session
+ session.add(repo)
+
+ # Commit all changes
+ session.commit()
+
+ @classmethod
+ def get_instance(cls, config: OpenHandsConfig) -> RepositoryStore:
+ """Get an instance of the UserRepositoryStore."""
+ return RepositoryStore(session_maker, config)
diff --git a/enterprise/storage/saas_conversation_store.py b/enterprise/storage/saas_conversation_store.py
new file mode 100644
index 0000000000..c0fbda6d90
--- /dev/null
+++ b/enterprise/storage/saas_conversation_store.py
@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import dataclasses
+import logging
+from dataclasses import dataclass
+from datetime import UTC
+
+from sqlalchemy.orm import sessionmaker
+from storage.database import session_maker
+from storage.stored_conversation_metadata import StoredConversationMetadata
+
+from openhands.core.config.openhands_config import OpenHandsConfig
+from openhands.integrations.provider import ProviderType
+from openhands.storage.conversation.conversation_store import ConversationStore
+from openhands.storage.data_models.conversation_metadata import (
+ ConversationMetadata,
+ ConversationTrigger,
+)
+from openhands.storage.data_models.conversation_metadata_result_set import (
+ ConversationMetadataResultSet,
+)
+from openhands.utils.async_utils import call_sync_from_async
+from openhands.utils.search_utils import offset_to_page_id, page_id_to_offset
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SaasConversationStore(ConversationStore):
+ user_id: str
+ session_maker: sessionmaker
+
+ def _select_by_id(self, session, conversation_id: str):
+ return (
+ session.query(StoredConversationMetadata)
+ .filter(StoredConversationMetadata.user_id == self.user_id)
+ .filter(StoredConversationMetadata.conversation_id == conversation_id)
+ )
+
+ def _to_external_model(self, conversation_metadata: StoredConversationMetadata):
+ kwargs = {
+ c.name: getattr(conversation_metadata, c.name)
+ for c in StoredConversationMetadata.__table__.columns
+ if c.name != 'github_user_id' # Skip github_user_id field
+ }
+ # TODO: I'm not sure why the timezone is not set on the dates coming back out of the db
+ kwargs['created_at'] = kwargs['created_at'].replace(tzinfo=UTC)
+ kwargs['last_updated_at'] = kwargs['last_updated_at'].replace(tzinfo=UTC)
+ if kwargs['trigger']:
+ kwargs['trigger'] = ConversationTrigger(kwargs['trigger'])
+ if kwargs['git_provider'] and isinstance(kwargs['git_provider'], str):
+ # Convert string to ProviderType enum
+ kwargs['git_provider'] = ProviderType(kwargs['git_provider'])
+
+ return ConversationMetadata(**kwargs)
+
+ async def save_metadata(self, metadata: ConversationMetadata):
+ kwargs = dataclasses.asdict(metadata)
+ kwargs['user_id'] = self.user_id
+
+ # Convert ProviderType enum to string for storage
+ if kwargs.get('git_provider') is not None:
+ kwargs['git_provider'] = (
+ kwargs['git_provider'].value
+ if hasattr(kwargs['git_provider'], 'value')
+ else kwargs['git_provider']
+ )
+
+ stored_metadata = StoredConversationMetadata(**kwargs)
+
+ def _save_metadata():
+ with self.session_maker() as session:
+ session.merge(stored_metadata)
+ session.commit()
+
+ await call_sync_from_async(_save_metadata)
+
+ async def get_metadata(self, conversation_id: str) -> ConversationMetadata:
+ def _get_metadata():
+ with self.session_maker() as session:
+ conversation_metadata = self._select_by_id(
+ session, conversation_id
+ ).first()
+ if not conversation_metadata:
+ raise FileNotFoundError(conversation_id)
+ return self._to_external_model(conversation_metadata)
+
+ return await call_sync_from_async(_get_metadata)
+
+ async def delete_metadata(self, conversation_id: str) -> None:
+ def _delete_metadata():
+ with self.session_maker() as session:
+ self._select_by_id(session, conversation_id).delete()
+ session.commit()
+
+ await call_sync_from_async(_delete_metadata)
+
+ async def exists(self, conversation_id: str) -> bool:
+ def _exists():
+ with self.session_maker() as session:
+ result = self._select_by_id(session, conversation_id).scalar()
+ return bool(result)
+
+ return await call_sync_from_async(_exists)
+
+ async def search(
+ self,
+ page_id: str | None = None,
+ limit: int = 20,
+ ) -> ConversationMetadataResultSet:
+ offset = page_id_to_offset(page_id)
+
+ def _search():
+ with self.session_maker() as session:
+ conversations = (
+ session.query(StoredConversationMetadata)
+ .filter(StoredConversationMetadata.user_id == self.user_id)
+ .order_by(StoredConversationMetadata.created_at.desc())
+ .offset(offset)
+ .limit(limit + 1)
+ .all()
+ )
+ conversations = [self._to_external_model(c) for c in conversations]
+ current_page_size = len(conversations)
+ next_page_id = offset_to_page_id(
+ offset + limit, current_page_size > limit
+ )
+ conversations = conversations[:limit]
+ return ConversationMetadataResultSet(conversations, next_page_id)
+
+ return await call_sync_from_async(_search)
+
+ @classmethod
+ async def get_instance(
+ cls, config: OpenHandsConfig, user_id: str | None
+ ) -> ConversationStore:
+ # user_id should not be None in SaaS, should we raise?
+ return SaasConversationStore(str(user_id), session_maker)
diff --git a/enterprise/storage/saas_conversation_validator.py b/enterprise/storage/saas_conversation_validator.py
new file mode 100644
index 0000000000..27461bebc5
--- /dev/null
+++ b/enterprise/storage/saas_conversation_validator.py
@@ -0,0 +1,152 @@
+from server.auth.auth_error import AuthError, ExpiredError
+from server.auth.saas_user_auth import saas_user_auth_from_signed_token
+from server.auth.token_manager import TokenManager
+from socketio.exceptions import ConnectionRefusedError
+from storage.api_key_store import ApiKeyStore
+
+from openhands.core.config import load_openhands_config
+from openhands.core.logger import openhands_logger as logger
+from openhands.server.shared import ConversationStoreImpl
+from openhands.storage.conversation.conversation_validator import ConversationValidator
+
+
+class SaasConversationValidator(ConversationValidator):
+ """Storage for conversation metadata. May or may not support multiple users depending on the environment."""
+
+ async def _validate_api_key(self, api_key: str) -> str | None:
+ """
+ Validate an API key and return the user_id and github_user_id if valid.
+
+ Args:
+ api_key: The API key to validate
+
+ Returns:
+ A tuple of (user_id, github_user_id) if the API key is valid, None otherwise
+ """
+ try:
+ token_manager = TokenManager()
+
+ # Validate the API key and get the user_id
+ api_key_store = ApiKeyStore.get_instance()
+ user_id = api_key_store.validate_api_key(api_key)
+
+ if not user_id:
+ logger.warning('Invalid API key')
+ return None
+
+ # Get the offline token for the user
+ offline_token = await token_manager.load_offline_token(user_id)
+ if not offline_token:
+ logger.warning(f'No offline token found for user {user_id}')
+ return None
+
+ return user_id
+
+ except Exception as e:
+ logger.warning(f'Error validating API key: {str(e)}')
+ return None
+
+ async def _validate_conversation_access(
+ self, conversation_id: str, user_id: str
+ ) -> bool:
+ """
+ Validate that the user has access to the conversation.
+
+ Args:
+ conversation_id: The ID of the conversation
+ user_id: The ID of the user
+ github_user_id: The GitHub user ID, if available
+
+ Returns:
+ True if the user has access to the conversation, False otherwise
+
+ Raises:
+ ConnectionRefusedError: If the user does not have access to the conversation
+ """
+ config = load_openhands_config()
+ conversation_store = await ConversationStoreImpl.get_instance(config, user_id)
+
+ if not await conversation_store.validate_metadata(conversation_id, user_id):
+ logger.error(
+ f'User {user_id} is not allowed to join conversation {conversation_id}'
+ )
+ raise ConnectionRefusedError(
+ f'User {user_id} is not allowed to join conversation {conversation_id}'
+ )
+ return True
+
+ async def validate(
+ self,
+ conversation_id: str,
+ cookies_str: str,
+ authorization_header: str | None = None,
+ ) -> str | None:
+ """
+ Validate the conversation access using either an API key from the Authorization header
+ or a keycloak_auth cookie.
+
+ Args:
+ conversation_id: The ID of the conversation
+ cookies_str: The cookies string from the request
+ authorization_header: The Authorization header from the request, if available
+
+ Returns:
+ A tuple of (user_id, github_user_id)
+
+ Raises:
+ ConnectionRefusedError: If the user does not have access to the conversation
+ AuthError: If the authentication fails
+ RuntimeError: If there is an error with the configuration or user info
+ """
+ # Try to authenticate using Authorization header first
+ if authorization_header and authorization_header.startswith('Bearer '):
+ api_key = authorization_header.replace('Bearer ', '')
+ user_id = await self._validate_api_key(api_key)
+
+ if user_id:
+ logger.info(
+ f'User {user_id} is connecting to conversation {conversation_id} via API key'
+ )
+
+ await self._validate_conversation_access(conversation_id, user_id)
+ return user_id
+
+ # Fall back to cookie authentication
+ token_manager = TokenManager()
+ config = load_openhands_config()
+ cookies = (
+ dict(cookie.split('=', 1) for cookie in cookies_str.split('; '))
+ if cookies_str
+ else {}
+ )
+
+ signed_token = cookies.get('keycloak_auth', '')
+ if not signed_token:
+ logger.warning('No keycloak_auth cookie or valid Authorization header')
+ raise ConnectionRefusedError(
+ 'No keycloak_auth cookie or valid Authorization header'
+ )
+ if not config.jwt_secret:
+ raise RuntimeError('JWT secret not found')
+
+ try:
+ user_auth = await saas_user_auth_from_signed_token(signed_token)
+ access_token = await user_auth.get_access_token()
+ except ExpiredError:
+ raise ConnectionRefusedError('SESSION$TIMEOUT_MESSAGE')
+ if access_token is None:
+ raise AuthError('no_access_token')
+ user_info_dict = await token_manager.get_user_info(
+ access_token.get_secret_value()
+ )
+ if not user_info_dict or 'sub' not in user_info_dict:
+ logger.info(
+ f'Invalid user_info {user_info_dict} for access token {access_token}'
+ )
+ raise RuntimeError('Invalid user_info')
+ user_id = user_info_dict['sub']
+
+ logger.info(f'User {user_id} is connecting to conversation {conversation_id}')
+
+ await self._validate_conversation_access(conversation_id, user_id) # type: ignore
+ return user_id
diff --git a/enterprise/storage/saas_secrets_store.py b/enterprise/storage/saas_secrets_store.py
new file mode 100644
index 0000000000..5b1018510e
--- /dev/null
+++ b/enterprise/storage/saas_secrets_store.py
@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import hashlib
+from base64 import b64decode, b64encode
+from dataclasses import dataclass
+
+from cryptography.fernet import Fernet
+from sqlalchemy.orm import sessionmaker
+from storage.database import session_maker
+from storage.stored_user_secrets import StoredUserSecrets
+
+from openhands.core.config.openhands_config import OpenHandsConfig
+from openhands.core.logger import openhands_logger as logger
+from openhands.storage.data_models.user_secrets import UserSecrets
+from openhands.storage.secrets.secrets_store import SecretsStore
+
+
+@dataclass
+class SaasSecretsStore(SecretsStore):
+ user_id: str
+ session_maker: sessionmaker
+ config: OpenHandsConfig
+
+ async def load(self) -> UserSecrets | None:
+ if not self.user_id:
+ return None
+
+ with self.session_maker() as session:
+ # Fetch all secrets for the given user ID
+ settings = (
+ session.query(StoredUserSecrets)
+ .filter(StoredUserSecrets.keycloak_user_id == self.user_id)
+ .all()
+ )
+
+ if not settings:
+ return UserSecrets()
+
+ kwargs = {}
+ for secret in settings:
+ kwargs[secret.secret_name] = {
+ 'secret': secret.secret_value,
+ 'description': secret.description,
+ }
+
+ self._decrypt_kwargs(kwargs)
+
+ return UserSecrets(custom_secrets=kwargs) # type: ignore[arg-type]
+
+ async def store(self, item: UserSecrets):
+ with self.session_maker() as session:
+ # Incoming secrets are always the most updated ones
+ # Delete all existing records and override with incoming ones
+ session.query(StoredUserSecrets).filter(
+ StoredUserSecrets.keycloak_user_id == self.user_id
+ ).delete()
+
+ # Prepare the new secrets data
+ kwargs = item.model_dump(context={'expose_secrets': True})
+ del kwargs[
+ 'provider_tokens'
+ ] # Assuming provider_tokens is not part of custom_secrets
+ self._encrypt_kwargs(kwargs)
+
+ secrets_json = kwargs.get('custom_secrets', {})
+
+ # Extract the secrets into tuples for insertion or updating
+ secret_tuples = []
+ for secret_name, secret_info in secrets_json.items():
+ secret_value = secret_info.get('secret')
+ description = secret_info.get('description')
+
+ secret_tuples.append((secret_name, secret_value, description))
+
+ # Add the new secrets
+ for secret_name, secret_value, description in secret_tuples:
+ new_secret = StoredUserSecrets(
+ keycloak_user_id=self.user_id,
+ secret_name=secret_name,
+ secret_value=secret_value,
+ description=description,
+ )
+ session.add(new_secret)
+
+ session.commit()
+
+ def _decrypt_kwargs(self, kwargs: dict):
+ fernet = self._fernet()
+ for key, value in kwargs.items():
+ if isinstance(value, dict):
+ self._decrypt_kwargs(value)
+ continue
+
+ if value is None:
+ kwargs[key] = value
+ else:
+ value = fernet.decrypt(b64decode(value.encode())).decode()
+ kwargs[key] = value
+
+ def _encrypt_kwargs(self, kwargs: dict):
+ fernet = self._fernet()
+ for key, value in kwargs.items():
+ if isinstance(value, dict):
+ self._encrypt_kwargs(value)
+ continue
+
+ if value is None:
+ kwargs[key] = value
+ else:
+ encrypted_value = b64encode(fernet.encrypt(value.encode())).decode()
+ kwargs[key] = encrypted_value
+
+ def _fernet(self):
+ if not self.config.jwt_secret:
+ raise Exception('config.jwt_secret must be set')
+ jwt_secret = self.config.jwt_secret.get_secret_value()
+ fernet_key = b64encode(hashlib.sha256(jwt_secret.encode()).digest())
+ return Fernet(fernet_key)
+
+ @classmethod
+ async def get_instance(
+ cls,
+ config: OpenHandsConfig,
+ user_id: str | None,
+ ) -> SaasSecretsStore:
+ if not user_id:
+ raise Exception('SaasSecretsStore cannot be constructed with no user_id')
+ logger.debug(f'saas_secrets_store.get_instance::{user_id}')
+ return SaasSecretsStore(user_id, session_maker, config)
diff --git a/enterprise/storage/saas_settings_store.py b/enterprise/storage/saas_settings_store.py
new file mode 100644
index 0000000000..3614d99d49
--- /dev/null
+++ b/enterprise/storage/saas_settings_store.py
@@ -0,0 +1,393 @@
+from __future__ import annotations
+
+import binascii
+import hashlib
+import json
+import os
+from base64 import b64decode, b64encode
+from dataclasses import dataclass
+
+import httpx
+from cryptography.fernet import Fernet
+from integrations import stripe_service
+from pydantic import SecretStr
+from server.auth.token_manager import TokenManager
+from server.constants import (
+ CURRENT_USER_SETTINGS_VERSION,
+ DEFAULT_INITIAL_BUDGET,
+ LITE_LLM_API_KEY,
+ LITE_LLM_API_URL,
+ LITE_LLM_TEAM_ID,
+ REQUIRE_PAYMENT,
+ get_default_litellm_model,
+)
+from server.logger import logger
+from sqlalchemy.orm import sessionmaker
+from storage.database import session_maker
+from storage.stored_settings import StoredSettings
+from storage.user_settings import UserSettings
+
+from openhands.core.config.openhands_config import OpenHandsConfig
+from openhands.server.settings import Settings
+from openhands.storage import get_file_store
+from openhands.storage.settings.settings_store import SettingsStore
+from openhands.utils.async_utils import call_sync_from_async
+
+
+@dataclass
+class SaasSettingsStore(SettingsStore):
+ user_id: str
+ session_maker: sessionmaker
+ config: OpenHandsConfig
+
+ async def load(self) -> Settings | None:
+ if not self.user_id:
+ return None
+ with self.session_maker() as session:
+ settings = (
+ session.query(UserSettings)
+ .filter(UserSettings.keycloak_user_id == self.user_id)
+ .first()
+ )
+
+ if not settings or settings.user_version != CURRENT_USER_SETTINGS_VERSION:
+ logger.info(
+ 'saas_settings_store:load:triggering_migration',
+ extra={'user_id': self.user_id},
+ )
+ return await self.create_default_settings(settings)
+ kwargs = {
+ c.name: getattr(settings, c.name)
+ for c in UserSettings.__table__.columns
+ if c.name in Settings.model_fields
+ }
+ self._decrypt_kwargs(kwargs)
+ settings = Settings(**kwargs)
+ return settings
+
+ async def store(self, item: Settings):
+ with self.session_maker() as session:
+ existing = None
+ kwargs = {}
+ if item:
+ kwargs = item.model_dump(context={'expose_secrets': True})
+ self._encrypt_kwargs(kwargs)
+ query = session.query(UserSettings).filter(
+ UserSettings.keycloak_user_id == self.user_id
+ )
+
+ # First check if we have an existing entry in the new table
+ existing = query.first()
+
+ kwargs = {
+ key: value
+ for key, value in kwargs.items()
+ if key in UserSettings.__table__.columns
+ }
+ if existing:
+ # Update existing entry
+ for key, value in kwargs.items():
+ setattr(existing, key, value)
+ existing.user_version = CURRENT_USER_SETTINGS_VERSION
+ session.merge(existing)
+ else:
+ kwargs['keycloak_user_id'] = self.user_id
+ kwargs['user_version'] = CURRENT_USER_SETTINGS_VERSION
+ kwargs.pop('secrets_store', None) # Don't save secrets_store to db
+ settings = UserSettings(**kwargs)
+ session.add(settings)
+ session.commit()
+
+ async def create_default_settings(self, user_settings: UserSettings | None):
+ logger.info(
+ 'saas_settings_store:create_default_settings:start',
+ extra={'user_id': self.user_id},
+ )
+ # You must log in before you get default settings
+ if not self.user_id:
+ return None
+
+ # Only users that have specified a payment method get default settings
+ if REQUIRE_PAYMENT and not await stripe_service.has_payment_method(
+ self.user_id
+ ):
+ logger.info(
+ 'saas_settings_store:create_default_settings:no_payment',
+ extra={'user_id': self.user_id},
+ )
+ return None
+ settings: Settings | None = None
+ if user_settings is None:
+ settings = Settings(
+ language='en',
+ enable_proactive_conversation_starters=True,
+ )
+ elif isinstance(user_settings, UserSettings):
+ # Convert UserSettings (SQLAlchemy model) to Settings (Pydantic model)
+ kwargs = {
+ c.name: getattr(user_settings, c.name)
+ for c in UserSettings.__table__.columns
+ if c.name in Settings.model_fields
+ }
+ self._decrypt_kwargs(kwargs)
+ settings = Settings(**kwargs)
+
+ if settings:
+ settings = await self.update_settings_with_litellm_default(settings)
+ if settings is None:
+ logger.info(
+ 'saas_settings_store:create_default_settings:litellm_update_failed',
+ extra={'user_id': self.user_id},
+ )
+ return None
+
+ await self.store(settings)
+ return settings
+
+ def load_legacy_db_settings(self, github_user_id: str) -> Settings | None:
+ if not github_user_id:
+ return None
+
+ with self.session_maker() as session:
+ settings = (
+ session.query(StoredSettings)
+ .filter(StoredSettings.id == github_user_id)
+ .first()
+ )
+ if settings is None:
+ return None
+
+ logger.info(
+ 'saas_settings_store:load_legacy_db_settings:found',
+ extra={'github_user_id': github_user_id},
+ )
+ kwargs = {
+ c.name: getattr(settings, c.name)
+ for c in StoredSettings.__table__.columns
+ if c.name in Settings.model_fields
+ }
+ self._decrypt_kwargs(kwargs)
+ del kwargs['secrets_store']
+ settings = Settings(**kwargs)
+ return settings
+
+ async def load_legacy_file_store_settings(self, github_user_id: str):
+ if not github_user_id:
+ return None
+
+ file_store = get_file_store(self.config.file_store, self.config.file_store_path)
+ path = f'users/github/{github_user_id}/settings.json'
+
+ try:
+ json_str = await call_sync_from_async(file_store.read, path)
+ logger.info(
+ 'saas_settings_store:load_legacy_file_store_settings:found',
+ extra={'github_user_id': github_user_id},
+ )
+ kwargs = json.loads(json_str)
+ self._decrypt_kwargs(kwargs)
+ settings = Settings(**kwargs)
+ return settings
+ except FileNotFoundError:
+ return None
+ except Exception as e:
+ logger.error(
+ 'saas_settings_store:load_legacy_file_store_settings:error',
+ extra={'github_user_id': github_user_id, 'error': str(e)},
+ )
+ return None
+
+ async def update_settings_with_litellm_default(
+ self, settings: Settings
+ ) -> Settings | None:
+ logger.info(
+ 'saas_settings_store:update_settings_with_litellm_default:start',
+ extra={'user_id': self.user_id},
+ )
+ if LITE_LLM_API_KEY is None or LITE_LLM_API_URL is None:
+ return None
+ local_deploy = os.environ.get('LOCAL_DEPLOYMENT', None)
+ key = LITE_LLM_API_KEY
+ if not local_deploy:
+ # Get user info to add to litellm
+ token_manager = TokenManager()
+ keycloak_user_info = (
+ await token_manager.get_user_info_from_user_id(self.user_id) or {}
+ )
+
+ async with httpx.AsyncClient(
+ headers={
+ 'x-goog-api-key': LITE_LLM_API_KEY,
+ }
+ ) as client:
+ # Get the previous max budget to prevent accidental loss
+ # In Litellm a get always succeeds, regardless of whether the user actually exists
+ response = await client.get(
+ f'{LITE_LLM_API_URL}/user/info?user_id={self.user_id}'
+ )
+ response.raise_for_status()
+ response_json = response.json()
+ user_info = response_json.get('user_info') or {}
+ logger.info(
+ f'creating_litellm_user: {self.user_id}; prev_max_budget: {user_info.get("max_budget")}; prev_metadata: {user_info.get("metadata")}'
+ )
+ max_budget = user_info.get('max_budget') or DEFAULT_INITIAL_BUDGET
+ spend = user_info.get('spend') or 0
+
+ with session_maker() as session:
+ user_settings = (
+ session.query(UserSettings)
+ .filter(UserSettings.keycloak_user_id == self.user_id)
+ .first()
+ )
+ # In upgrade to V4, we no longer use billing margin, but instead apply this directly
+ # in litellm. The default billing marign was 2 before this (hence the magic numbers below)
+ if (
+ user_settings
+ and user_settings.user_version < 4
+ and user_settings.billing_margin
+ and user_settings.billing_margin != 1.0
+ ):
+ billing_margin = user_settings.billing_margin
+ logger.info(
+ 'user_settings_v4_budget_upgrade',
+ extra={
+ 'max_budget': max_budget,
+ 'billing_margin': billing_margin,
+ 'spend': spend,
+ },
+ )
+ max_budget *= billing_margin
+ spend *= billing_margin
+ user_settings.billing_margin = 1.0
+ session.commit()
+
+ email = keycloak_user_info.get('email')
+
+ # We explicitly delete here to guard against odd inherited settings on upgrade.
+ # We don't care if this fails with a 404
+ await client.post(
+ f'{LITE_LLM_API_URL}/user/delete', json={'user_ids': [self.user_id]}
+ )
+
+ # Create the new litellm user
+ response = await self._create_user_in_lite_llm(
+ client, email, max_budget, spend
+ )
+ if not response.is_success:
+ logger.warning(
+ 'duplicate_user_email',
+ extra={'user_id': self.user_id, 'email': email},
+ )
+ # Litellm insists on unique email addresses - it is possible the email address was registered with a different user.
+ response = await self._create_user_in_lite_llm(
+ client, None, max_budget, spend
+ )
+
+ # User failed to create in litellm - this is an unforseen error state...
+ if not response.is_success:
+ logger.error(
+ 'error_creating_litellm_user',
+ extra={
+ 'status_code': response.status_code,
+ 'text': response.text,
+ 'user_id': [self.user_id],
+ 'email': email,
+ 'max_budget': max_budget,
+ 'spend': spend,
+ },
+ )
+ return None
+
+ response_json = response.json()
+ key = response_json['key']
+
+ logger.info(
+ 'saas_settings_store:update_settings_with_litellm_default:user_created',
+ extra={'user_id': self.user_id},
+ )
+
+ settings.agent = 'CodeActAgent'
+ # Use the model corresponding to the current user settings version
+ settings.llm_model = get_default_litellm_model()
+ settings.llm_api_key = SecretStr(key)
+ settings.llm_base_url = LITE_LLM_API_URL
+ return settings
+
+ @classmethod
+ async def get_instance(
+ cls,
+ config: OpenHandsConfig,
+ user_id: str, # type: ignore[override]
+ ) -> SaasSettingsStore:
+ logger.debug(f'saas_settings_store.get_instance::{user_id}')
+ return SaasSettingsStore(user_id, session_maker, config)
+
+ def _decrypt_kwargs(self, kwargs: dict):
+ fernet = self._fernet()
+ for key, value in kwargs.items():
+ try:
+ if value is None:
+ continue
+ if self._should_encrypt(key):
+ if isinstance(value, SecretStr):
+ value = fernet.decrypt(
+ b64decode(value.get_secret_value().encode())
+ ).decode()
+ else:
+ value = fernet.decrypt(b64decode(value.encode())).decode()
+ kwargs[key] = value
+ except binascii.Error:
+ pass # Key is in legacy format...
+
+ def _encrypt_kwargs(self, kwargs: dict):
+ fernet = self._fernet()
+ for key, value in kwargs.items():
+ if value is None:
+ continue
+
+ if isinstance(value, dict):
+ self._encrypt_kwargs(value)
+ continue
+
+ if self._should_encrypt(key):
+ if isinstance(value, SecretStr):
+ value = b64encode(
+ fernet.encrypt(value.get_secret_value().encode())
+ ).decode()
+ else:
+ value = b64encode(fernet.encrypt(value.encode())).decode()
+ kwargs[key] = value
+
+ def _fernet(self):
+ if not self.config.jwt_secret:
+ raise ValueError('jwt_secret must be defined on config')
+ jwt_secret = self.config.jwt_secret.get_secret_value()
+ fernet_key = b64encode(hashlib.sha256(jwt_secret.encode()).digest())
+ return Fernet(fernet_key)
+
+ def _should_encrypt(self, key: str) -> bool:
+ return key in ('llm_api_key', 'llm_api_key_for_byor', 'search_api_key')
+
+ async def _create_user_in_lite_llm(
+ self, client: httpx.AsyncClient, email: str | None, max_budget: int, spend: int
+ ):
+ response = await client.post(
+ f'{LITE_LLM_API_URL}/user/new',
+ json={
+ 'user_email': email,
+ 'models': [],
+ 'max_budget': max_budget,
+ 'spend': spend,
+ 'user_id': str(self.user_id),
+ 'teams': [LITE_LLM_TEAM_ID],
+ 'auto_create_key': True,
+ 'send_invite_email': False,
+ 'metadata': {
+ 'version': CURRENT_USER_SETTINGS_VERSION,
+ 'model': get_default_litellm_model(),
+ },
+ 'key_alias': f'OpenHands Cloud - user {self.user_id}',
+ },
+ )
+ return response
diff --git a/enterprise/storage/slack_conversation.py b/enterprise/storage/slack_conversation.py
new file mode 100644
index 0000000000..d2cea4e7a5
--- /dev/null
+++ b/enterprise/storage/slack_conversation.py
@@ -0,0 +1,11 @@
+from sqlalchemy import Column, Identity, Integer, String
+from storage.base import Base
+
+
+class SlackConversation(Base): # type: ignore
+ __tablename__ = 'slack_conversation'
+ id = Column(Integer, Identity(), primary_key=True)
+ conversation_id = Column(String, nullable=False, index=True)
+ channel_id = Column(String, nullable=False)
+ keycloak_user_id = Column(String, nullable=False)
+ parent_id = Column(String, nullable=True, index=True)
diff --git a/enterprise/storage/slack_conversation_store.py b/enterprise/storage/slack_conversation_store.py
new file mode 100644
index 0000000000..2d859ee62c
--- /dev/null
+++ b/enterprise/storage/slack_conversation_store.py
@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sqlalchemy.orm import sessionmaker
+from storage.database import session_maker
+from storage.slack_conversation import SlackConversation
+
+
+@dataclass
+class SlackConversationStore:
+ session_maker: sessionmaker
+
+ async def get_slack_conversation(
+ self, channel_id: str, parent_id: str
+ ) -> SlackConversation | None:
+ """
+ Get a slack conversation by channel_id and message_ts.
+ Both parameters are required to match for a conversation to be returned.
+ """
+ with session_maker() as session:
+ conversation = (
+ session.query(SlackConversation)
+ .filter(SlackConversation.channel_id == channel_id)
+ .filter(SlackConversation.parent_id == parent_id)
+ .first()
+ )
+
+ return conversation
+
+ async def create_slack_conversation(
+ self, slack_converstion: SlackConversation
+ ) -> None:
+ with self.session_maker() as session:
+ session.merge(slack_converstion)
+ session.commit()
+
+ @classmethod
+ def get_instance(cls) -> SlackConversationStore:
+ return SlackConversationStore(session_maker)
diff --git a/enterprise/storage/slack_team.py b/enterprise/storage/slack_team.py
new file mode 100644
index 0000000000..c344e3bab5
--- /dev/null
+++ b/enterprise/storage/slack_team.py
@@ -0,0 +1,14 @@
+from sqlalchemy import Column, DateTime, Identity, Integer, String, text
+from storage.base import Base
+
+
+class SlackTeam(Base): # type: ignore
+ __tablename__ = 'slack_teams'
+ id = Column(Integer, Identity(), primary_key=True)
+ team_id = Column(String, nullable=False, index=True, unique=True)
+ bot_access_token = Column(String, nullable=False)
+ created_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
diff --git a/enterprise/storage/slack_team_store.py b/enterprise/storage/slack_team_store.py
new file mode 100644
index 0000000000..df8e2cd65d
--- /dev/null
+++ b/enterprise/storage/slack_team_store.py
@@ -0,0 +1,38 @@
+from dataclasses import dataclass
+
+from sqlalchemy.orm import sessionmaker
+from storage.database import session_maker
+from storage.slack_team import SlackTeam
+
+
+@dataclass
+class SlackTeamStore:
+ session_maker: sessionmaker
+
+ def get_team_bot_token(self, team_id: str) -> str | None:
+ """
+ Get a team's bot access token by team_id
+ """
+ with session_maker() as session:
+ team = session.query(SlackTeam).filter(SlackTeam.team_id == team_id).first()
+ return team.bot_access_token if team else None
+
+ def create_team(
+ self,
+ team_id: str,
+ bot_access_token: str,
+ ) -> SlackTeam:
+ """
+ Create a new SlackTeam
+ """
+ slack_team = SlackTeam(team_id=team_id, bot_access_token=bot_access_token)
+ with session_maker() as session:
+ session.query(SlackTeam).filter(SlackTeam.team_id == team_id).delete()
+
+ # Store the token
+ session.add(slack_team)
+ session.commit()
+
+ @classmethod
+ def get_instance(cls):
+ return SlackTeamStore(session_maker)
diff --git a/enterprise/storage/slack_user.py b/enterprise/storage/slack_user.py
new file mode 100644
index 0000000000..ba81071e2a
--- /dev/null
+++ b/enterprise/storage/slack_user.py
@@ -0,0 +1,15 @@
+from sqlalchemy import Column, DateTime, Identity, Integer, String, text
+from storage.base import Base
+
+
+class SlackUser(Base): # type: ignore
+ __tablename__ = 'slack_users'
+ id = Column(Integer, Identity(), primary_key=True)
+ keycloak_user_id = Column(String, nullable=False, index=True)
+ slack_user_id = Column(String, nullable=False, index=True)
+ slack_display_name = Column(String, nullable=False)
+ created_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
diff --git a/enterprise/storage/stored_conversation_metadata.py b/enterprise/storage/stored_conversation_metadata.py
new file mode 100644
index 0000000000..cc289e87d1
--- /dev/null
+++ b/enterprise/storage/stored_conversation_metadata.py
@@ -0,0 +1,41 @@
+import uuid
+from datetime import UTC, datetime
+
+from sqlalchemy import JSON, Column, DateTime, Float, Integer, String
+from storage.base import Base
+
+
+class StoredConversationMetadata(Base): # type: ignore
+ __tablename__ = 'conversation_metadata'
+ conversation_id = Column(
+ String, primary_key=True, default=lambda: str(uuid.uuid4())
+ )
+ github_user_id = Column(String, nullable=True) # The GitHub user ID
+ user_id = Column(String, nullable=False) # The Keycloak User ID
+ selected_repository = Column(String, nullable=True)
+ selected_branch = Column(String, nullable=True)
+ git_provider = Column(
+ String, nullable=True
+ ) # The git provider (GitHub, GitLab, etc.)
+ title = Column(String, nullable=True)
+ last_updated_at = Column(
+ DateTime(timezone=True),
+ default=lambda: datetime.now(UTC), # type: ignore[attr-defined]
+ )
+ created_at = Column(
+ DateTime(timezone=True),
+ default=lambda: datetime.now(UTC), # type: ignore[attr-defined]
+ )
+ trigger = Column(String, nullable=True)
+ pr_number = Column(
+ JSON, nullable=True
+ ) # List of PR numbers associated with the conversation
+
+ # Cost and token metrics
+ accumulated_cost = Column(Float, default=0.0)
+ prompt_tokens = Column(Integer, default=0)
+ completion_tokens = Column(Integer, default=0)
+ total_tokens = Column(Integer, default=0)
+
+ # LLM model used for the conversation
+ llm_model = Column(String, nullable=True)
diff --git a/enterprise/storage/stored_offline_token.py b/enterprise/storage/stored_offline_token.py
new file mode 100644
index 0000000000..a48c9bed64
--- /dev/null
+++ b/enterprise/storage/stored_offline_token.py
@@ -0,0 +1,18 @@
+from sqlalchemy import Column, DateTime, String, text
+from storage.base import Base
+
+
+class StoredOfflineToken(Base):
+ __tablename__ = 'offline_tokens'
+
+ user_id = Column(String(255), primary_key=True)
+ offline_token = Column(String, nullable=False)
+ created_at = Column(
+ DateTime, server_default=text('CURRENT_TIMESTAMP'), nullable=False
+ )
+ updated_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ onupdate=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
diff --git a/enterprise/storage/stored_repository.py b/enterprise/storage/stored_repository.py
new file mode 100644
index 0000000000..5e25fbce1d
--- /dev/null
+++ b/enterprise/storage/stored_repository.py
@@ -0,0 +1,16 @@
+from sqlalchemy import Boolean, Column, Integer, String
+from storage.base import Base
+
+
+class StoredRepository(Base): # type: ignore
+ """
+ Represents a repositories fetched from git providers.
+ """
+
+ __tablename__ = 'repos'
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ repo_name = Column(String, nullable=False)
+ repo_id = Column(String, nullable=False) # {provider}##{id} format
+ is_public = Column(Boolean, nullable=False)
+ has_microagent = Column(Boolean, nullable=True)
+ has_setup_script = Column(Boolean, nullable=True)
diff --git a/enterprise/storage/stored_settings.py b/enterprise/storage/stored_settings.py
new file mode 100644
index 0000000000..f9502fdd34
--- /dev/null
+++ b/enterprise/storage/stored_settings.py
@@ -0,0 +1,29 @@
+import uuid
+
+from sqlalchemy import JSON, Boolean, Column, Float, Integer, String
+from storage.base import Base
+
+
+class StoredSettings(Base): # type: ignore
+ """
+ Legacy user settings storage. This should be considered deprecated - use UserSettings isntead
+ """
+
+ __tablename__ = 'settings'
+ id = Column(String, primary_key=True, default=lambda: str(uuid.uuid4()))
+ language = Column(String, nullable=True)
+ agent = Column(String, nullable=True)
+ max_iterations = Column(Integer, nullable=True)
+ security_analyzer = Column(String, nullable=True)
+ confirmation_mode = Column(Boolean, nullable=True, default=False)
+ llm_model = Column(String, nullable=True)
+ llm_api_key = Column(String, nullable=True)
+ llm_base_url = Column(String, nullable=True)
+ remote_runtime_resource_factor = Column(Integer, nullable=True)
+ enable_default_condenser = Column(Boolean, nullable=False, default=True)
+ user_consents_to_analytics = Column(Boolean, nullable=True)
+ margin = Column(Float, nullable=True)
+ enable_sound_notifications = Column(Boolean, nullable=True, default=False)
+ sandbox_base_container_image = Column(String, nullable=True)
+ sandbox_runtime_container_image = Column(String, nullable=True)
+ secrets_store = Column(JSON, nullable=True)
diff --git a/enterprise/storage/stored_user_secrets.py b/enterprise/storage/stored_user_secrets.py
new file mode 100644
index 0000000000..7d8f229162
--- /dev/null
+++ b/enterprise/storage/stored_user_secrets.py
@@ -0,0 +1,11 @@
+from sqlalchemy import Column, Identity, Integer, String
+from storage.base import Base
+
+
+class StoredUserSecrets(Base): # type: ignore
+ __tablename__ = 'user_secrets'
+ id = Column(Integer, Identity(), primary_key=True)
+ keycloak_user_id = Column(String, nullable=True, index=True)
+ secret_name = Column(String, nullable=False)
+ secret_value = Column(String, nullable=False)
+ description = Column(String, nullable=True)
diff --git a/enterprise/storage/stripe_customer.py b/enterprise/storage/stripe_customer.py
new file mode 100644
index 0000000000..4ad0d37198
--- /dev/null
+++ b/enterprise/storage/stripe_customer.py
@@ -0,0 +1,25 @@
+from sqlalchemy import Column, DateTime, Integer, String, text
+from storage.base import Base
+
+
+class StripeCustomer(Base): # type: ignore
+ """
+ Represents a stripe customer. We can't simply use the stripe API for this because:
+ "Don’t use search in read-after-write flows where strict consistency is necessary.
+ Under normal operating conditions, data is searchable in less than a minute.
+ Occasionally, propagation of new or updated data can be up to an hour behind during outages"
+ """
+
+ __tablename__ = 'stripe_customers'
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ keycloak_user_id = Column(String, nullable=False)
+ stripe_customer_id = Column(String, nullable=False)
+ created_at = Column(
+ DateTime, server_default=text('CURRENT_TIMESTAMP'), nullable=False
+ )
+ updated_at = Column(
+ DateTime,
+ server_default=text('CURRENT_TIMESTAMP'),
+ onupdate=text('CURRENT_TIMESTAMP'),
+ nullable=False,
+ )
diff --git a/enterprise/storage/subscription_access.py b/enterprise/storage/subscription_access.py
new file mode 100644
index 0000000000..5c102abf63
--- /dev/null
+++ b/enterprise/storage/subscription_access.py
@@ -0,0 +1,43 @@
+from datetime import UTC, datetime
+
+from sqlalchemy import DECIMAL, Column, DateTime, Enum, Integer, String
+from storage.base import Base
+
+
+class SubscriptionAccess(Base): # type: ignore
+ """
+ Represents a user's subscription access record.
+ Tracks subscription status, duration, and payment information.
+ """
+
+ __tablename__ = 'subscription_access'
+
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ status = Column(
+ Enum(
+ 'ACTIVE',
+ 'DISABLED',
+ name='subscription_access_status_enum',
+ ),
+ nullable=False,
+ index=True,
+ )
+ user_id = Column(String, nullable=False, index=True)
+ start_at = Column(DateTime(timezone=True), nullable=True)
+ end_at = Column(DateTime(timezone=True), nullable=True)
+ amount_paid = Column(DECIMAL(19, 4), nullable=True)
+ stripe_invoice_payment_id = Column(String, nullable=False)
+ created_at = Column(
+ DateTime(timezone=True),
+ default=lambda: datetime.now(UTC), # type: ignore[attr-defined]
+ nullable=False,
+ )
+ updated_at = Column(
+ DateTime(timezone=True),
+ default=lambda: datetime.now(UTC), # type: ignore[attr-defined]
+ onupdate=lambda: datetime.now(UTC), # type: ignore[attr-defined]
+ nullable=False,
+ )
+
+ class Config:
+ from_attributes = True
diff --git a/enterprise/storage/subscription_access_status.py b/enterprise/storage/subscription_access_status.py
new file mode 100644
index 0000000000..ddb64160df
--- /dev/null
+++ b/enterprise/storage/subscription_access_status.py
@@ -0,0 +1,6 @@
+from enum import Enum
+
+
+class SubscriptionAccessStatus(Enum):
+ ACTIVE = 'ACTIVE'
+ DISABLED = 'DISABLED'
diff --git a/enterprise/storage/user_repo_map.py b/enterprise/storage/user_repo_map.py
new file mode 100644
index 0000000000..a358f2dbde
--- /dev/null
+++ b/enterprise/storage/user_repo_map.py
@@ -0,0 +1,14 @@
+from sqlalchemy import Boolean, Column, Integer, String
+from storage.base import Base
+
+
+class UserRepositoryMap(Base):
+ """
+ Represents a map between user id and repo ids
+ """
+
+ __tablename__ = 'user-repos'
+ id = Column(Integer, primary_key=True, autoincrement=True)
+ user_id = Column(String, nullable=False)
+ repo_id = Column(String, nullable=False)
+ admin = Column(Boolean, nullable=True)
diff --git a/enterprise/storage/user_repo_map_store.py b/enterprise/storage/user_repo_map_store.py
new file mode 100644
index 0000000000..072f4bd778
--- /dev/null
+++ b/enterprise/storage/user_repo_map_store.py
@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import sqlalchemy
+from sqlalchemy.orm import sessionmaker
+from storage.database import session_maker
+from storage.user_repo_map import UserRepositoryMap
+
+from openhands.core.config.openhands_config import OpenHandsConfig
+
+
+@dataclass
+class UserRepositoryMapStore:
+ session_maker: sessionmaker
+ config: OpenHandsConfig
+
+ def store_user_repo_mappings(self, mappings: list[UserRepositoryMap]) -> None:
+ """
+ Store user-repository mappings in database
+
+ 1. Make sure to store mappings if they don't exist
+ 2. If a mapping already exists (same user_id and repo_id), update the admin field
+
+ This implementation uses batch operations for better performance with large numbers of mappings.
+
+ Args:
+ mappings: List of UserRepositoryMap objects to store
+ """
+ if not mappings:
+ return
+
+ with self.session_maker() as session:
+ # Extract all user_id/repo_id pairs to check
+ mapping_keys = [(m.user_id, m.repo_id) for m in mappings]
+
+ # Get all existing mappings in a single query
+ existing_mappings = {
+ (m.user_id, m.repo_id): m
+ for m in session.query(UserRepositoryMap).filter(
+ sqlalchemy.tuple_(
+ UserRepositoryMap.user_id, UserRepositoryMap.repo_id
+ ).in_(mapping_keys)
+ )
+ }
+
+ # Process all mappings
+ for mapping in mappings:
+ key = (mapping.user_id, mapping.repo_id)
+ if key in existing_mappings:
+ # Update only the admin field for existing mappings
+ existing_mapping = existing_mappings[key]
+ existing_mapping.admin = mapping.admin
+ else:
+ # Add new mapping to the session
+ session.add(mapping)
+
+ # Commit all changes
+ session.commit()
+
+ @classmethod
+ def get_instance(cls, config: OpenHandsConfig) -> UserRepositoryMapStore:
+ """Get an instance of the UserRepositoryMapStore."""
+ return UserRepositoryMapStore(session_maker, config)
diff --git a/enterprise/storage/user_settings.py b/enterprise/storage/user_settings.py
new file mode 100644
index 0000000000..b84f644b71
--- /dev/null
+++ b/enterprise/storage/user_settings.py
@@ -0,0 +1,40 @@
+from server.constants import DEFAULT_BILLING_MARGIN
+from sqlalchemy import JSON, Boolean, Column, DateTime, Float, Identity, Integer, String
+from storage.base import Base
+
+
+class UserSettings(Base): # type: ignore
+ __tablename__ = 'user_settings'
+ id = Column(Integer, Identity(), primary_key=True)
+ keycloak_user_id = Column(String, nullable=True, index=True)
+ language = Column(String, nullable=True)
+ agent = Column(String, nullable=True)
+ max_iterations = Column(Integer, nullable=True)
+ security_analyzer = Column(String, nullable=True)
+ confirmation_mode = Column(Boolean, nullable=True, default=False)
+ llm_model = Column(String, nullable=True)
+ llm_api_key = Column(String, nullable=True)
+ llm_api_key_for_byor = Column(String, nullable=True)
+ llm_base_url = Column(String, nullable=True)
+ remote_runtime_resource_factor = Column(Integer, nullable=True)
+ enable_default_condenser = Column(Boolean, nullable=False, default=True)
+ condenser_max_size = Column(Integer, nullable=True)
+ user_consents_to_analytics = Column(Boolean, nullable=True)
+ billing_margin = Column(Float, nullable=True, default=DEFAULT_BILLING_MARGIN)
+ enable_sound_notifications = Column(Boolean, nullable=True, default=False)
+ enable_proactive_conversation_starters = Column(
+ Boolean, nullable=False, default=True
+ )
+ sandbox_base_container_image = Column(String, nullable=True)
+ sandbox_runtime_container_image = Column(String, nullable=True)
+ user_version = Column(Integer, nullable=False, default=0)
+ accepted_tos = Column(DateTime, nullable=True)
+ mcp_config = Column(JSON, nullable=True)
+ search_api_key = Column(String, nullable=True)
+ sandbox_api_key = Column(String, nullable=True)
+ max_budget_per_task = Column(Float, nullable=True)
+ enable_solvability_analysis = Column(Boolean, nullable=True, default=False)
+ email = Column(String, nullable=True)
+ email_verified = Column(Boolean, nullable=True)
+ git_user_name = Column(String, nullable=True)
+ git_user_email = Column(String, nullable=True)
diff --git a/enterprise/sync/README.md b/enterprise/sync/README.md
new file mode 100644
index 0000000000..f023a36158
--- /dev/null
+++ b/enterprise/sync/README.md
@@ -0,0 +1,52 @@
+# Resend Sync Service
+
+This service syncs users from Keycloak to a Resend.com audience. It runs as a Kubernetes CronJob that periodically queries the Keycloak database and adds any new users to the specified Resend audience.
+
+## Features
+
+- Syncs users from Keycloak to Resend.com audience
+- Handles rate limiting and retries with exponential backoff
+- Runs as a Kubernetes CronJob
+- Configurable batch size and sync frequency
+
+## Configuration
+
+The service is configured using environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `RESEND_API_KEY` | Resend API key | (required) |
+| `RESEND_AUDIENCE_ID` | Resend audience ID | (required) |
+| `KEYCLOAK_REALM` | Keycloak realm | `all-hands` |
+| `BATCH_SIZE` | Number of users to process in each batch | `100` |
+| `MAX_RETRIES` | Maximum number of retries for API calls | `3` |
+| `INITIAL_BACKOFF_SECONDS` | Initial backoff time for retries | `1` |
+| `MAX_BACKOFF_SECONDS` | Maximum backoff time for retries | `60` |
+| `BACKOFF_FACTOR` | Backoff factor for retries | `2` |
+| `RATE_LIMIT` | Rate limit for API calls (requests per second) | `2` |
+
+## Deployment
+
+The service is deployed as part of the openhands Helm chart. To enable it, set the following in your values.yaml:
+
+```yaml
+resendSync:
+ enabled: true
+ audienceId: "your-audience-id"
+```
+
+### Prerequisites
+
+- Kubernetes cluster with the openhands chart deployed
+- Resend.com API key stored in a Kubernetes secret named `resend-api-key`
+- Resend.com audience ID
+
+## Running Manually
+
+You can run the sync job manually by executing:
+
+```bash
+python -m app.sync.resend
+```
+
+Make sure all required environment variables are set before running the script.
diff --git a/enterprise/sync/__init__.py b/enterprise/sync/__init__.py
new file mode 100644
index 0000000000..d04934e1d2
--- /dev/null
+++ b/enterprise/sync/__init__.py
@@ -0,0 +1 @@
+# Sync package for OpenHands
diff --git a/enterprise/sync/clean_proactive_convo_table.py b/enterprise/sync/clean_proactive_convo_table.py
new file mode 100644
index 0000000000..f2bdf8c0ca
--- /dev/null
+++ b/enterprise/sync/clean_proactive_convo_table.py
@@ -0,0 +1,14 @@
+import asyncio
+
+from storage.proactive_conversation_store import ProactiveConversationStore
+
+OLDER_THAN = 30 # 30 minutes
+
+
+async def main():
+ convo_store = ProactiveConversationStore()
+ await convo_store.clean_old_convos(older_than_minutes=OLDER_THAN)
+
+
+if __name__ == '__main__':
+ asyncio.run(main())
diff --git a/enterprise/sync/common_room_sync.py b/enterprise/sync/common_room_sync.py
new file mode 100755
index 0000000000..e07fb9561d
--- /dev/null
+++ b/enterprise/sync/common_room_sync.py
@@ -0,0 +1,562 @@
+#!/usr/bin/env python3
+"""
+Common Room Sync
+
+This script queries the database to count conversations created by each user,
+then creates or updates a signal in Common Room for each user with their
+conversation count.
+"""
+
+import asyncio
+import logging
+import os
+import sys
+import time
+from datetime import UTC, datetime
+from typing import Any, Dict, List, Optional, Set
+
+import requests
+from sqlalchemy import text
+
+# Add the parent directory to the path so we can import from storage
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from server.auth.token_manager import get_keycloak_admin
+from storage.database import engine
+
+# Configure logging
+logging.basicConfig(
+ level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger('common_room_sync')
+
+# Common Room API configuration
+COMMON_ROOM_API_KEY = os.environ.get('COMMON_ROOM_API_KEY')
+COMMON_ROOM_DESTINATION_SOURCE_ID = os.environ.get('COMMON_ROOM_DESTINATION_SOURCE_ID')
+COMMON_ROOM_API_BASE_URL = 'https://api.commonroom.io/community/v1'
+
+# Sync configuration
+BATCH_SIZE = int(os.environ.get('BATCH_SIZE', '100'))
+KEYCLOAK_BATCH_SIZE = int(os.environ.get('KEYCLOAK_BATCH_SIZE', '20'))
+MAX_RETRIES = int(os.environ.get('MAX_RETRIES', '3'))
+INITIAL_BACKOFF_SECONDS = float(os.environ.get('INITIAL_BACKOFF_SECONDS', '1'))
+MAX_BACKOFF_SECONDS = float(os.environ.get('MAX_BACKOFF_SECONDS', '60'))
+BACKOFF_FACTOR = float(os.environ.get('BACKOFF_FACTOR', '2'))
+RATE_LIMIT = float(os.environ.get('RATE_LIMIT', '2')) # Requests per second
+
+
+class CommonRoomSyncError(Exception):
+ """Base exception for Common Room sync errors."""
+
+
+class DatabaseError(CommonRoomSyncError):
+ """Exception for database errors."""
+
+
+class CommonRoomAPIError(CommonRoomSyncError):
+ """Exception for Common Room API errors."""
+
+
+class KeycloakClientError(CommonRoomSyncError):
+ """Exception for Keycloak client errors."""
+
+
+def get_recent_conversations(minutes: int = 60) -> List[Dict[str, Any]]:
+ """Get conversations created in the past N minutes.
+
+ Args:
+ minutes: Number of minutes to look back for new conversations.
+
+ Returns:
+ A list of dictionaries, each containing conversation details.
+
+ Raises:
+ DatabaseError: If the database query fails.
+ """
+ try:
+ # Use a different syntax for the interval that works with pg8000
+ query = text("""
+ SELECT
+ conversation_id, user_id, title, created_at
+ FROM
+ conversation_metadata
+ WHERE
+ created_at >= NOW() - (INTERVAL '1 minute' * :minutes)
+ ORDER BY
+ created_at DESC
+ """)
+
+ with engine.connect() as connection:
+ result = connection.execute(query, {'minutes': minutes})
+ conversations = [
+ {
+ 'conversation_id': row[0],
+ 'user_id': row[1],
+ 'title': row[2],
+ 'created_at': row[3].isoformat() if row[3] else None,
+ }
+ for row in result
+ ]
+
+ logger.info(
+ f'Retrieved {len(conversations)} conversations created in the past {minutes} minutes'
+ )
+ return conversations
+ except Exception as e:
+ logger.exception(f'Error querying recent conversations: {e}')
+ raise DatabaseError(f'Failed to query recent conversations: {e}')
+
+
+async def get_users_from_keycloak(user_ids: Set[str]) -> Dict[str, Dict[str, Any]]:
+ """Get user information from Keycloak for a set of user IDs.
+
+ Args:
+ user_ids: A set of user IDs to look up.
+
+ Returns:
+ A dictionary mapping user IDs to user information dictionaries.
+
+ Raises:
+ KeycloakClientError: If the Keycloak API call fails.
+ """
+ try:
+ # Get Keycloak admin client
+ keycloak_admin = get_keycloak_admin()
+
+ # Create a dictionary to store user information
+ user_info_dict = {}
+
+ # Convert set to list for easier batching
+ user_id_list = list(user_ids)
+
+ # Process user IDs in batches
+ for i in range(0, len(user_id_list), KEYCLOAK_BATCH_SIZE):
+ batch = user_id_list[i : i + KEYCLOAK_BATCH_SIZE]
+ batch_tasks = []
+
+ # Create tasks for each user ID in the batch
+ for user_id in batch:
+ # Use the Keycloak admin client to get user by ID
+ batch_tasks.append(get_user_by_id(keycloak_admin, user_id))
+
+ # Run the batch of tasks concurrently
+ batch_results = await asyncio.gather(*batch_tasks, return_exceptions=True)
+
+ # Process the results
+ for user_id, result in zip(batch, batch_results):
+ if isinstance(result, Exception):
+ logger.warning(f'Error getting user {user_id}: {result}')
+ continue
+
+ if result and isinstance(result, dict):
+ user_info_dict[user_id] = {
+ 'username': result.get('username'),
+ 'email': result.get('email'),
+ 'id': result.get('id'),
+ }
+
+ logger.info(
+ f'Retrieved information for {len(user_info_dict)} users from Keycloak'
+ )
+ return user_info_dict
+
+ except Exception as e:
+ error_msg = f'Error getting users from Keycloak: {e}'
+ logger.exception(error_msg)
+ raise KeycloakClientError(error_msg)
+
+
+async def get_user_by_id(keycloak_admin, user_id: str) -> Optional[Dict[str, Any]]:
+ """Get a user from Keycloak by ID.
+
+ Args:
+ keycloak_admin: The Keycloak admin client.
+ user_id: The user ID to look up.
+
+ Returns:
+ A dictionary with the user's information, or None if not found.
+ """
+ try:
+ # Use the Keycloak admin client to get user by ID
+ user = keycloak_admin.get_user(user_id)
+ if user:
+ logger.debug(
+ f"Found user in Keycloak: {user.get('username')}, {user.get('email')}"
+ )
+ return user
+ else:
+ logger.warning(f'User {user_id} not found in Keycloak')
+ return None
+ except Exception as e:
+ logger.warning(f'Error getting user {user_id} from Keycloak: {e}')
+ return None
+
+
+def get_user_info(
+ user_id: str, user_info_cache: Dict[str, Dict[str, Any]]
+) -> Optional[Dict[str, str]]:
+ """Get the email address and GitHub username for a user from the cache.
+
+ Args:
+ user_id: The user ID to look up.
+ user_info_cache: A dictionary mapping user IDs to user information.
+
+ Returns:
+ A dictionary with the user's email and username, or None if not found.
+ """
+ # Check if the user is in the cache
+ if user_id in user_info_cache:
+ user_info = user_info_cache[user_id]
+ logger.debug(
+ f"Found user info in cache: {user_info.get('username')}, {user_info.get('email')}"
+ )
+ return user_info
+ else:
+ logger.warning(f'User {user_id} not found in user info cache')
+ return None
+
+
+def register_user_in_common_room(
+ user_id: str, email: str, github_username: str
+) -> Dict[str, Any]:
+ """Create or update a user in Common Room.
+
+ Args:
+ user_id: The user ID.
+ email: The user's email address.
+ github_username: The user's GitHub username.
+
+ Returns:
+ The API response from Common Room.
+
+ Raises:
+ CommonRoomAPIError: If the Common Room API request fails.
+ """
+ if not COMMON_ROOM_API_KEY:
+ raise CommonRoomAPIError('COMMON_ROOM_API_KEY environment variable not set')
+
+ if not COMMON_ROOM_DESTINATION_SOURCE_ID:
+ raise CommonRoomAPIError(
+ 'COMMON_ROOM_DESTINATION_SOURCE_ID environment variable not set'
+ )
+
+ try:
+ headers = {
+ 'Authorization': f'Bearer {COMMON_ROOM_API_KEY}',
+ 'Content-Type': 'application/json',
+ }
+
+ # Create or update user in Common Room
+ user_data = {
+ 'id': user_id,
+ 'email': email,
+ 'username': github_username,
+ 'github': {'type': 'handle', 'value': github_username},
+ }
+
+ user_url = f'{COMMON_ROOM_API_BASE_URL}/source/{COMMON_ROOM_DESTINATION_SOURCE_ID}/user'
+ user_response = requests.post(user_url, headers=headers, json=user_data)
+
+ if user_response.status_code not in (200, 202):
+ logger.error(
+ f'Failed to create/update user in Common Room: {user_response.text}'
+ )
+ logger.error(f'Response status code: {user_response.status_code}')
+ raise CommonRoomAPIError(
+ f'Failed to create/update user: {user_response.text}'
+ )
+
+ logger.info(
+ f'Registered/updated user {user_id} (GitHub: {github_username}) in Common Room'
+ )
+ return user_response.json()
+ except requests.RequestException as e:
+ logger.exception(f'Error communicating with Common Room API: {e}')
+ raise CommonRoomAPIError(f'Failed to communicate with Common Room API: {e}')
+
+
+def register_conversation_activity(
+ user_id: str,
+ conversation_id: str,
+ conversation_title: str,
+ created_at: datetime,
+ email: str,
+ github_username: str,
+) -> Dict[str, Any]:
+ """Create an activity in Common Room for a new conversation.
+
+ Args:
+ user_id: The user ID who created the conversation.
+ conversation_id: The ID of the conversation.
+ conversation_title: The title of the conversation.
+ created_at: The datetime object when the conversation was created.
+ email: The user's email address.
+ github_username: The user's GitHub username.
+
+ Returns:
+ The API response from Common Room.
+
+ Raises:
+ CommonRoomAPIError: If the Common Room API request fails.
+ """
+ if not COMMON_ROOM_API_KEY:
+ raise CommonRoomAPIError('COMMON_ROOM_API_KEY environment variable not set')
+
+ if not COMMON_ROOM_DESTINATION_SOURCE_ID:
+ raise CommonRoomAPIError(
+ 'COMMON_ROOM_DESTINATION_SOURCE_ID environment variable not set'
+ )
+
+ try:
+ headers = {
+ 'Authorization': f'Bearer {COMMON_ROOM_API_KEY}',
+ 'Content-Type': 'application/json',
+ }
+
+ # Format the datetime object to the expected ISO format
+ formatted_timestamp = (
+ created_at.strftime('%Y-%m-%dT%H:%M:%SZ')
+ if created_at
+ else time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime())
+ )
+
+ # Create activity for the conversation
+ activity_data = {
+ 'id': f'conversation_{conversation_id}', # Use conversation ID to ensure uniqueness
+ 'activityType': 'started_session',
+ 'user': {
+ 'id': user_id,
+ 'email': email,
+ 'github': {'type': 'handle', 'value': github_username},
+ 'username': github_username,
+ },
+ 'activityTitle': {
+ 'type': 'text',
+ 'value': conversation_title or 'New Conversation',
+ },
+ 'content': {
+ 'type': 'text',
+ 'value': f'Started a new conversation: {conversation_title or "Untitled"}',
+ },
+ 'timestamp': formatted_timestamp,
+ 'url': f'https://app.all-hands.dev/conversations/{conversation_id}',
+ }
+
+ # Log the activity data for debugging
+ logger.info(f'Activity data payload: {activity_data}')
+
+ activity_url = f'{COMMON_ROOM_API_BASE_URL}/source/{COMMON_ROOM_DESTINATION_SOURCE_ID}/activity'
+ activity_response = requests.post(
+ activity_url, headers=headers, json=activity_data
+ )
+
+ if activity_response.status_code not in (200, 202):
+ logger.error(
+ f'Failed to create activity in Common Room: {activity_response.text}'
+ )
+ logger.error(f'Response status code: {activity_response.status_code}')
+ raise CommonRoomAPIError(
+ f'Failed to create activity: {activity_response.text}'
+ )
+
+ logger.info(
+ f'Registered conversation activity for user {user_id}, conversation {conversation_id}'
+ )
+ return activity_response.json()
+ except requests.RequestException as e:
+ logger.exception(f'Error communicating with Common Room API: {e}')
+ raise CommonRoomAPIError(f'Failed to communicate with Common Room API: {e}')
+
+
+def retry_with_backoff(func, *args, **kwargs):
+ """Retry a function with exponential backoff.
+
+ Args:
+ func: The function to retry.
+ *args: Positional arguments to pass to the function.
+ **kwargs: Keyword arguments to pass to the function.
+
+ Returns:
+ The result of the function call.
+
+ Raises:
+ The last exception raised by the function.
+ """
+ backoff = INITIAL_BACKOFF_SECONDS
+ last_exception = None
+
+ for attempt in range(MAX_RETRIES):
+ try:
+ return func(*args, **kwargs)
+ except Exception as e:
+ last_exception = e
+ logger.warning(f'Attempt {attempt + 1}/{MAX_RETRIES} failed: {e}')
+
+ if attempt < MAX_RETRIES - 1:
+ sleep_time = min(backoff, MAX_BACKOFF_SECONDS)
+ logger.info(f'Retrying in {sleep_time:.2f} seconds...')
+ time.sleep(sleep_time)
+ backoff *= BACKOFF_FACTOR
+ else:
+ logger.exception(f'All {MAX_RETRIES} attempts failed')
+ raise last_exception
+
+
+async def retry_with_backoff_async(func, *args, **kwargs):
+ """Retry an async function with exponential backoff.
+
+ Args:
+ func: The async function to retry.
+ *args: Positional arguments to pass to the function.
+ **kwargs: Keyword arguments to pass to the function.
+
+ Returns:
+ The result of the function call.
+
+ Raises:
+ The last exception raised by the function.
+ """
+ backoff = INITIAL_BACKOFF_SECONDS
+ last_exception = None
+
+ for attempt in range(MAX_RETRIES):
+ try:
+ return await func(*args, **kwargs)
+ except Exception as e:
+ last_exception = e
+ logger.warning(f'Attempt {attempt + 1}/{MAX_RETRIES} failed: {e}')
+
+ if attempt < MAX_RETRIES - 1:
+ sleep_time = min(backoff, MAX_BACKOFF_SECONDS)
+ logger.info(f'Retrying in {sleep_time:.2f} seconds...')
+ await asyncio.sleep(sleep_time)
+ backoff *= BACKOFF_FACTOR
+ else:
+ logger.exception(f'All {MAX_RETRIES} attempts failed')
+ raise last_exception
+
+
+async def async_sync_recent_conversations_to_common_room(minutes: int = 60):
+ """Async main function to sync recent conversations to Common Room.
+
+ Args:
+ minutes: Number of minutes to look back for new conversations.
+ """
+ logger.info(
+ f'Starting Common Room recent conversations sync (past {minutes} minutes)'
+ )
+
+ stats = {
+ 'total_conversations': 0,
+ 'registered_users': 0,
+ 'registered_activities': 0,
+ 'errors': 0,
+ 'missing_user_info': 0,
+ }
+
+ try:
+ # Get conversations created in the past N minutes
+ recent_conversations = retry_with_backoff(get_recent_conversations, minutes)
+ stats['total_conversations'] = len(recent_conversations)
+
+ logger.info(f'Processing {len(recent_conversations)} recent conversations')
+
+ if not recent_conversations:
+ logger.info('No recent conversations found, exiting')
+ return
+
+ # Extract all unique user IDs
+ user_ids = {conv['user_id'] for conv in recent_conversations if conv['user_id']}
+
+ # Get user information for all users in batches
+ user_info_cache = await retry_with_backoff_async(
+ get_users_from_keycloak, user_ids
+ )
+
+ # Track registered users to avoid duplicate registrations
+ registered_users = set()
+
+ # Process each conversation
+ for conversation in recent_conversations:
+ conversation_id = conversation['conversation_id']
+ user_id = conversation['user_id']
+ title = conversation['title']
+ created_at = conversation[
+ 'created_at'
+ ] # This might be a string or datetime object
+
+ try:
+ # Get user info from cache
+ user_info = get_user_info(user_id, user_info_cache)
+ if not user_info:
+ logger.warning(
+ f'Could not find user info for user {user_id}, skipping conversation {conversation_id}'
+ )
+ stats['missing_user_info'] += 1
+ continue
+
+ email = user_info['email']
+ github_username = user_info['username']
+
+ if not email:
+ logger.warning(
+ f'User {user_id} has no email, skipping conversation {conversation_id}'
+ )
+ stats['errors'] += 1
+ continue
+
+ # Register user in Common Room if not already registered in this run
+ if user_id not in registered_users:
+ register_user_in_common_room(user_id, email, github_username)
+ registered_users.add(user_id)
+ stats['registered_users'] += 1
+
+ # If created_at is a string, parse it to a datetime object
+ # If it's already a datetime object, use it as is
+ # If it's None, use current time
+ created_at_datetime = (
+ created_at
+ if isinstance(created_at, datetime)
+ else datetime.fromisoformat(created_at.replace('Z', '+00:00'))
+ if created_at
+ else datetime.now(UTC)
+ )
+
+ # Register conversation activity with email and github username
+ register_conversation_activity(
+ user_id,
+ conversation_id,
+ title,
+ created_at_datetime,
+ email,
+ github_username,
+ )
+ stats['registered_activities'] += 1
+
+ # Sleep to respect rate limit
+ await asyncio.sleep(1 / RATE_LIMIT)
+ except Exception as e:
+ logger.exception(
+ f'Error processing conversation {conversation_id} for user {user_id}: {e}'
+ )
+ stats['errors'] += 1
+ except Exception as e:
+ logger.exception(f'Sync failed: {e}')
+ raise
+ finally:
+ logger.info(f'Sync completed. Stats: {stats}')
+
+
+def sync_recent_conversations_to_common_room(minutes: int = 60):
+ """Main function to sync recent conversations to Common Room.
+
+ Args:
+ minutes: Number of minutes to look back for new conversations.
+ """
+ # Run the async function in the event loop
+ asyncio.run(async_sync_recent_conversations_to_common_room(minutes))
+
+
+if __name__ == '__main__':
+ # Default to looking back 60 minutes for new conversations
+ minutes = int(os.environ.get('SYNC_MINUTES', '60'))
+ sync_recent_conversations_to_common_room(minutes)
diff --git a/enterprise/sync/enrich_user_interaction_data.py b/enterprise/sync/enrich_user_interaction_data.py
new file mode 100644
index 0000000000..184c1c40cc
--- /dev/null
+++ b/enterprise/sync/enrich_user_interaction_data.py
@@ -0,0 +1,67 @@
+import asyncio
+
+from integrations.github.data_collector import GitHubDataCollector
+from storage.openhands_pr import OpenhandsPR
+from storage.openhands_pr_store import OpenhandsPRStore
+
+from openhands.core.logger import openhands_logger as logger
+
+PROCESS_AMOUNT = 50
+MAX_RETRIES = 3
+
+store = OpenhandsPRStore.get_instance()
+data_collector = GitHubDataCollector()
+
+
+def get_unprocessed_prs() -> list[OpenhandsPR]:
+ """
+ Get unprocessed PR entries from the OpenhandsPR table.
+
+ Args:
+ limit: Maximum number of PRs to retrieve (default: 50)
+
+ Returns:
+ List of OpenhandsPR objects that need processing
+ """
+ unprocessed_prs = store.get_unprocessed_prs(PROCESS_AMOUNT, MAX_RETRIES)
+ logger.info(f'Retrieved {len(unprocessed_prs)} unprocessed PRs for enrichment')
+ return unprocessed_prs
+
+
+async def process_pr(pr: OpenhandsPR):
+ """
+ Process a single PR to enrich its data.
+ """
+
+ logger.info(f'Processing PR #{pr.pr_number} from repo {pr.repo_name}')
+ await data_collector.save_full_pr(pr)
+ store.increment_process_attempts(pr.repo_id, pr.pr_number)
+
+
+async def main():
+ """
+ Main function to retrieve and process unprocessed PRs.
+ """
+ logger.info('Starting PR data enrichment process')
+
+ # Get unprocessed PRs
+ unprocessed_prs = get_unprocessed_prs()
+ logger.info(f'Found {len(unprocessed_prs)} PRs to process')
+
+ # Process each PR
+ for pr in unprocessed_prs:
+ try:
+ await process_pr(pr)
+ logger.info(
+ f'Successfully processed PR #{pr.pr_number} from repo {pr.repo_name}'
+ )
+ except Exception as e:
+ logger.exception(
+ f'Error processing PR #{pr.pr_number} from repo {pr.repo_name}: {str(e)}'
+ )
+
+ logger.info('PR data enrichment process completed')
+
+
+if __name__ == '__main__':
+ asyncio.run(main())
diff --git a/enterprise/sync/install_gitlab_webhooks.py b/enterprise/sync/install_gitlab_webhooks.py
new file mode 100644
index 0000000000..e8e3ead613
--- /dev/null
+++ b/enterprise/sync/install_gitlab_webhooks.py
@@ -0,0 +1,324 @@
+import asyncio
+from typing import cast
+from uuid import uuid4
+
+from integrations.types import GitLabResourceType
+from integrations.utils import GITLAB_WEBHOOK_URL
+from storage.gitlab_webhook import GitlabWebhook, WebhookStatus
+from storage.gitlab_webhook_store import GitlabWebhookStore
+
+from openhands.core.logger import openhands_logger as logger
+from openhands.integrations.gitlab.gitlab_service import GitLabServiceImpl
+from openhands.integrations.service_types import GitService
+
+CHUNK_SIZE = 100
+WEBHOOK_NAME = 'OpenHands Resolver'
+SCOPES: list[str] = [
+ 'note_events',
+ 'merge_requests_events',
+ 'confidential_issues_events',
+ 'issues_events',
+ 'confidential_note_events',
+ 'job_events',
+ 'pipeline_events',
+]
+
+
+class BreakLoopException(Exception):
+ pass
+
+
+class VerifyWebhookStatus:
+ async def fetch_rows(self, webhook_store: GitlabWebhookStore):
+ webhooks = await webhook_store.filter_rows(limit=CHUNK_SIZE)
+
+ return webhooks
+
+ def determine_if_rate_limited(
+ self,
+ status: WebhookStatus | None,
+ ) -> None:
+ if status == WebhookStatus.RATE_LIMITED:
+ raise BreakLoopException()
+
+ async def check_if_resource_exists(
+ self,
+ gitlab_service: type[GitService],
+ resource_type: GitLabResourceType,
+ resource_id: str,
+ webhook_store: GitlabWebhookStore,
+ webhook: GitlabWebhook,
+ ):
+ """
+ Check if the GitLab resource still exists
+ """
+ from integrations.gitlab.gitlab_service import SaaSGitLabService
+
+ gitlab_service = cast(type[SaaSGitLabService], gitlab_service)
+
+ does_resource_exist, status = await gitlab_service.check_resource_exists(
+ resource_type, resource_id
+ )
+
+ logger.info(
+ 'Does resource exists',
+ extra={
+ 'does_resource_exist': does_resource_exist,
+ 'status': status,
+ 'resource_id': resource_id,
+ 'resource_type': resource_type,
+ },
+ )
+
+ self.determine_if_rate_limited(status)
+ if not does_resource_exist and status != WebhookStatus.RATE_LIMITED:
+ await webhook_store.delete_webhook(webhook)
+ raise BreakLoopException()
+
+ async def check_if_user_has_admin_acccess_to_resource(
+ self,
+ gitlab_service: type[GitService],
+ resource_type: GitLabResourceType,
+ resource_id: str,
+ webhook_store: GitlabWebhookStore,
+ webhook: GitlabWebhook,
+ ):
+ """
+ Check is user still has permission to resource
+ """
+ from integrations.gitlab.gitlab_service import SaaSGitLabService
+
+ gitlab_service = cast(type[SaaSGitLabService], gitlab_service)
+
+ (
+ is_user_admin_of_resource,
+ status,
+ ) = await gitlab_service.check_user_has_admin_access_to_resource(
+ resource_type, resource_id
+ )
+
+ logger.info(
+ 'Is user admin',
+ extra={
+ 'is_user_admin': is_user_admin_of_resource,
+ 'status': status,
+ 'resource_id': resource_id,
+ 'resource_type': resource_type,
+ },
+ )
+
+ self.determine_if_rate_limited(status)
+ if not is_user_admin_of_resource:
+ await webhook_store.delete_webhook(webhook)
+ raise BreakLoopException()
+
+ async def check_if_webhook_already_exists_on_resource(
+ self,
+ gitlab_service: type[GitService],
+ resource_type: GitLabResourceType,
+ resource_id: str,
+ webhook_store: GitlabWebhookStore,
+ webhook: GitlabWebhook,
+ ):
+ """
+ Check whether webhook already exists on resource
+ """
+ from integrations.gitlab.gitlab_service import SaaSGitLabService
+
+ gitlab_service = cast(type[SaaSGitLabService], gitlab_service)
+ (
+ does_webhook_exist_on_resource,
+ status,
+ ) = await gitlab_service.check_webhook_exists_on_resource(
+ resource_type, resource_id, GITLAB_WEBHOOK_URL
+ )
+
+ logger.info(
+ 'Does webhook already exist',
+ extra={
+ 'does_webhook_exist_on_resource': does_webhook_exist_on_resource,
+ 'status': status,
+ 'resource_id': resource_id,
+ 'resource_type': resource_type,
+ },
+ )
+
+ self.determine_if_rate_limited(status)
+ if does_webhook_exist_on_resource != webhook.webhook_exists:
+ await webhook_store.update_webhook(
+ webhook, {'webhook_exists': does_webhook_exist_on_resource}
+ )
+
+ if does_webhook_exist_on_resource:
+ raise BreakLoopException()
+
+ async def verify_conditions_are_met(
+ self,
+ gitlab_service: type[GitService],
+ resource_type: GitLabResourceType,
+ resource_id: str,
+ webhook_store: GitlabWebhookStore,
+ webhook: GitlabWebhook,
+ ):
+ await self.check_if_resource_exists(
+ gitlab_service=gitlab_service,
+ resource_type=resource_type,
+ resource_id=resource_id,
+ webhook_store=webhook_store,
+ webhook=webhook,
+ )
+
+ await self.check_if_user_has_admin_acccess_to_resource(
+ gitlab_service=gitlab_service,
+ resource_type=resource_type,
+ resource_id=resource_id,
+ webhook_store=webhook_store,
+ webhook=webhook,
+ )
+
+ await self.check_if_webhook_already_exists_on_resource(
+ gitlab_service=gitlab_service,
+ resource_type=resource_type,
+ resource_id=resource_id,
+ webhook_store=webhook_store,
+ webhook=webhook,
+ )
+
+ async def create_new_webhook(
+ self,
+ gitlab_service: type[GitService],
+ resource_type: GitLabResourceType,
+ resource_id: str,
+ webhook_store: GitlabWebhookStore,
+ webhook: GitlabWebhook,
+ ):
+ """
+ Install webhook on resource
+ """
+ from integrations.gitlab.gitlab_service import SaaSGitLabService
+
+ gitlab_service = cast(type[SaaSGitLabService], gitlab_service)
+
+ webhook_secret = f'{webhook.user_id}-{str(uuid4())}'
+ webhook_uuid = f'{str(uuid4())}'
+
+ webhook_id, status = await gitlab_service.install_webhook(
+ resource_type=resource_type,
+ resource_id=resource_id,
+ webhook_name=WEBHOOK_NAME,
+ webhook_url=GITLAB_WEBHOOK_URL,
+ webhook_secret=webhook_secret,
+ webhook_uuid=webhook_uuid,
+ scopes=SCOPES,
+ )
+
+ logger.info(
+ 'Creating new webhook',
+ extra={
+ 'webhook_id': webhook_id,
+ 'status': status,
+ 'resource_id': resource_id,
+ 'resource_type': resource_type,
+ },
+ )
+
+ self.determine_if_rate_limited(status)
+
+ if webhook_id:
+ await webhook_store.update_webhook(
+ webhook=webhook,
+ update_fields={
+ 'webhook_secret': webhook_secret,
+ 'webhook_exists': True, # webhook was created
+ 'webhook_url': GITLAB_WEBHOOK_URL,
+ 'scopes': SCOPES,
+ 'webhook_uuid': webhook_uuid, # required to identify which webhook installation is sending payload
+ },
+ )
+
+ logger.info(
+ f'Installed webhook for {webhook.user_id} on {resource_type}:{resource_id}'
+ )
+
+ async def install_webhooks(self):
+ """
+ Periodically check the conditions for installing a webhook on resource as valid
+ Rows with valid conditions with contain (webhook_exists=False, status=WebhookStatus.VERIFIED)
+
+ Conditions we check for
+ 1. Resoure exists
+ - user could have deleted resource
+ 2. User has admin access to resource
+ - user's permissions to install webhook could have changed
+ 3. Webhook exists
+ - user could have removed webhook from resource
+ - resource was never setup with webhook
+
+ """
+
+ from integrations.gitlab.gitlab_service import SaaSGitLabService
+
+ # Get an instance of the webhook store
+ webhook_store = await GitlabWebhookStore.get_instance()
+
+ # Load chunks of rows that need processing (webhook_exists == False)
+ webhooks_to_process = await self.fetch_rows(webhook_store)
+
+ logger.info(
+ 'Processing webhook chunks',
+ extra={'webhooks_to_process': webhooks_to_process},
+ )
+
+ for webhook in webhooks_to_process:
+ try:
+ user_id = webhook.user_id
+ resource_type, resource_id = GitlabWebhookStore.determine_resource_type(
+ webhook
+ )
+
+ gitlab_service = GitLabServiceImpl(external_auth_id=user_id)
+
+ if not isinstance(gitlab_service, SaaSGitLabService):
+ raise Exception('Only SaaSGitLabService is supported')
+ # Cast needed when mypy can see OpenHands
+ gitlab_service = cast(type[SaaSGitLabService], gitlab_service)
+
+ await self.verify_conditions_are_met(
+ gitlab_service=gitlab_service,
+ resource_type=resource_type,
+ resource_id=resource_id,
+ webhook_store=webhook_store,
+ webhook=webhook,
+ )
+
+ # Conditions have been met for installing webhook
+ await self.create_new_webhook(
+ gitlab_service=gitlab_service,
+ resource_type=resource_type,
+ resource_id=resource_id,
+ webhook_store=webhook_store,
+ webhook=webhook,
+ )
+
+ except BreakLoopException:
+ pass # Continue processing but still update last_synced
+ finally:
+ # Always update last_synced after processing (success or failure)
+ # to prevent immediate reprocessing of the same webhook
+ try:
+ await webhook_store.update_last_synced(webhook)
+ except Exception as e:
+ logger.warning(
+ 'Failed to update last_synced for webhook',
+ extra={
+ 'webhook_id': getattr(webhook, 'id', None),
+ 'project_id': getattr(webhook, 'project_id', None),
+ 'group_id': getattr(webhook, 'group_id', None),
+ 'error': str(e),
+ },
+ )
+
+
+if __name__ == '__main__':
+ status_verifier = VerifyWebhookStatus()
+ asyncio.run(status_verifier.install_webhooks())
diff --git a/enterprise/sync/resend_keycloak.py b/enterprise/sync/resend_keycloak.py
new file mode 100644
index 0000000000..17ab72bbd5
--- /dev/null
+++ b/enterprise/sync/resend_keycloak.py
@@ -0,0 +1,403 @@
+#!/usr/bin/env python3
+"""Sync script to add Keycloak users to Resend.com audience.
+
+This script uses the Keycloak admin client to fetch users and adds them to a
+Resend.com audience. It handles rate limiting and retries with exponential
+backoff for adding contacts. When a user is newly added to the mailing list, a welcome email is sent.
+
+Required environment variables:
+- KEYCLOAK_SERVER_URL: URL of the Keycloak server
+- KEYCLOAK_REALM_NAME: Keycloak realm name
+- KEYCLOAK_ADMIN_PASSWORD: Password for the Keycloak admin user
+- RESEND_API_KEY: API key for Resend.com
+- RESEND_AUDIENCE_ID: ID of the Resend audience to add users to
+
+Optional environment variables:
+- KEYCLOAK_PROVIDER_NAME: Provider name for Keycloak
+- KEYCLOAK_CLIENT_ID: Client ID for Keycloak
+- KEYCLOAK_CLIENT_SECRET: Client secret for Keycloak
+- RESEND_FROM_EMAIL: Email address to use as the sender (default: "All Hands Team ")
+- BATCH_SIZE: Number of users to process in each batch (default: 100)
+- MAX_RETRIES: Maximum number of retries for API calls (default: 3)
+- INITIAL_BACKOFF_SECONDS: Initial backoff time for retries (default: 1)
+- MAX_BACKOFF_SECONDS: Maximum backoff time for retries (default: 60)
+- BACKOFF_FACTOR: Backoff factor for retries (default: 2)
+- RATE_LIMIT: Rate limit for API calls (requests per second) (default: 2)
+"""
+
+import os
+import sys
+import time
+from typing import Any, Dict, List, Optional
+
+import resend
+from keycloak.exceptions import KeycloakError
+from resend.exceptions import ResendError
+from server.auth.token_manager import get_keycloak_admin
+from tenacity import (
+ retry,
+ retry_if_exception_type,
+ stop_after_attempt,
+ wait_exponential,
+)
+
+from openhands.core.logger import openhands_logger as logger
+
+# Get Keycloak configuration from environment variables
+KEYCLOAK_SERVER_URL = os.environ.get('KEYCLOAK_SERVER_URL', '')
+KEYCLOAK_REALM_NAME = os.environ.get('KEYCLOAK_REALM_NAME', '')
+KEYCLOAK_PROVIDER_NAME = os.environ.get('KEYCLOAK_PROVIDER_NAME', '')
+KEYCLOAK_CLIENT_ID = os.environ.get('KEYCLOAK_CLIENT_ID', '')
+KEYCLOAK_CLIENT_SECRET = os.environ.get('KEYCLOAK_CLIENT_SECRET', '')
+KEYCLOAK_ADMIN_PASSWORD = os.environ.get('KEYCLOAK_ADMIN_PASSWORD', '')
+
+# Logger is imported from openhands.core.logger
+
+# Get configuration from environment variables
+RESEND_API_KEY = os.environ.get('RESEND_API_KEY')
+RESEND_AUDIENCE_ID = os.environ.get('RESEND_AUDIENCE_ID', '')
+
+# Sync configuration
+BATCH_SIZE = int(os.environ.get('BATCH_SIZE', '100'))
+MAX_RETRIES = int(os.environ.get('MAX_RETRIES', '3'))
+INITIAL_BACKOFF_SECONDS = float(os.environ.get('INITIAL_BACKOFF_SECONDS', '1'))
+MAX_BACKOFF_SECONDS = float(os.environ.get('MAX_BACKOFF_SECONDS', '60'))
+BACKOFF_FACTOR = float(os.environ.get('BACKOFF_FACTOR', '2'))
+RATE_LIMIT = float(os.environ.get('RATE_LIMIT', '2')) # Requests per second
+
+# Set up Resend API
+resend.api_key = RESEND_API_KEY
+
+print('resend module', resend)
+print('has contacts', hasattr(resend, 'Contacts'))
+
+
+class ResendSyncError(Exception):
+ """Base exception for Resend sync errors."""
+
+ pass
+
+
+class KeycloakClientError(ResendSyncError):
+ """Exception for Keycloak client errors."""
+
+ pass
+
+
+class ResendAPIError(ResendSyncError):
+ """Exception for Resend API errors."""
+
+ pass
+
+
+def get_keycloak_users(offset: int = 0, limit: int = 100) -> List[Dict[str, Any]]:
+ """Get users from Keycloak using the admin client.
+
+ Args:
+ offset: The offset to start from.
+ limit: The maximum number of users to return.
+
+ Returns:
+ A list of users.
+
+ Raises:
+ KeycloakClientError: If the API call fails.
+ """
+ try:
+ keycloak_admin = get_keycloak_admin()
+
+ # Get users with pagination
+ # The Keycloak API uses 'first' for offset and 'max' for limit
+ params: Dict[str, Any] = {
+ 'first': offset,
+ 'max': limit,
+ 'briefRepresentation': False, # Get full user details
+ }
+
+ users_data = keycloak_admin.get_users(params)
+ logger.info(f'Fetched {len(users_data)} users from Keycloak')
+
+ # Transform the response to match our expected format
+ users = []
+ for user in users_data:
+ if user.get('email'): # Ensure user has an email
+ users.append(
+ {
+ 'id': user.get('id'),
+ 'email': user.get('email'),
+ 'first_name': user.get('firstName'),
+ 'last_name': user.get('lastName'),
+ 'username': user.get('username'),
+ }
+ )
+
+ return users
+ except KeycloakError:
+ logger.exception('Failed to get users from Keycloak')
+ raise
+ except Exception:
+ logger.exception('Unexpected error getting users from Keycloak')
+ raise
+
+
+def get_total_keycloak_users() -> int:
+ """Get the total number of users in Keycloak.
+
+ Returns:
+ The total number of users.
+
+ Raises:
+ KeycloakClientError: If the API call fails.
+ """
+ try:
+ keycloak_admin = get_keycloak_admin()
+ count = keycloak_admin.users_count()
+ return count
+ except KeycloakError:
+ logger.exception('Failed to get total users from Keycloak')
+ raise
+ except Exception:
+ logger.exception('Unexpected error getting total users from Keycloak')
+ raise
+
+
+def get_resend_contacts(audience_id: str) -> Dict[str, Dict[str, Any]]:
+ """Get contacts from Resend.
+
+ Args:
+ audience_id: The Resend audience ID.
+
+ Returns:
+ A dictionary mapping email addresses to contact data.
+
+ Raises:
+ ResendAPIError: If the API call fails.
+ """
+ print('getting resend contacts')
+ print('has resend contacts', hasattr(resend, 'Contacts'))
+ try:
+ contacts = resend.Contacts.list(audience_id).get('data', [])
+ # Create a dictionary mapping email addresses to contact data for
+ # efficient lookup
+ return {contact['email'].lower(): contact for contact in contacts}
+ except Exception:
+ logger.exception('Failed to get contacts from Resend')
+ raise
+
+
+@retry(
+ stop=stop_after_attempt(MAX_RETRIES),
+ wait=wait_exponential(
+ multiplier=INITIAL_BACKOFF_SECONDS,
+ max=MAX_BACKOFF_SECONDS,
+ exp_base=BACKOFF_FACTOR,
+ ),
+ retry=retry_if_exception_type((ResendError, KeycloakClientError)),
+)
+def add_contact_to_resend(
+ audience_id: str,
+ email: str,
+ first_name: Optional[str] = None,
+ last_name: Optional[str] = None,
+) -> Dict[str, Any]:
+ """Add a contact to the Resend audience with retry logic.
+
+ Args:
+ audience_id: The Resend audience ID.
+ email: The email address of the contact.
+ first_name: The first name of the contact.
+ last_name: The last name of the contact.
+
+ Returns:
+ The API response.
+
+ Raises:
+ ResendAPIError: If the API call fails after retries.
+ """
+ try:
+ params = {'audience_id': audience_id, 'email': email}
+
+ if first_name:
+ params['first_name'] = first_name
+
+ if last_name:
+ params['last_name'] = last_name
+
+ return resend.Contacts.create(params)
+ except Exception:
+ logger.exception(f'Failed to add contact {email} to Resend')
+ raise
+
+
+def send_welcome_email(
+ email: str,
+ first_name: Optional[str] = None,
+ last_name: Optional[str] = None,
+) -> Dict[str, Any]:
+ """Send a welcome email to a new contact.
+
+ Args:
+ email: The email address of the contact.
+ first_name: The first name of the contact.
+ last_name: The last name of the contact.
+
+ Returns:
+ The API response.
+
+ Raises:
+ ResendError: If the API call fails.
+ """
+ try:
+ # Prepare the recipient name
+ recipient_name = ''
+ if first_name:
+ recipient_name = first_name
+ if last_name:
+ recipient_name += f' {last_name}'
+
+ # Personalize greeting based on available information
+ greeting = f'Hi {recipient_name},' if recipient_name else 'Hi there,'
+
+ # Prepare email parameters
+ params = {
+ 'from': os.environ.get(
+ 'RESEND_FROM_EMAIL', 'All Hands Team '
+ ),
+ 'to': [email],
+ 'subject': 'Welcome to OpenHands Cloud',
+ 'html': f"""
+
+
{greeting}
+
Thanks for joining OpenHands Cloud — we're excited to help you start building with the world's leading open source AI coding agent!
+
Here are three quick ways to get started:
+
+ - Connect your Git repo – Link your GitHub or GitLab repository in seconds so OpenHands can begin understanding your codebase and suggest tasks.
+ - Use OpenHands on an issue or pull request – Label an issue with 'openhands' or mention @openhands on any PR comment to generate explanations, tests, refactors, or doc fixes tailored to the exact lines you're reviewing.
+ - Join the community – Drop into our Slack Community to share tips, feedback, and help shape the next features on our roadmap.
+
+
Have questions? Want to share feedback? Just reply to this email—we're here to help.
+
Happy coding!
+
The All Hands AI team
+