refactor: enforce architectural boundaries by updating OpenClaw service imports

backend/app/services/openclaw/__init__.py

@@ -1,88 +1,7 @@
-"""OpenClaw lifecycle services package."""
+"""OpenClaw lifecycle package.
 
-from .admin_service import (
-    AbstractGatewayMainAgentManager,
-    DefaultGatewayMainAgentManager,
-    GatewayAdminLifecycleService,
-)
-from .agent_service import (
-    AbstractProvisionExecution,
-    ActorContextLike,
-    AgentLifecycleService,
-    AgentUpdateOptions,
-    AgentUpdateProvisionRequest,
-    AgentUpdateProvisionTarget,
-    BoardAgentProvisionExecution,
-    MainAgentProvisionExecution,
-)
-from .constants import DEFAULT_CHANNEL_HEARTBEAT_VISIBILITY, DEFAULT_HEARTBEAT_CONFIG
-from .coordination_service import AbstractGatewayMessagingService, GatewayCoordinationService
-from .exceptions import (
-    GatewayErrorPolicy,
-    GatewayOperation,
-    map_gateway_error_message,
-    map_gateway_error_to_http_exception,
-)
-from .onboarding_service import BoardOnboardingMessagingService
-from .provisioning import (
-    AgentProvisionRequest,
-    LeadAgentOptions,
-    LeadAgentRequest,
-    MainAgentProvisionRequest,
-    ProvisionOptions,
-    cleanup_agent,
-    ensure_board_lead_agent,
-    patch_gateway_agent_heartbeats,
-    provision_agent,
-    provision_main_agent,
-    sync_gateway_agent_heartbeats,
-)
-from .session_service import GatewaySessionService, GatewayTemplateSyncQuery
-from .shared import (
-    GatewayAgentIdentity,
-    optional_gateway_config_for_board,
-    require_gateway_config_for_board,
-    resolve_trace_id,
-    send_gateway_agent_message,
-)
+Import concrete modules directly (for example: ``app.services.openclaw.agent_service``)
+to keep architectural boundaries explicit.
+"""
 
-__all__ = [
-    "AbstractGatewayMainAgentManager",
-    "DefaultGatewayMainAgentManager",
-    "GatewayAdminLifecycleService",
-    "AbstractProvisionExecution",
-    "ActorContextLike",
-    "AgentLifecycleService",
-    "AgentUpdateOptions",
-    "AgentUpdateProvisionRequest",
-    "AgentUpdateProvisionTarget",
-    "BoardAgentProvisionExecution",
-    "MainAgentProvisionExecution",
-    "DEFAULT_CHANNEL_HEARTBEAT_VISIBILITY",
-    "DEFAULT_HEARTBEAT_CONFIG",
-    "AbstractGatewayMessagingService",
-    "GatewayCoordinationService",
-    "GatewayErrorPolicy",
-    "GatewayOperation",
-    "map_gateway_error_message",
-    "map_gateway_error_to_http_exception",
-    "BoardOnboardingMessagingService",
-    "AgentProvisionRequest",
-    "LeadAgentOptions",
-    "LeadAgentRequest",
-    "MainAgentProvisionRequest",
-    "ProvisionOptions",
-    "cleanup_agent",
-    "ensure_board_lead_agent",
-    "patch_gateway_agent_heartbeats",
-    "provision_agent",
-    "provision_main_agent",
-    "sync_gateway_agent_heartbeats",
-    "GatewaySessionService",
-    "GatewayTemplateSyncQuery",
-    "GatewayAgentIdentity",
-    "optional_gateway_config_for_board",
-    "require_gateway_config_for_board",
-    "resolve_trace_id",
-    "send_gateway_agent_message",
-]
+__all__: list[str] = []

backend/app/services/openclaw/shared.py

@@ -8,8 +8,8 @@ from uuid import UUID, uuid4
 
 from fastapi import HTTPException, status
 
-from app.integrations.openclaw_gateway import GatewayConfig as GatewayClientConfig
-from app.integrations.openclaw_gateway import ensure_session, send_message
+from app.integrations.openclaw_gateway import GatewayConfig as _GatewayClientConfig
+from app.integrations.openclaw_gateway import OpenClawGatewayError, ensure_session, send_message
 from app.models.boards import Board
 from app.models.gateways import Gateway
 from app.services.openclaw.constants import (
@@ -22,6 +22,9 @@ if TYPE_CHECKING:
     from sqlmodel.ext.asyncio.session import AsyncSession
 
 
+GatewayClientConfig = _GatewayClientConfig
+
+
 class GatewayAgentIdentity:
     """Naming and identity rules for Mission Control gateway-main agents."""
 
@@ -87,6 +90,28 @@ async def send_gateway_agent_message(
     await send_message(message, session_key=session_key, config=config, deliver=deliver)
 
 
+async def send_gateway_agent_message_safe(
+    *,
+    session_key: str,
+    config: GatewayClientConfig,
+    agent_name: str,
+    message: str,
+    deliver: bool = False,
+) -> GatewayTransportError | None:
+    """Best-effort gateway dispatch returning transport error when one occurs."""
+    try:
+        await send_gateway_agent_message(
+            session_key=session_key,
+            config=config,
+            agent_name=agent_name,
+            message=message,
+            deliver=deliver,
+        )
+    except GatewayTransportError as exc:
+        return exc
+    return None
+
+
 def resolve_trace_id(correlation_id: str | None, *, prefix: str) -> str:
     """Resolve a stable trace id from correlation id or generate a scoped fallback."""
     normalized = (correlation_id or "").strip()
@@ -96,3 +121,6 @@ def resolve_trace_id(correlation_id: str | None, *, prefix: str) -> str:
 
 
 logger = logging.getLogger(__name__)
+
+# Keep integration exceptions behind the OpenClaw service boundary.
+GatewayTransportError = OpenClawGatewayError