@trevonistrevon/pi-loop 0.1.0

package/AGENTS.md

@@ -0,0 +1,79 @@
+# pi-loop Development Guidelines
+
+## Overview
+`pi-loop` is a pi extension providing cron/event-based agent re-wake loops and background process monitoring. Modeled after Claude Code's `/loop`, `CronCreate`, and `MonitorCreate` tools.
+
+## Stack
+- TypeScript 6.x (strict, ES2022 target, bundler module resolution)
+- `typebox` for tool parameter validation
+- `vitest` for tests
+- `biome` for linting (linter: on, formatter: off)
+- npm packaging as `@trevonistrevon/pi-loop`
+
+## Architecture
+```
+src/
+├── index.ts              # Extension entry: 6 tools + /loop /loops commands + widget
+├── types.ts              # LoopKind, Trigger spec, LoopEntry, MonitorEntry, LoopConfig
+├── store.ts              # File-backed CRUD (.pi/loops/loops.json) with file locking
+├── scheduler.ts          # Timer-based cron scheduler with jitter + 7-day expiry
+├── trigger-system.ts     # Unified trigger engine: cron timers + pi event subscriptions + hybrid
+├── monitor-manager.ts    # ChildProcess tracking, output buffering, event emission, stop
+├── loop-parse.ts         # Human interval → cron expression, next-fire computation, jitter
+└── ui/
+    └── widget.ts         # Persistent widget: active loops + monitors
+```
+
+## Conventions (mirror pi-tasks)
+- No comments unless answering "why", never "what"
+- `debug(...)` helper gated on `PI_LOOP_DEBUG` env var, logs to stderr
+- `textResult(msg)` helper for uniform tool output
+- All tool params use `Type.Object()` with description strings
+- Tool descriptions follow Claude Code format: `## When to Use`, `## When NOT to Use`
+- Cross-extension communication via `pi.events` with `requestId` + reply channels
+- File-backed stores use atomic write (write tmp → rename) + pid-based file locking
+- Widget uses `UICtx.setWidget()` with `render()` callback pattern
+- Tests co-located in `test/`, named `<module>.test.ts`
+
+## File Locking Pattern
+Copy TaskStore from pi-tasks: `O_EXCL` lockfile, stale PID detection, `LOCK_RETRY_MS`/`LOCK_MAX_RETRIES`
+
+## Trigger Types
+Three trigger types, all stored as `LoopEntry.trigger`:
+- `{ type: "cron", schedule: "*/5 * * * *" }` — timer-based
+- `{ type: "event", source: "tool_execution_start", filter?: "regex:..." | '{"key":"value"}' }` — eventbus-based
+- `{ type: "hybrid", cron: "...", event: { source, filter? }, debounceMs: 30000 }` — both with debounce
+
+## Re-wake via System Reminder
+When a loop fires, the scheduler calls `onLoopFire()` which emits `pi.events("loop:fire", ...)`. The extension's listener queues a reminder. On the next `tool_result` event, the reminder is injected as `<system-reminder>` text (mirroring pi-tasks' pattern):
+```
+<system-reminder>
+Scheduled loop "deploy check" fired. Trigger: schedule: */5 * * * *.
+[loop:abc12345]
+</system-reminder>
+```
+
+## Monitor Streaming via PI Events
+Monitor stdout/stderr lines are emitted as `pi.events("monitor:output", { monitorId, line, timestamp })`. Tool consumers subscribe to these events. Completion emits `"monitor:done"` / `"monitor:error"`.
+
+## pi-tasks Integration
+When `@tintinweb/pi-tasks` is present, `LoopCreate` with `autoTask: true` fires an RPC to create a task. Communication via `pi.events`:
+- `tasks:rpc:ping` on init → detect pi-tasks presence
+- `tasks:ready` listener → late-binding detection
+- `tasks:rpc:create` → auto-create task when loop fires (if `autoTask: true`)
+
+## /loop Self-Paced Mode
+When no interval is specified in `/loop prompt`, the loop runs in self-paced mode. The agent receives the prompt, acts on it, and uses `LoopCreate`/`LoopUpdate` to schedule the next iteration. The loop fires once, then the agent decides the next interval dynamically (matching Claude Code's dynamic interval behavior).
+
+## Testing
+- `vitest` with `describe`/`it` blocks
+- In-memory stores for unit tests, `tmpdir` for file-backed tests
+- Fake timers (`vi.useFakeTimers`) for scheduler tests
+- Mock pi eventbus for monitor-manager tests
+- `vitest run` in CI, `vitest` for watch mode
+
+## Limits
+- Maximum 25 active loops
+- Maximum 25 running monitors
+- 7-day expiry on recurring loops
+- 5-minute default cron interval for self-paced mode

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## [0.1.0] — Initial Release
+
+### Tools
+
+- **LoopCreate** — Create scheduled (cron), event-triggered, or hybrid re-wake loops
+- **LoopList** — List all active loops with IDs, triggers, status, and next-fire times
+- **LoopDelete** — Delete or pause a loop by ID
+- **MonitorCreate** — Start a background command that streams output via `monitor:output` pi events
+- **MonitorList** — List monitoring processes and their status
+- **MonitorStop** — Stop a running monitor (SIGTERM → 5s → SIGKILL)
+
+### Commands
+
+- **`/loop [interval] [prompt]`** — Interactive TUI loop creation
+- **`/loops`** — View, create, cancel, and configure loops
+
+### Features
+
+- Three trigger types: cron (timer), event (eventbus), hybrid (both with debounce)
+- File-backed persistence with pid-based file locking and atomic writes
+- Cron scheduler with per-loop jitter and 7-day expiry
+- Background process monitoring with stdout/stderr streaming
+- Persistent TUI widget showing active loops and monitors
+- System-reminder injection for loop fires (mirrors pi-tasks pattern)
+- Self-paced loop mode for dynamic interval scheduling
+- `@tintinweb/pi-tasks` integration with auto-task creation
+
+### Configuration
+
+- `PI_LOOP` env var for store path override / disable
+- `PI_LOOP_SCOPE` env var for `memory` | `session` | `project`
+- `PI_LOOP_DEBUG` env var for debug logging
+
+### Limits
+
+- Maximum 25 active loops
+- Maximum 25 running monitors

package/CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing to @trevonistrevon/pi-loop
+
+Thanks for contributing! This document covers local dev setup, conventions, and workflow.
+
+## Getting Started
+
+```bash
+git clone https://github.com/trevonistrevon/pi-loop.git
+cd pi-loop
+npm install
+```
+
+## Scripts
+
+| Command | Description |
+|---|---|
+| `npm run typecheck` | TypeScript type checking (`tsc --noEmit`) |
+| `npm run lint` | Lint with Biome |
+| `npm run lint:fix` | Auto-fix lint issues |
+| `npm test` | Run tests (`vitest run`) |
+| `npm run test:watch` | Watch mode |
+| `npm run build` | Compile TypeScript |
+
+## Architecture
+
+See `AGENTS.md` for the full architecture overview. Key modules:
+
+- **`src/index.ts`** — Extension entry: registers 6 tools + `/loop` `/loops` commands + widget lifecycle
+- **`src/types.ts`** — Core types: `LoopEntry`, `MonitorEntry`, `Trigger` variants
+- **`src/store.ts`** — File-backed CRUD with pid-based file locking (atomic write → rename)
+- **`src/scheduler.ts`** — Timer-based cron scheduler with per-loop jitter and 7-day expiry
+- **`src/trigger-system.ts`** — Unified engine: cron timers + pi event subscriptions + hybrid debounce
+- **`src/monitor-manager.ts`** — `ChildProcess` wrapper: stdout/stderr streaming as pi events
+- **`src/loop-parse.ts`** — Human interval parsing (`5m` → cron), cron matching, next-fire computation
+- **`src/ui/widget.ts`** — TUI widget rendering active loops + monitors above the editor
+
+## Conventions
+
+- **TypeScript 6.x** strict mode, ES2022 target, bundler module resolution
+- **No comments unless answering "why"** — never "what"
+- **`debug(...)`** helper gated on `PI_LOOP_DEBUG` env var, logs to stderr
+- **`textResult(msg)`** helper for uniform tool output strings
+- **Tool params** use `Type.Object()` with description strings from `typebox`
+- **File-backed stores** use atomic write (write tmp → rename) + pid-based file locking
+
+## Testing
+
+Tests are co-located in `test/` as `<module>.test.ts`. The suite uses:
+
+- **vitest** with `describe`/`it`
+- In-memory stores for unit tests
+- `tmpdir` for file-backed store tests
+- `vi.useFakeTimers()` for scheduler tests
+- Mocked pi eventbus for monitor-manager tests
+
+```bash
+npm test            # Run once
+npm run test:watch  # Watch mode
+```
+
+## Pull Request Workflow
+
+1. Fork, branch, implement
+2. Ensure `npm run typecheck`, `npm run lint`, and `npm test` all pass
+3. Open PR against `main`
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 trevonistrevon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+<p align="center">
+<h1 align="center">@trevonistrevon/pi-loop</h1>
+<h6 align="center">Cron and event loops for the pi coding agent. Background monitors, scheduled re-wakes, pi-tasks integration.</h6>
+</p>
+
+## Install
+
+```bash
+pi install @trevonistrevon/pi-loop
+```
+
+## Quick start
+
+```
+LoopCreate trigger="5m" prompt="Check if the build passed"
+LoopCreate trigger="tool_execution_start" prompt="Log the tool being used" triggerType="event"
+LoopList
+LoopDelete id="1"
+```
+
+```
+MonitorCreate command="tail -n0 -f build.log" description="Watch build"
+MonitorList
+MonitorStop monitorId="1"
+```
+
+## Commands
+
+`/loop [interval] [prompt]` — interactive loop creation.
+
+```
+/loop                         # menu
+/loop 5m check the deploy     # 5-minute cron loop
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `LoopCreate` | Schedule a prompt on a cron timer, a pi event, or both with debounce |
+| `LoopList` | Show active loops with IDs, triggers, and next-fire times |
+| `LoopDelete` | Delete or pause a loop |
+| `MonitorCreate` | Run a background command, stream output as `monitor:output` events |
+| `MonitorList` | Show monitors with status, uptime, and output line count |
+| `MonitorStop` | Stop a monitor (SIGTERM → 5s → SIGKILL) |
+
+Trigger types: `cron` (`5m`, `1h`, `0 9 * * 1-5`), `event` (any pi event source), or `hybrid` (both, debounced).
+
+## pi-tasks
+
+Works with [@tintinweb/pi-tasks](https://github.com/tintinweb/pi-tasks). Pass `autoTask: true` on `LoopCreate` and each loop fire auto-creates a tracked task. Detection happens over pi's event bus — no manual wiring.
+
+## Widget
+
+Active loops and monitors show in a persistent TUI widget above the editor.
+
+## Configuration
+
+| Variable | Effect | Default |
+|---|---|---|
+| `PI_LOOP` | Store path. `off` to disable, absolute or project-relative path | `.pi/loops/loops.json` |
+| `PI_LOOP_SCOPE` | `memory` (ephemeral), `session` (per-session file), `project` (shared) | `session` |
+| `PI_LOOP_DEBUG` | Debug logging to stderr | unset |
+
+## Limits
+
+25 active loops, 25 running monitors. Recurring loops expire after 7 days.
+
+## Development
+
+```bash
+npm run typecheck
+npm run lint
+npm test
+npm run build
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+MIT — [LICENSE](./LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @trevonistrevon/pi-loop — A pi extension providing cron/event-based agent re-wake loops and background process monitoring.
+ *
+ * Tools:
+ *   LoopCreate    — Create a scheduled or event-triggered re-wake loop
+ *   LoopList      — List all active loops with status and next-fire times
+ *   LoopDelete    — Delete or pause a loop by ID
+ *   MonitorCreate — Start a background command that streams output via pi events
+ *   MonitorList   — List running monitors
+ *   MonitorStop   — Stop a running monitor
+ *
+ * Commands:
+ *   /loop    — Schedule a re-wake loop: /loop [interval] [prompt]
+ *   /loops   — Interactive menu: view, create, cancel, settings
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+export default function (pi: ExtensionAPI): void;