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
This commit is contained in:
Codex
165
prod/docs/PI_WAKE_AGENT_TOOL.md
Normal file
165
prod/docs/PI_WAKE_AGENT_TOOL.md
Normal file
@@ -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:<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`
|
||||
Reference in New Issue
Block a user