# 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 ```bash 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`): ```bash 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: 1. **Has the most recent successful execution** in its log file 2. **Produces correct results** (not `{"status":"error","message":"未知命令类型"}`) 3. **Uses `/data/local/tmp/VisualAgent/`** rather than `/sdcard/VisualAgent/` (avoids FUSE issues) 4. **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. ```bash # 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: ```bash # 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 ```bash # 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 # 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**: ```bash # 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**: 1. Uses Python `json.loads()` - reliable parsing, no `grep`/`cut` fragility 2. Uses `/data/local/tmp/` - avoids FUSE filesystem visibility issues 3. Handles both `command` and `type` fields 4. Base64-encodes results for safe writing via `su` 5. Produces structured JSON results with `success`, `output`, `saved_to` fields ## Common Stale Infrastructure Patterns ### Stale PID file with dead process ```bash # 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": 1. **DON'T** write a new Python script with `execute_code` (blocked in cron) 2. **DO** check for existing `visualagent_service.py` 3. **If found**: Run it directly with `terminal` 4. **If not found**: Use direct MCP tool calls for each operation 5. **For command file creation**: Use `terminal` with `su -c` and base64 encoding Example cron workflow: ```bash # 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] ```