Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
"""Android System Services routes."""
import re
from fastapi import APIRouter, Depends, HTTPException, Query
from pydantic import BaseModel, Field
from typing import Dict, Any
from ._dispatcher import AndroidService
from core.logging import get_logger
from services.plugin.deps import get_android_service
logger = get_logger(__name__)
router = APIRouter(prefix="/api/android", tags=["android"])
# USB, emulator, TCP and wireless-debugging serials. The first character
# must be alphanumeric so a device ID cannot look like a command-line flag.
# Also enforce this at the subprocess boundary for callers outside FastAPI.
_DEVICE_ID_PATTERN = r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$"
class AndroidServiceRequest(BaseModel):
"""Request model for Android service execution."""
service_id: str = Field(..., description="Android service ID (e.g., 'battery', 'network', 'app_launcher')")
action: str = Field(..., description="Service action to perform (e.g., 'status', 'launch', 'list')")
parameters: Dict[str, Any] = Field(default_factory=dict, description="Action-specific parameters")
android_host: str = Field(default="localhost", description="Android device API host")
android_port: int = Field(default=8888, description="Android device API port")
@router.post("/execute")
async def execute_android_service(request: AndroidServiceRequest, android_service: AndroidService = Depends(get_android_service)):
"""Execute an Android system service action.
Examples:
- Battery status: {"service_id": "battery", "action": "status"}
- Launch app: {"service_id": "app_launcher", "action": "launch", "parameters": {"package_name": "com.android.settings"}}
- List apps: {"service_id": "app_list", "action": "list", "parameters": {"include_system": false}}
"""
logger.info(
"[Android API] Executing service",
service_id=request.service_id,
action=request.action,
android_host=request.android_host,
android_port=request.android_port,
)
result = await android_service.execute_service(
node_id="api_call",
service_id=request.service_id,
action=request.action,
parameters=request.parameters,
android_host=request.android_host,
android_port=request.android_port,
)
return result
@router.get("/status")
async def check_device_status(
android_host: str = "localhost", android_port: int = 8888, android_service: AndroidService = Depends(get_android_service)
):
"""Check if Android device API is reachable."""
logger.info("[Android API] Checking device status", android_host=android_host, android_port=android_port)
status = await android_service.check_device_status(android_host=android_host, android_port=android_port)
return status
@router.get("/services/{service_id}/actions")
async def get_service_actions(service_id: str, android_service: AndroidService = Depends(get_android_service)):
"""Get available actions for a specific Android service.
Returns list of action options that can be performed on the service.
"""
logger.info(f"[Android API] Getting actions for service: {service_id}")
actions = android_service.get_service_actions(service_id)
if not actions:
return {"success": False, "error": f"Unknown service: {service_id}", "actions": []}
return {"success": True, "service_id": service_id, "actions": actions}
@router.get("/services/{service_id}/actions/{action}/parameters")
async def get_action_parameters(service_id: str, action: str, android_service: AndroidService = Depends(get_android_service)):
"""Get default parameters for a specific service action.
Returns default parameter template that can be used as a starting point.
"""
logger.info(f"[Android API] Getting parameters for: {service_id}/{action}")
default_params = android_service.get_default_parameters(service_id, action)
return {"success": True, "service_id": service_id, "action": action, "default_parameters": default_params}
@router.get("/devices")
async def list_android_devices(android_service: AndroidService = Depends(get_android_service)):
"""List all connected Android devices via ADB."""
return await android_service.list_devices()
@router.post("/port-forward")
async def setup_port_forwarding(
device_id: str = Query(..., pattern=_DEVICE_ID_PATTERN, max_length=64),
local_port: int = Query(8888, ge=1024, le=65535),
device_port: int = Query(8888, ge=1024, le=65535),
):
"""Setup ADB port forwarding for Android device communication."""
import subprocess
if not isinstance(device_id, str) or re.fullmatch(_DEVICE_ID_PATTERN, device_id) is None:
raise HTTPException(status_code=422, detail="Invalid Android device ID")
if (
type(local_port) is not int
or type(device_port) is not int
or not 1024 <= local_port <= 65535
or not 1024 <= device_port <= 65535
):
raise HTTPException(status_code=422, detail="Ports must be integers between 1024 and 65535")
try:
from services.process_environment import without_onepassword_environment
# Keep the executable literal at the call site, with validated inputs
# confined to individual arguments. No shell interprets these values.
result = subprocess.run(
["adb", "-s", device_id, "forward", f"tcp:{int(local_port)}", f"tcp:{int(device_port)}"],
shell=False,
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=5,
env=without_onepassword_environment(),
)
if result.returncode == 0:
logger.info(f"[Android] Port forwarding setup: {device_id} tcp:{local_port} -> tcp:{device_port}")
return {
"success": True,
"device_id": device_id,
"local_port": local_port,
"device_port": device_port,
"message": f"Port forwarding active: localhost:{local_port} -> device:{device_port}",
}
else:
error_msg = result.stderr.strip() or result.stdout.strip()
logger.error(f"[Android] Port forwarding failed: {error_msg}")
return {"success": False, "error": error_msg}
except FileNotFoundError:
logger.error("[Android] ADB not found in PATH")
return {"success": False, "error": "ADB not found. Please install Android SDK Platform Tools"}
except Exception as e:
logger.error("[Android] Port forwarding error", error=str(e), exc_info=True)
return {"success": False, "error": "Port forwarding failed"}
@router.get("/health")
async def android_health_check():
"""Android service health check."""
return {"status": "OK", "service": "android"}
@router.get("/relay-status")
async def get_relay_connection_status():
"""Get relay connection status for remote Android devices.
Returns connection status including whether a relay connection is active
and the paired Android device.
"""
try:
from ._relay import get_current_relay_client
relay_client = get_current_relay_client()
if relay_client and relay_client.is_connected():
return {
"success": True,
"connected": True,
"paired": relay_client.is_paired(),
"connection_type": "relay",
"device_id": relay_client.paired_device_id,
"device_name": relay_client.paired_device_name,
"qr_data": relay_client.qr_data if not relay_client.is_paired() else None,
"status": "paired" if relay_client.is_paired() else "waiting_for_pairing",
}
else:
return {
"success": True,
"connected": False,
"paired": False,
"connection_type": None,
"device_id": None,
"device_name": None,
"status": "disconnected",
}
except Exception as e:
logger.error("[Android] Failed to get relay status", error=str(e), exc_info=True)
return {"success": False, "connected": False, "error": "Failed to get relay status", "status": "error"}