d9284b7b75
- prod/docs/PI_WAKE_AGENT_TOOL.md: complete usage documentation - test_pi_wake_agent.py: 38 test cases
4.5 KiB
4.5 KiB
pi_wake_agent.py — Multi-Agent Wake Timer
Location: /mnt/dolphinng5_predict/pi_wake_agent.py
Branch: tools/pi_wake_agent
Status: v1.0 — 38 tests passing
Overview
Reusable multi-agent wake-up timer with self-cron/daemon/succession modes. Designed for the DOLPHIN fleet (pi_nvnemo, cmd, mimo, codex, etc.) to send doorbell injections via zellij and durable messages via h5i bus.
Installation
cd /mnt/dolphinng5_predict
python3 pi_wake_agent.py --install --interval 30m --session pi_test --msg "Wake up!"
Modes
| Mode | Flag | Description |
|---|---|---|
| Install cron | --install |
Recurring wake via system cron |
| One-shot | --once |
Single wake after interval (no cron) |
| Daemon | --daemon |
Long-lived process, no cron |
| Succession | --succession |
Run N times at interval, then self-clean |
| Run (internal) | --run |
Called by cron, executes wake |
| Remove | --remove |
Remove cron entry |
| List | --list |
Show active cron entries |
| Status | --status |
Show cron + one-shot timers |
| Validate | --validate |
Check zellij sessions exist |
Options
| Option | Description |
|---|---|
--interval DURATION |
Default: 1h. Formats: 30m, 1h, 90m, 2h, 10s |
--session SESSION |
Zellij session name (repeatable) |
--sessions "A,B,C" |
Comma-separated list |
--msg "MESSAGE" |
Wake message (default: "Operator says CONTINUE. Pi here!") |
--count N |
Number of runs for --succession |
--debug |
Enable debug logging |
--help |
Show help |
Examples
# Recurring 1-hour wake for one session
pi_wake_agent.py --install --interval 1h --session cc_UV_dev0_Fb
# Multi-session 30-minute wake
pi_wake_agent.py --install --interval 30m --sessions "cc_UV_dev0_Fb,cc_UV_dev1_48" --msg "Wake up!"
# One-shot in 2 hours
pi_wake_agent.py --once --interval 2h --session cc_UV_dev0_Fb --msg "Time's up!"
# Run 3 times at 1-hour intervals, then self-clean
pi_wake_agent.py --succession --count 3 --interval 1h --session cc_UV_dev0_Fb --msg "Scheduled wake"
# Daemon mode (long-lived, no cron)
pi_wake_agent.py --daemon --interval 1h --session cc_UV_dev0_Fb
# Remove timer
pi_wake_agent.py --remove --session cc_UV_dev0_Fb --interval 1h
# List / status
pi_wake_agent.py --list
pi_wake_agent.py --status
# Validate sessions exist
pi_wake_agent.py --validate --session cc_UV_dev0_Fb
Key Features
Non-Blocking h5i Bus
Messages sent to Fable via h5i msg send are fire-and-forget:
- Runs in background thread
- 5-second timeout
- Silently ignores failures
- Never blocks the wake cycle
Self-Cleaning Succession
pi_wake_agent.py --succession --count 3 --interval 1h --session S
Runs exactly 3 times at 1-hour intervals, then removes its own cron entry.
Multi-Session
# Repeatable --session
pi_wake_agent.py --install --interval 1h --session s1 --session s2
# Comma-separated --sessions
pi_wake_agent.py --install --interval 1h --sessions "s1,s2,s3"
Daemon Mode
Runs indefinitely as a long-lived process (no cron needed):
pi_wake_agent.py --daemon --interval 1h --session S
h5i Bus Protocol Compliance
Every wake injection:
- Identifies as
[pi_nvnemo via zellij] - Includes
Run: h5i-bus msg inboxdirective - Sends 5× ENTER keypresses (1s delay) for reliable submission
- Sends parallel h5i bus message for durability
Per AGENT_TERMINAL_DIRECT_INTERVENTION_PROCEDURES.md.
Testing
cd /mnt/dolphinng5_predict
python3 -m pytest test_pi_wake_agent.py -v
38 tests passing covering:
- Unit tests: interval parsing, cron comments, session parsing
- Integration: install/remove/list, one-shot, succession, run mode
- Edge cases: invalid intervals, missing sessions, invalid counts
Cron Entry Format
*/30 * * * * cd /mnt/dolphinng5_predict && export H5I_AGENT=pi_nvnemo && /mnt/dolphinng5_predict/pi_wake_agent.py --run --sessions 'pi_test' --msg '...' # pi_wake_agent:pi_test:30m
Comment format: pi_wake_agent:<sessions>:<interval>
Logs
- File:
/tmp/pi_wake_agent.log - Rotation: 10MB max, 5 files
- Format:
[YYYY-MM-DD HH:MM:SS] [LEVEL] message
Related Files
/mnt/dolphinng5_predict/pi_wake_agent.py— Main script/mnt/dolphinng5_predict/test_pi_wake_agent.py— Test suite (38 tests)/mnt/dolphinng5_predict/prod/docs/AGENT_TERMINAL_DIRECT_INTERVENTION_PROCEDURES.md— Protocol- Branch:
tools/pi_wake_agent