# 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

```bash
# 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

```bash
# 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

```bash
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

```bash
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

```bash
# 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