@agimon-ai/doompi-loop 0.0.1-alpha.21 → 0.0.1-alpha.22

package/README.md

@@ -1,44 +1,59 @@
 # @agimon-ai/doompi-loop
 
-**Run it now. Run it again later.**
+A session-scoped scheduler that sends a prompt immediately and repeats it at a bounded interval.
 
-This package runs a prompt immediately, then repeats it on a schedule. Several loops can
-live in one Pi session, each with its own prompt and interval. Loop is a minor mode: it
-turns on when work is scheduled, stacks with the other modes, and reports itself on the
-shared `MODES` line.
+Several loops can coexist. Loop is a minor mode and remains active while at least one scheduled prompt belongs to the current session.
 
-The built-in Default loop asks for a prompt and interval. Other extensions can register
-their own launchers beside it, so a domain can add a recurring job without forking the
-scheduler.
+> **Alpha:** launcher and scheduling contracts may change between releases.
 
-This is part of [Doompi](https://www.npmjs.com/package/@agimon-ai/doompi). Most users get
-it with the distribution.
+## Requirements
+
+- Node.js 22.19.0 or newer
+- Pi 0.84.2 and Pi TUI 0.84.2
 
 ## Install
 
+DoomPi loads Loop as core. For standalone Pi:
+
 ```bash
-npm install @agimon-ai/doompi-loop
+pi install npm:@agimon-ai/doompi-loop
 ```
 
-## How it loads
+## Start and manage loops
+
+Use `/loop` to start a loop and `/loops` to inspect or stop active loops. In DoomPi, `SPC l s` opens the start flow and `SPC l l` opens the list.
+
+The default interval is 300 seconds. Accepted intervals range from 30 to 3600 seconds. A loop runs its prompt once immediately, then schedules later passes.
+
+If Pi is busy, a due pass waits for the shared agent to become idle. Multiple due signals can coalesce rather than creating overlapping model turns. Stopping a loop prevents future passes but does not rewind side effects from a pass already sent.
 
-Doompi loads Loop as core. It is not a major-mode layer and does not appear in
-`.doom/modes.yaml`. The bare package name follows its Pi manifest and loads the Pi adapter.
+## Lifecycle and cost
 
-## Leader
+Loop state is held in session memory; it is not a durable queue. Session replacement or shutdown stops the timers. A resumed transcript does not imply that old loops restart.
 
-- `SPC l s` starts a loop.
-- `SPC l l` lists active loops and lets you stop one.
+Every pass can start another model turn and repeat tool or external side effects. Choose conservative intervals, make prompts idempotent where possible, and stop loops when the recurring work is complete.
 
-Use Loop for recurring checks or prompts that belong to the current session. Use several
-when the schedules are independent; there is no single-loop lock.
+## Public API
 
-## Entry points
+```ts
+import {
+  createDefaultLoopLauncher,
+  createLoopLauncherClient,
+  registerLoopExtension,
+  registerLoopLauncher,
+} from '@agimon-ai/doompi-loop';
+```
+
+Other extensions can register a launcher alongside the default prompt launcher without forking the scheduler.
+
+## Development
 
-| Import                                 | Purpose                  |
-| -------------------------------------- | ------------------------ |
-| `@agimon-ai/doompi-loop`               | Library API              |
-| `@agimon-ai/doompi-loop/extensions/pi` | Pi extension entry point |
+```bash
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm lint
+```
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agimon-ai/doompi-loop",
-  "version": "0.0.1-alpha.21",
+  "version": "0.0.1-alpha.22",
   "description": "Generic multi-loop controller for Doompi",
   "keywords": [
     "ai",
@@ -37,8 +37,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@agimon-ai/doompi-extension-contracts": "0.0.1-alpha.21",
-    "@agimon-ai/doompi-ui": "0.0.1-alpha.21"
+    "@agimon-ai/doompi-extension-contracts": "0.0.1-alpha.22",
+    "@agimon-ai/doompi-ui": "0.0.1-alpha.22"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.84.2",