From d9284b7b755bc35f98578219979263076b854f2d Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 8 Jul 2026 14:21:18 +0200 Subject: [PATCH] docs/tools: pi_wake_agent tool documentation + test suite - prod/docs/PI_WAKE_AGENT_TOOL.md: complete usage documentation - test_pi_wake_agent.py: 38 test cases --- prod/docs/PI_WAKE_AGENT_TOOL.md | 165 ++++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 prod/docs/PI_WAKE_AGENT_TOOL.md diff --git a/prod/docs/PI_WAKE_AGENT_TOOL.md b/prod/docs/PI_WAKE_AGENT_TOOL.md new file mode 100644 index 00000000..8c540fcf --- /dev/null +++ b/prod/docs/PI_WAKE_AGENT_TOOL.md @@ -0,0 +1,165 @@ +# 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 + +```bash +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 + +```bash +# 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 +```bash +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 +```bash +# 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): +```bash +pi_wake_agent.py --daemon --interval 1h --session S +``` + +--- + +## h5i Bus Protocol Compliance + +Every wake injection: +1. Identifies as `[pi_nvnemo via zellij]` +2. Includes `Run: h5i-bus msg inbox` directive +3. Sends 5× ENTER keypresses (1s delay) for reliable submission +4. Sends parallel h5i bus message for durability + +Per [AGENT_TERMINAL_DIRECT_INTERVENTION_PROCEDURES.md](AGENT_TERMINAL_DIRECT_INTERVENTION_PROCEDURES.md). + +--- + +## Testing + +```bash +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::` + +--- + +## 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`