Cron VisualAgent: Empty Directory → [SILENT] Pattern
Context
When running as a VisualAgent cron job, the agent polls /sdcard/VisualAgent/commands/ for JSON command files. If the directory is empty or contains only non-JSON files (e.g., .dat, .txt), there is nothing to execute.
The Correct Response
Respond with exactly [SILENT] and nothing else. This suppresses delivery and avoids spamming the user with empty reports.
Incorrect: Reporting "No commands found" with a full status report.
Correct: [SILENT]
Discovery Pattern
Use find to check for JSON files (cron-safe, works with su):
su -c 'find /sdcard/VisualAgent/commands/ -name "*.json" -type f 2>/dev/null'
- Empty output → no commands →
[SILENT] - Non-empty output → process commands → report results
Why find is Preferred Over ls
- Returns empty string when no matches — easy to detect
- Handles filenames with spaces — no word splitting issues
- Runs in
sucontext — no glob expansion in parent shell - Filters by extension — ignores
.dat,.txt,.logfiles that may be present
Real-World Example
# Check for commands
su -c 'find /sdcard/VisualAgent/commands/ -name "*.json" -type f 2>/dev/null'
# → "" (empty output)
# Check what files ARE present (for debugging, optional)
su -c 'ls -la /sdcard/VisualAgent/commands/'
# → myfile.dat, test.txt
# Response: [SILENT]
Common Non-JSON Files in Commands Directory
.processed_files— tracking file listing processed command IDs.datfiles — binary or metadata files from other tools.txtfiles — log files or notes.logfiles — service logs- No extension — raw command files from some clients
All of these should be ignored by the JSON filter. Only files ending in .json are valid command files in the standard VisualAgent protocol.
Cross-Referencing When Commands Directory Appears Empty
Sometimes the commands directory has no .json files, but you should verify whether this is truly "nothing new" or a state mismatch. Check these in order:
.processed_filestracking file — lists files already processed:su -c 'cat /sdcard/VisualAgent/.processed_files 2>/dev/null || echo "NO_TRACKING_FILE"'processed/directory — files moved here after execution:su -c 'ls /sdcard/VisualAgent/processed/ 2>/dev/null || echo "NO_PROCESSED_DIR"'results/directory — result files from previous runs:su -c 'ls /sdcard/VisualAgent/results/ 2>/dev/null | head -5'
If the commands directory has no .json files AND .processed_files shows previous commands AND processed/ contains those same files → this is a genuine empty state → [SILENT].
If the commands directory has no .json files BUT .processed_files is empty AND processed/ is empty → this may be a fresh install or a reset → still [SILENT], but note the state in memory for future reference.
Health Check vs. [SILENT]
A health check screenshot is useful when:
- This is the FIRST run (no history in
.processed_filesorprocessed/) - The user explicitly asked for a status check
- There are ERROR indicators in the service (missing directories, permission errors, repeated failures in results)
A health check is NOT needed when:
- The service has been running successfully (history in
processed/and results) - The commands directory is simply empty (normal operational state)
- The previous run was also
[SILENT](steady state) - The daemon PID is stale but the service has clear operational history — see below
Stale Daemon PID ≠ Unhealthy Service
A common trap: discovering that the daemon PID file points to a dead process, then taking a health check screenshot "to verify the service is working." This is unnecessary if:
processed/contains many files (shows commands were executed)results/contains result files (shows execution produced output).processed_fileshas entries (shows tracking was working)daemon.logshows recent activity (shows the service was alive recently)
Example from real session:
daemon.pid: 1093 (process not found)
processed/: 30+ command files
results/: 40+ result files
.processed_files: exists with entries
daemon.log: shows commands processed minutes ago
In this case, the daemon died but the service infrastructure is clearly functional. The cron job can still process commands directly via MCP tools or shell commands. A health check screenshot adds no information — the historical data IS the evidence.
Correct response: After confirming commands/ is empty and cross-referencing state, respond [SILENT] immediately. The stale PID is a daemon lifecycle issue (see references/visual-agent-daemon-lifecycle.md), not a service health issue.
Incorrect response: Taking a screenshot, checking the UI tree, or writing a verbose status report about the dead daemon. These waste tool calls and produce unnecessary delivery noise.
Rule of thumb: If everything looks normal and there's just no work to do, [SILENT]. Only perform a health check if there's a specific reason to suspect the service is unhealthy.
Pitfall: Don't Over-Check
Once you've confirmed the directory is empty of JSON files and cross-referenced state, respond [SILENT] immediately. Do NOT:
- Check the directory multiple times in the same run
- Read non-JSON files looking for hidden commands
- Create test files to verify the system works
- Write a "heartbeat" result file
- Perform a health check screenshot "just in case"
Each unnecessary tool call wastes an iteration and may eventually hit the max iteration limit. See references/cron-polling-anti-patterns.md for details.