command-file-extension-flexibility.md 6.17 KB

Command File Extension Flexibility & Infinite Loop Prevention

Problem

VisualAgent command files may not always use the .json extension. They may use:

  • .cmd (common for command files)
  • .txt (text files containing JSON)
  • No extension at all
  • Custom extensions specific to the client's tooling

If the agent only looks for *.json files, it will miss valid commands. Worse, if a command file exists but has a non-.json extension, the agent may report "no commands found" and respond [SILENT], never processing the command.

Real-World Example

# Directory listing shows:
-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

# Agent only checks for *.json — finds nothing
su -c 'find /sdcard/VisualAgent/commands/ -name "*.json" -type f'
# (empty output)

# But the actual command is in cmd.cmd!
su -c 'cat /sdcard/VisualAgent/commands/cmd.cmd'
# {"type":"screenshot","id":"test"}

Solution: Flexible Extension Matching

Approach 1: Check All Files (Most Robust)

List ALL files in the commands directory, then filter by whether they contain valid JSON:

# List all files, not just .json
FILES=$(su -c 'ls -1 /sdcard/VisualAgent/commands/ 2>/dev/null')

for f in $FILES; do
    # Check if file contains valid JSON with a type/command field
    cmd_type=$(su -c "cat /sdcard/VisualAgent/commands/$f" | python3 -c "
import json, sys
try:
    d = json.load(sys.stdin)
    print(d.get('type') or d.get('command', ''))
except:
    print('')
" 2>/dev/null)

    if [ -n "$cmd_type" ]; then
        echo "Found command: $f (type: $cmd_type)"
        # Process this file
    fi
done

Approach 2: Check Common Extensions

If you must use extension filtering, check multiple common extensions:

# Check multiple extensions
for ext in json cmd txt; do
    FILES=$(su -c "find /sdcard/VisualAgent/commands/ -name '*.$ext' -type f 2>/dev/null")
    if [ -n "$FILES" ]; then
        echo "Found files with .$ext extension"
        # Process these files
    fi
done

Approach 3: Check All Files + Content Validation

The most robust approach: list ALL files, validate content, process valid commands:

# Get all files
ALL_FILES=$(su -c 'ls -1 /sdcard/VisualAgent/commands/ 2>/dev/null')

if [ -z "$ALL_FILES" ]; then
    echo "[SILENT]"
    exit 0
fi

# Validate each file
for f in $ALL_FILES; do
    # Skip directories
    if su -c "test -d /sdcard/VisualAgent/commands/$f"; then
        continue
    fi

    # Try to parse as JSON
    cmd_type=$(su -c "cat /sdcard/VisualAgent/commands/$f" | python3 -c "
import json, sys
try:
    d = json.load(sys.stdin)
    print(d.get('type') or d.get('command', ''))
except:
    print('')
" 2>/dev/null)

    if [ -n "$cmd_type" ]; then
        echo "Processing: $f (type: $cmd_type)"
        # ... execute command ...
    fi
done

The Infinite Loop Problem

When a command file is NOT moved/deleted after processing, the agent will find it again on the next cron run and re-execute it. This creates an infinite loop of re-processing the same command.

Root Cause

  1. Command file exists in commands/
  2. Agent processes it
  3. Agent does NOT move it to processed/ or delete it
  4. Next cron run: agent finds the same file again
  5. Repeat indefinitely

Prevention: Always Archive or Delete After Processing

Preferred: Move to processed/ directory

# After processing, move the file
su -c "mkdir -p /sdcard/VisualAgent/processed/"
su -c "mv /sdcard/VisualAgent/commands/$filename /sdcard/VisualAgent/processed/"

# Also track in .processed_files
su -c "echo '$filename' >> /sdcard/VisualAgent/.processed_files"

Alternative: Delete the file (less preferred — loses history)

# After processing, delete the file
su -c "rm /sdcard/VisualAgent/commands/$filename"

Note: Some environments block rm on /sdcard/ paths with approval mechanisms. Use mv to processed/ as the safer default.

The Stuck Agent Pattern

When the agent gets stuck re-processing the same command, the session log looks like this:

> su -c 'cat /sdcard/VisualAgent/commands/cmd.cmd'
# {"type":"screenshot","id":"test"}
> mcp_android_phone_screenshot(path="/sdcard/VisualAgent/results/screenshot_test.png")
# {"ok": true, "size_bytes": 1825667}

> su -c 'cat /sdcard/VisualAgent/commands/cmd.cmd'
# {"type":"screenshot","id":"test"}
> mcp_android_phone_screenshot(path="/sdcard/VisualAgent/results/screenshot_test.png")
# {"ok": true, "size_bytes": 1831773}

# ... 100+ identical repetitions ...

Key indicator: The same command file is read, the same command is executed, and the file is still in commands/ after each execution. This is NOT a polling anti-pattern (the agent isn't checking an empty directory) — it's a failure to archive the processed command.

Recovery: When You Notice You're Stuck

If you realize you've been re-processing the same command:

  1. Stop immediately — Do not execute the command again
  2. Archive the file — Move it to processed/: bash su -c "mkdir -p /sdcard/VisualAgent/processed/" su -c "mv /sdcard/VisualAgent/commands/cmd.cmd /sdcard/VisualAgent/processed/"
  3. Report the situation — In your final response, note that the command was processed multiple times due to the file not being archived
  4. Prevent future occurrences — Ensure your workflow always includes the archive step after execution

Summary

Problem Solution
Missing commands due to extension mismatch Check ALL files, not just *.json
Re-processing the same command Always move to processed/ after execution
Getting stuck in an infinite loop Check if file was already processed this session
rm blocked by approval Use mv to processed/ instead

Quick Checklist

  • [ ] Do I check ALL files in commands/, not just *.json?
  • [ ] Do I validate file content (JSON parseable, has type or command field)?
  • [ ] Do I move processed files to processed/ after execution?
  • [ ] Do I update .processed_files tracking?
  • [ ] Do I check if a file was already processed THIS session before re-executing?