d9284b7b75
- prod/docs/PI_WAKE_AGENT_TOOL.md: complete usage documentation - test_pi_wake_agent.py: 38 test cases
166 lines
4.5 KiB
Markdown
166 lines
4.5 KiB
Markdown
# 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:<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`
|