VisualAgent Service Discovery on Devices with Multiple Implementations
Problem
Devices that have been used for VisualAgent automation over multiple sessions often accumulate multiple implementations:
visualagent_service.py(Python service, canonical)visualagent_daemon.sh(Bash daemon with start/stop/once/file modes)visualagent_processor.sh(Bash processor, simpler)visual_agent.py,visual_agent.sh(older naming variants)- Various cron wrapper scripts
All may exist simultaneously in /data/data/com.termux/files/home/ and may have stale PID files, stale lock files, or dead processes.
Discovery Checklist
When asked to "build a VisualAgent backend" or "create a monitoring service":
Step 1: Search for ALL implementations
find /data/data/com.termux/files/home/ -maxdepth 1 \( -name '*visualagent*' -o -name '*visual_agent*' \) -type f 2>/dev/null
Also check for Python scripts specifically (the canonical implementation is always a .py):
find /data/data/com.termux/files/home/ -maxdepth 1 -name '*.py' -type f 2>/dev/null | xargs grep -l -i 'visualagent\|visual_agent' 2>/dev/null
Step 2: Check which is the CANONICAL implementation
The canonical implementation is the one that:
- Has the most recent successful execution in its log file
- Produces correct results (not
{"status":"error","message":"未知命令类型"}) - Uses
/data/local/tmp/VisualAgent/rather than/sdcard/VisualAgent/(avoids FUSE issues) - Is a Python script (
visualagent_service.py) rather than shell (more robust JSON parsing)
Step 3: Verify the canonical implementation works
Important: Always check BOTH /data/local/tmp/VisualAgent/ AND /sdcard/VisualAgent/ — the canonical implementation may be configured for either path. The key indicator is the Python script's internal COMMANDS_DIR variable.
# Check which path the canonical service uses
su -c "grep -n 'COMMANDS_DIR\|RESULTS_DIR' /data/data/com.termux/files/home/visualagent_service.py"
Then create a test command in the correct path:
# Create a test command (use the path discovered above)
su -c 'echo '\''{"command":"screenshot","filename":"discovery_test.png"}'\'' > /data/local/tmp/VisualAgent/commands/discovery_test.json'
# Run the service
python3 /data/data/com.termux/files/home/visualagent_service.py
# Check result
su -c "cat /data/local/tmp/VisualAgent/results/discovery_test_result.json"
Expected result: {"success": true, ...} with a valid saved_to path.
If you get {"status":"error","message":"未知命令类型"}, you're using the WRONG implementation (likely visualagent_processor.sh which uses grep/cut parsing and fails on the command field name).
Step 4: Check for stale infrastructure
# Check PID files
cat /sdcard/VisualAgent/daemon.pid 2>/dev/null
cat /data/local/tmp/VisualAgent/daemon.pid 2>/dev/null
# Verify PIDs are alive
ps | grep <pid>
# Check for stale lock files
ls -la /sdcard/VisualAgent/*.pid /data/local/tmp/VisualAgent/*.pid 2>/dev/null
The Canonical Implementation: visualagent_service.py
Path: /data/data/com.termux/files/home/visualagent_service.py
Working directories:
- Commands:
/data/local/tmp/VisualAgent/commands/ - Results:
/data/local/tmp/VisualAgent/results/ - Processed:
/data/local/tmp/VisualAgent/processed/
Usage:
# Single scan (for cron)
python3 /data/data/com.termux/files/home/visualagent_service.py
# The script is NOT a daemon - it scans once and exits
# For continuous monitoring, use cron to run it periodically
Why it's canonical:
- Uses Python
json.loads()- reliable parsing, nogrep/cutfragility - Uses
/data/local/tmp/- avoids FUSE filesystem visibility issues - Handles both
commandandtypefields - Base64-encodes results for safe writing via
su - Produces structured JSON results with
success,output,saved_tofields
Common Stale Infrastructure Patterns
Stale PID file with dead process
# PID file exists
cat /sdcard/VisualAgent/daemon.pid
# → 12345
# But process is dead
ps | grep 12345
# → (no output)
Action: Remove the stale PID file. The daemon is dead; use visualagent_service.py instead.
Multiple result files with {"status":"error"}
If you see many result files containing {"status":"error","message":"未知命令类型"}, the visualagent_processor.sh (or similar shell implementation) is running and failing. This implementation uses fragile grep/cut parsing that breaks on valid JSON.
Action: Stop using the shell implementation. Use visualagent_service.py instead.
Files in /sdcard/VisualAgent/ but not /data/local/tmp/VisualAgent/
If commands placed in /sdcard/VisualAgent/commands/ immediately disappear (moved to processed/), a watcher is running against the /sdcard/ path. But the canonical implementation uses /data/local/tmp/.
Action: Use /data/local/tmp/VisualAgent/commands/ for your commands. The /sdcard/ watcher is likely a stale or alternative implementation.
Files in /data/local/tmp/VisualAgent/ but not /sdcard/VisualAgent/
The canonical implementation may be configured for /data/local/tmp/ only. In this case, /sdcard/VisualAgent/ may contain stale files from an older implementation or a different watcher. The Python service at visualagent_service.py is the authoritative source — check its COMMANDS_DIR variable to confirm the active path.
Action: Always check the Python script's internal configuration before assuming which path is canonical. Use grep 'COMMANDS_DIR' /data/data/com.termux/files/home/visualagent_service.py to discover the correct path.
If commands placed in /sdcard/VisualAgent/commands/ immediately disappear (moved to processed/), a watcher is running against the /sdcard/ path. But the canonical implementation uses /data/local/tmp/.
Action: Use /data/local/tmp/VisualAgent/commands/ for your commands. The /sdcard/ watcher is likely a stale or alternative implementation.
Decision Tree
Are there visualagent* files in /data/data/com.termux/files/home/?
├── YES → Is visualagent_service.py present?
│ ├── YES → Does it produce correct results when tested?
│ │ ├── YES → Use visualagent_service.py (canonical)
│ │ └── NO → Check if python3 is available; fix script if needed
│ └── NO → Is visualagent_daemon.sh present?
│ ├── YES → Does it have a working "file" mode?
│ │ ├── YES → Use daemon.sh file mode for single files
│ │ └── NO → Fall back to direct MCP tool calls
│ └── NO → Build new infrastructure using /data/local/tmp/
└── NO → Build new infrastructure using /data/local/tmp/
Integration Pattern for Cron Jobs
When running as a cron job and asked to "build a VisualAgent service":
- DON'T write a new Python script with
execute_code(blocked in cron) - DO check for existing
visualagent_service.py - If found: Run it directly with
terminal - If not found: Use direct MCP tool calls for each operation
- For command file creation: Use
terminalwithsu -cand base64 encoding
Example cron workflow:
# Check for commands
su -c "ls /data/local/tmp/VisualAgent/commands/" 2>/dev/null
# If found, run the service
python3 /data/data/com.termux/files/home/visualagent_service.py
# If not found, respond [SILENT]