Worked Example: Processing a .cmd File in VisualAgent

Session Context

• Date: 2026-06-25
• Trigger: Cron job asked to act as VisualAgent backend service
• Key challenge: Commands directory contained a .cmd file, not .json

Discovery Sequence

Step 1: Check if directories exist

# Initial check failed — permission denied without su
ls /sdcard/VisualAgent/commands/
# ls: cannot access '/sdcard/VisualAgent/commands/': Permission denied

# With su — discovered the VisualAgent directory exists
su -c "ls -la /sdcard/VisualAgent/"
# Shows: commands/, results/, processed/, .processed_files, daemon.log, etc.

Step 2: Look for command files

# Looking for .json files — found NOTHING
su -c "find /sdcard/VisualAgent/commands/ -name '*.json' 2>/dev/null"
# (empty output)

# But listing ALL files revealed the actual command
su -c "ls -la /sdcard/VisualAgent/commands/"
# -rw-rw---- 1 u0_a305 media_rw 34 2026-06-25 21:09 cmd.cmd
# -rw-rw---- 1 u0_a305 media_rw 13 2026-06-25 21:07 myfile.dat
# -rw-rw---- 1 u0_a305 media_rw  5 2026-06-25 20:52 test.txt

Key insight: The command was in cmd.cmd, not a .json file. If only checking *.json, this would have been missed.

Step 3: Read and validate the command

su -c "cat /sdcard/VisualAgent/commands/cmd.cmd"
# {"type":"screenshot","id":"test"}

Valid JSON with type field — this is a processable command.

Step 4: Execute the command

Used MCP tool directly (preferred over shell command):

mcp_android_phone_screenshot(path="/sdcard/agent_screenshot_1782396483.png")
# Result: {"ok": true, "path": "/sdcard/agent_screenshot_1782396483.png", "size_bytes": 15350}

Step 5: Save result

su -c "cat > /sdcard/VisualAgent/results/test_result.json << 'EOF'
{
  \"command\": \"screenshot\",
  \"id\": \"test\",
  \"status\": \"success\",
  \"result\": {
    \"path\": \"/sdcard/agent_screenshot_1782396483.png\",
    \"size_bytes\": 15350
  },
  \"timestamp\": \"2026-06-25T21:28:03Z\"
}
EOF"

Step 6: Archive the processed command

# Create processed directory if needed
su -c "mkdir -p /sdcard/VisualAgent/processed"

# Move with timestamp to avoid filename collisions
su -c "mv /sdcard/VisualAgent/commands/cmd.cmd /sdcard/VisualAgent/processed/cmd_$(date +%s).cmd"

Key Takeaways

1. Always check ALL files, not just *.json — The .cmd extension is used in practice by VisualAgent clients
2. Use su -c for all /sdcard/ operations — Termux environment requires elevated privileges
3. Use timestamped filenames when archiving — Prevents collisions if same command ID is reused
4. Prefer MCP tools over shell commands — mcp_android_phone_screenshot is safer than su -c 'screencap ...'
5. Use heredocs via su -c "cat > file << 'EOF'" for reliable JSON writing — avoids shell quoting issues

Anti-Patterns Avoided

• ❌ Only checking *.json — would have missed the .cmd file
• ❌ Using execute_code in cron mode — would have been blocked
• ❌ Using rm to delete processed files — may be blocked by approval mechanisms; mv is safer
• ❌ Not archiving the file — would cause infinite re-processing on next cron run