agent-builder/scripts/templates/cron/README.md

Cron Execution Templates

Two execution types for scheduled agent work, inspired by OpenClaw's cron service.

agentTurn (agent-turn.sh)

Full background autonomy. Creates/resumes its own named session.

Use for:

• Complex multi-step work
• Tasks that need full context and tool access
• Background autonomous operation (proactive agent cycles)

Features:

• Named sessions via --name for resume capability
• Orphan detection (checks PID before starting new run)
• Session rollover: fresh session after 200 turns or 72 hours
• Context loading from SESSION-STATE.md and HEARTBEAT.md
• Dated log files per agent per day

Session naming (VERIFIED): Uses --name "agent:<name>:turn" with --resume for continuity. Note: --session-id requires valid UUIDs. Named sessions are the correct approach for human-readable, resumable agent sessions.

systemEvent (system-event.sh)

Injects text into an existing session. No new session created.

Use for:

• Notifications ("new data available")
• Simple status checks
• Triggering a specific action in a running session

Limitations:

• Requires an active named session to resume
• Limited to 3 turns (quick action, not full autonomy)
• If the session doesn't exist, the command fails gracefully

Scheduling examples

# agentTurn: run full agent turn every hour
0 * * * * /path/to/agent-turn.sh >> /tmp/agent-turn.log 2>&1

# systemEvent: notify agent of new data every 30 min
*/30 * * * * /path/to/system-event.sh "agent:processor:turn" "Check /data/inbox for new files"

# agentTurn with catchup on reboot
@reboot /path/to/agent-turn.sh >> /tmp/agent-turn.log 2>&1