fix: route himalaya chat commands to device backend

backend/app/api/api.py

@@ -56,6 +56,7 @@
 from app.api.endpoints.internal import (
     callback_router,
     chat_storage_router,
+    devices_router as internal_devices_router,
     services_router,
     skills_router,
     subscriptions_router,
@@ -175,6 +176,9 @@
 
 api_router.include_router(skills_router, prefix="/internal", tags=["internal-skills"])
 api_router.include_router(tables_router, prefix="/internal", tags=["internal-tables"])
+api_router.include_router(
+    internal_devices_router, prefix="/internal", tags=["internal-devices"]
+)
 api_router.include_router(
     internal_bots_router, prefix="/internal", tags=["internal-bots"]
 )

backend/app/api/endpoints/devices.py

@@ -61,6 +61,42 @@ class DeviceUpgradeResponse(BaseModel):
     message: str = Field(..., description="Human-readable status message")
 
 
+class DeviceSandboxExecRequest(BaseModel):
+    """Request model for executing a command on a user device."""
+
+    command: str = Field(..., min_length=1, description="Command to execute")
+    working_dir: str = Field(
+        default="/home/user",
+        description="Working directory for command execution",
+    )
+    timeout_seconds: int = Field(
+        default=300,
+        ge=1,
+        le=1800,
+        description="Command timeout in seconds",
+    )
+    required_capability: Optional[str] = Field(
+        default=None,
+        description="Optional device capability required for routing",
+    )
+    device_id: Optional[str] = Field(
+        default=None,
+        description="Optional explicit device ID override",
+    )
+
+
+class DeviceSandboxExecResponse(BaseModel):
+    """Response model for a device-backed command execution."""
+
+    success: bool = Field(..., description="Whether the command succeeded")
+    stdout: str = Field(default="", description="Standard output")
+    stderr: str = Field(default="", description="Standard error")
+    exit_code: int = Field(..., description="Process exit code")
+    execution_time: float = Field(..., description="Execution time in seconds")
+    device_id: str = Field(..., description="Device that executed the command")
+    backend: str = Field(default="device", description="Execution backend identifier")
+
+
 @router.get("", response_model=DeviceListResponse)
 async def get_all_devices(
     db: Session = Depends(get_db),
@@ -162,6 +198,47 @@ async def delete_device(
     return {"message": f"Device '{device_id}' deleted"}
 
 
+@router.post("/sandbox/exec", response_model=DeviceSandboxExecResponse)
+async def execute_device_sandbox_command(
+    request: DeviceSandboxExecRequest,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(security.get_current_user),
+) -> DeviceSandboxExecResponse:
+    """
+    Execute a command on an online user device through the existing device channel.
+
+    The backend selects a compatible online device, forwards the command over
+    `/local-executor`, and returns the device's execution result.
+    """
+    from app.services.device_sandbox_service import (
+        DeviceSandboxError,
+        device_sandbox_service,
+    )
+
+    try:
+        result = await device_sandbox_service.execute_command(
+            db=db,
+            user_id=current_user.id,
+            command=request.command,
+            working_dir=request.working_dir,
+            timeout_seconds=request.timeout_seconds,
+            required_capability=request.required_capability,
+            device_id=request.device_id,
+        )
+    except DeviceSandboxError as exc:
+        logger.warning(
+            "[Device Sandbox] Command rejected: user_id=%s, error=%s",
+            current_user.id,
+            exc,
+        )
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(exc),
+        ) from exc
+
+    return DeviceSandboxExecResponse(**result)
+
+
 @router.post("/{device_id}/upgrade", response_model=DeviceUpgradeResponse)
 async def trigger_device_upgrade(
     device_id: str,

backend/app/api/endpoints/internal/__init__.py

@@ -9,6 +9,7 @@
 from .bots import router as bots_router
 from .callback import router as callback_router
 from .chat_storage import router as chat_storage_router
+from .devices import router as devices_router
 from .services import router as services_router
 from .skills import router as skills_router
 from .subscriptions import router as subscriptions_router
@@ -23,6 +24,7 @@
     "bots_router",
     "callback_router",
     "chat_storage_router",
+    "devices_router",
     "services_router",
     "skills_router",
     "subscriptions_router",

backend/app/api/endpoints/internal/devices.py

@@ -0,0 +1,69 @@
+# SPDX-FileCopyrightText: 2025 Weibo, Inc.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Internal device APIs for service-to-service communication."""
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session
+
+from app.api.dependencies import get_db
+from app.api.endpoints.devices import DeviceSandboxExecResponse
+
+router = APIRouter(prefix="/devices", tags=["internal-devices"])
+
+
+class InternalDeviceSandboxExecRequest(BaseModel):
+    """Internal request model for device-backed command execution."""
+
+    user_id: int = Field(..., ge=1, description="Owner user ID")
+    command: str = Field(..., min_length=1, description="Command to execute")
+    working_dir: str = Field(
+        default="/home/user",
+        description="Working directory for command execution",
+    )
+    timeout_seconds: int = Field(
+        default=300,
+        ge=1,
+        le=1800,
+        description="Command timeout in seconds",
+    )
+    required_capability: str | None = Field(
+        default=None,
+        description="Optional device capability required for routing",
+    )
+    device_id: str | None = Field(
+        default=None,
+        description="Optional explicit device ID override",
+    )
+
+
+@router.post("/sandbox/exec", response_model=DeviceSandboxExecResponse)
+async def execute_device_sandbox_command_internal(
+    request: InternalDeviceSandboxExecRequest,
+    db: Session = Depends(get_db),
+) -> DeviceSandboxExecResponse:
+    """Execute a command on a user's device for internal trusted services."""
+    from app.services.device_sandbox_service import (
+        DeviceSandboxError,
+        device_sandbox_service,
+    )
+
+    try:
+        result = await device_sandbox_service.execute_command(
+            db=db,
+            user_id=request.user_id,
+            command=request.command,
+            working_dir=request.working_dir,
+            timeout_seconds=request.timeout_seconds,
+            required_capability=request.required_capability,
+            device_id=request.device_id,
+        )
+    except DeviceSandboxError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(exc),
+        ) from exc
+
+    return DeviceSandboxExecResponse(**result)

backend/app/api/ws/device_namespace.py

@@ -165,6 +165,7 @@ def _register_device(
     client_ip: Optional[str] = None,
     device_type: Optional[str] = None,
     bind_shell: Optional[str] = None,
+    capabilities: Optional[list[str]] = None,
 ) -> tuple[bool, Optional[str]]:
     """
     Register or update device CRD in database.
@@ -189,6 +190,7 @@ def _register_device(
                 client_ip=client_ip,
                 device_type=device_type,
                 bind_shell=bind_shell,
+                capabilities=capabilities,
             )
         return True, None
     except Exception as e:
@@ -759,6 +761,7 @@ async def on_device_register(self, sid: str, data: dict) -> dict:
                 payload.client_ip,
                 payload.device_type.value,
                 payload.bind_shell.value,
+                payload.capabilities,
             )
             if not success:
                 return {"error": f"Registration failed: {error}"}