Self-improving AI Employees for everyone
Android Service Nodes - Shared Pattern
All 16 Android service nodes share a single backend handler, a single frontend factory, and a single execution path. This document is the authoritative description of that shared behaviour. Individual per-node docs link back here for everything that is not node-specific.
Single plugin base, registry-driven dispatch
Wave 11.C migrated all 16 Android nodes to self-contained plugin folders
under server/nodes/android/<service>/__init__.py. Each is a trivial
subclass of the shared AndroidServiceBase (server/nodes/android/_base.py)
that sets type / display_name / description / tool_name only. The old
handlers/android.py::handle_android_service handler and the
android_service.py service module are deleted. Dispatch flows
through BaseNode.execute() -> the @Operation("invoke") method on
AndroidServiceBase.
| Concern | Location |
|---|---|
| Plugin base | server/nodes/android/_base.py::AndroidServiceBase.invoke (@Operation("invoke")) |
| Underlying service | server/nodes/android/_dispatcher.py::AndroidService.execute_service |
| Registry binding | plugins self-register via BaseNode.__init_subclass__; merged into NodeExecutor via _PLUGIN_HANDLERS (server/services/node_executor.py line 124) |
| Output flatten | server/services/node_executor.py lines 173-181 |
The @Operation("invoke") method maps the incoming node_type (camelCase) to a
backend service_id (snake_case) via the SERVICE_ID_MAP dict in _base.py:
SERVICE_ID_MAP = {
'batteryMonitor': 'battery',
'networkMonitor': 'network',
'systemInfo': 'system_info',
'location': 'location',
'appLauncher': 'app_launcher',
'appList': 'app_list',
'wifiAutomation': 'wifi_automation',
'bluetoothAutomation': 'bluetooth_automation',
'audioAutomation': 'audio_automation',
'deviceStateAutomation': 'device_state',
'screenControlAutomation': 'screen_control',
'airplaneModeControl': 'airplane_mode',
'motionDetection': 'motion_detection',
'environmentalSensors': 'environmental_sensors',
'cameraControl': 'camera_control',
'mediaControl': 'media_control',
}
The frontend hidden service_id param is ignored for known node types;
the plugin's own map wins (SERVICE_ID_MAP.get(self.type, ...)). See "Known
inconsistencies" below.
Shared parameter set
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
service_id |
hidden | per-node (see frontend) | auto | Unused for dispatch; handler uses its own map |
android_host |
hidden | localhost |
no | Target host for local ADB mode |
android_port |
hidden | 8888 |
no | Target port for local ADB mode |
label |
string | display name | no | Custom label, cosmetic only |
action |
options | per-node default | yes | Action to perform - loaded dynamically from /api/android/services/<service_id>/actions |
parameters |
dict or JSON string | {} |
no | Per-action nested parameters |
package_name |
string | "" |
conditional | Only surfaced by appLauncher; handler promotes it into parameters automatically |
Root-level package_name is hoisted into parameters before dispatch by the
invoke method (the only key promoted today).
If parameters is received as a string it is coerced via json.loads() —
first in AndroidServiceParams._coerce_parameters (a field_validator(mode="before"))
and again defensively inside invoke; on JSONDecodeError the value is
silently replaced with {}.
Execution paths
AndroidService.execute_service picks one of two transports at call time:
- Relay path: if
get_current_relay_client().is_paired()returns a paired client, the call is forwarded to the remote device over the relay WebSocket via_execute_via_relay(...). - Local HTTP path: otherwise
httpx.AsyncClientposts{"action": action, "parameters": parameters}tohttp://{android_host}:{android_port}/api/{service_id}with the service's configureddefault_timeout.
flowchart TD
A[AndroidServiceBase.invoke @Operation] --> B[Look up service_id via SERVICE_ID_MAP self.type<br/>fallback to parameters.service_id then 'battery']
B --> C[Parse parameters<br/>coerce JSON string, promote package_name]
C --> D[android_service.execute_service<br/>node_id, service_id, action, parameters, host, port]
D --> E{relay client paired?}
E -- yes --> F[_execute_via_relay]
E -- no --> G[POST /api/{service_id} on android_host:android_port]
G -- 200 --> H[Return success + data]
G -- non-200 --> I[Return success=false + HTTP error]
G -- httpx.ConnectError --> J[Return success=false + 'Cannot connect...']
G -- httpx.TimeoutException --> K[Return success=false + 'Request timeout...']
G -- other Exception --> L[Return success=false + str(e)]
H --> M[NodeExecutor flattens result.data to top level]
Output envelope
AndroidService.execute_service returns:
{
success: boolean,
node_id: string,
node_type: 'androidService',
result: {
service_id: string,
action: string,
data: object, // raw service response under 'data' key
response_time: number, // httpx response elapsed seconds
android_host: string,
android_port: number,
timestamp: string // ISO8601
},
execution_time: number,
timestamp: string
}
NodeExecutor then flattens the result.data contents to the top level of
result before writing to the output store, so downstream templates can use
{{batteryMonitor.battery_level}} instead of
{{batteryMonitor.data.battery_level}}. The original data key is preserved
alongside the promoted fields. Metadata keys (service_id, action,
response_time, android_host, android_port, timestamp) are also
preserved.
Side effects
- External HTTP:
POST http://{android_host}:{android_port}/api/{service_id}(local path) - External WebSocket: relay RPC call when a paired client exists
- Database writes: none in the handler itself; the
NodeExecutorwrites three output-store keys (output_main,output_top,output_0) with the flattened payload. - Broadcasts: none direct from the handler. Status broadcasts are emitted by the outer executor (not by this handler).
- File I/O: none.
- Subprocess: none direct (any ADB port forwarding is set up out-of-band via the Android router, not by this handler).
External dependencies
- Transport selection:
services.android.get_current_relay_clientat call time - Local mode:
httpx.AsyncClientwithself.default_timeout(seeAndroidService.__init__) - Connection state: Android service node execution requires
paired=truein relay mode. The relayconnectedstate alone is not sufficient. - Environment variables: none; host/port come from hidden node params.
ADB port forwarding
POST /api/android/port-forward in the Android router
sets up local device communication outside node execution. It accepts USB,
emulator, TCP and wireless-debugging serials of up to 64 characters. Serials
must start with an ASCII letter or digit; subsequent characters may also be
., _, :, or -. Both ports must be integers between 1024 and 65535.
FastAPI checks the query parameters, and the handler validates them again
before starting ADB, including when called directly from Python. Invalid input
returns HTTP 422 without starting a subprocess. The subprocess receives a
literal argument list beginning with adb, uses shell=False, has a five-second
timeout, and excludes the 1Password bootstrap environment. Valid requests retain
the existing success/error response envelopes and do not add device discovery.
The port-forward regression tests cover valid serials, boundary ports, malicious inputs, direct calls and ADB failures.
Known inconsistencies & edge cases
Frontend/backend service_id mismatch for four nodes. The frontend
createAndroidServiceNodefactory stores the following serviceIds as hidden params:deviceStateAutomation->device_state_automationscreenControlAutomation->screen_control_automationairplaneModeControl->airplane_mode_control
The handler's
SERVICE_ID_MAPoverrides those with:deviceStateAutomation->device_statescreenControlAutomation->screen_controlairplaneModeControl->airplane_mode
The plugin map wins because it is looked up first, but any consumer that reads the hidden param directly would see a different value. The same discrepancy exists in the AI-tool path
server/nodes/android/_base.py::execute_android_service_tool.JSON parse failure is silent. A
parametersstring that fails to parse is replaced with{}and logged only at debug level.No validation of required action params.
appLauncherneedspackage_name, but the plugin never checks for it - an empty value is passed through and the Android side is expected to error.default_timeoutis service-instance-wide. All sensor / camera / media calls share the same timeout; there is no per-action override.Output flatten can shadow metadata. If the device returns a
datadict whose keys collide withresultmetadata keys (action,service_id,timestamp, ...), the flatten mergesdataafter metadata, so the data wins and the metadata is lost from the promoted view.execute_servicenever raises, butinvokedoes on failure.AndroidService.execute_servicereturns asuccess=falseenvelope for every exception path. The@Operation("invoke")wrapper then re-raises aRuntimeErrorwhenresult["success"] is False(usingresult["error"]), soBaseNode.execute()produces the standard error envelope. On successinvokereturnsresult["result"](or the whole dict if noresultkey).
Related
- Android service infrastructure:
server/nodes/android/ - Status broadcaster (two-state model): Status Broadcaster
- Android-agent skills:
server/skills/android_agent/ - AI-tool dispatch (direct service tools; the
androidToolaggregator was retired):execute_android_service_toolinserver/nodes/android/_base.py, called fromserver/services/handlers/tools.py::execute_tool