visualagent-service-discovery.md 7.4 KB

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:

  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.

# 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:

  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

# 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:

# 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]