@trevonistrevon/pi-loop 0.1.1 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.1.2]
+
+- Added `onDone` parameter to `MonitorCreate` — auto-creates a completion loop so the agent is notified when a background process finishes, no polling needed
+- Updated tool descriptions and prompt guidelines for the MonitorCreate + LoopCreate pairing
+
+
+
 ## [0.1.1]
 
 - Migrated peer dependencies from `@mariozechner/pi-*` to `@earendil-works/pi-*`

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-<h1 align="center">@pi-loop</h1>
+<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>
 
@@ -20,6 +20,7 @@ LoopDelete id="1"
 
 ```
 MonitorCreate command="tail -n0 -f build.log" description="Watch build"
+MonitorCreate command="python train.py" onDone="Analyze results and report best loss"
 MonitorList
 MonitorStop monitorId="1"
 ```
@@ -40,7 +41,7 @@ MonitorStop monitorId="1"
 | `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 |
+| `MonitorCreate` | Run a background command, stream output as `monitor:output` events. Use `onDone` for auto-notify on completion |
 | `MonitorList` | Show monitors with status, uptime, and output line count |
 | `MonitorStop` | Stop a monitor (SIGTERM → 5s → SIGKILL) |
 

package/benchmarks/experiment-sim.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Synthetic benchmark — mimics a research experiment with periodic progress output.
+ * Prints "iteration N/M, metric=0.XX" every 200ms for 30 iterations.
+ */
+
+const TOTAL = 30;
+const INTERVAL_MS = 200;
+
+let iteration = 0;
+
+const timer = setInterval(() => {
+  iteration++;
+  const metric = (Math.random() * 0.5 + 0.3).toFixed(4);
+  console.log(`iteration ${iteration}/${TOTAL}, loss=${metric}, timestamp=${Date.now()}`);
+
+  if (iteration >= TOTAL) {
+    console.log(`experiment complete: best loss=0.${Math.floor(Math.random() * 1000).toString().padStart(4, "0")}`);
+    clearInterval(timer);
+    process.exit(0);
+  }
+}, INTERVAL_MS);
+
+process.on("SIGTERM", () => {
+  console.log("experiment interrupted — saving checkpoint");
+  clearInterval(timer);
+  process.exit(0);
+});
+
+console.log("experiment starting: total_iterations=30, interval_ms=200");

package/dist/index.js

@@ -402,18 +402,35 @@ Use "pause" to temporarily stop a loop without removing it. Use "delete" to perm
     pi.registerTool({
         name: "MonitorCreate",
         label: "MonitorCreate",
-        description: `Start a background command and stream its output via pi events.
+        description: `Run a shell command in the background and get notified when it finishes. The core tool for async/parallel work.
 
-The monitor runs a shell command in the background. Each output line is emitted as a "monitor:output" pi event. Use this to watch logs, tail files, poll APIs, etc.
+Fire off a build check, CI monitor, experiment, script, or any slow command — then keep working. Output streams back as "monitor:output" events. When the process exits, "monitor:done" fires (or "monitor:error" on failure).
 
-Events emitted:
-- "monitor:output" — { monitorId, line, timestamp } for each output line
-- "monitor:done" — { monitorId, exitCode } on clean exit
-- "monitor:error" — { monitorId, error } on failure`,
+If you pass onDone with a prompt, the monitor auto-creates a one-shot completion loop — you get a system reminder with the exit code and output line count. No need to poll or create a separate loop.
+
+DO NOT use raw Bash while/sleep/for loops to watch something. DO NOT run slow commands inline that could be offloaded. Use MonitorCreate to run work in parallel while you continue.
+
+## When to Use
+
+Default to MonitorCreate for any long-running or background work:\n- Watch a CI/CD build (hut, gh, curl polling) while you work on something else\n- Run experiments, benchmarks, or training scripts in parallel\n- Tail a log or poll an API endpoint\n- Fire off a slow curl/fetch and check the result later\n- Run any script or command you don't need to wait on inline
+
+## Events emitted
+
+- "monitor:output" — { monitorId, line, timestamp } for each output line\n- "monitor:done" — { monitorId, exitCode, outputLines } on clean exit\n- "monitor:error" — { monitorId, error } on failure
+
+## onDone — auto-notify on completion
+
+Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fires when the process exits. The system reminder includes the exit code and output line count.\n\nExample: MonitorCreate command="python train.py" onDone="Check training results and report best loss"\nExample: MonitorCreate command="hut builds show 1769753" onDone="Analyze the build result and report status"`,
+        promptGuidelines: [
+            "Default to MonitorCreate for any long-running or background command — releases the agent to keep working on other tasks in parallel.",
+            "When the user asks to monitor CI builds, watch a build, check a remote job, or run an experiment, use MonitorCreate instead of inline bash/curl/wait.",
+            "Use onDone to auto-notify when a background command finishes — the agent will pick up the results automatically.",
+        ],
         parameters: Type.Object({
             command: Type.String({ description: "Shell command to run in background" }),
             description: Type.Optional(Type.String({ description: "Human-readable description" })),
             timeout: Type.Optional(Type.Number({ description: "Auto-stop after N ms (default: 300000, 0 = no timeout)", default: 300000 })),
+            onDone: Type.Optional(Type.String({ description: "Prompt to run when the monitor completes. Auto-creates a one-shot completion loop — no need for a separate LoopCreate." })),
         }),
         execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
             if (monitorManager.list().filter(m => m.status === "running").length >= 25) {
@@ -421,9 +438,16 @@ Events emitted:
             }
             const entry = monitorManager.create(params.command, params.description, params.timeout);
             widget.update();
+            let onDoneMsg = "";
+            if (params.onDone) {
+                const doneTrigger = { type: "event", source: "monitor:done", filter: JSON.stringify({ monitorId: entry.id }) };
+                const doneLoop = store.create(doneTrigger, params.onDone, { recurring: false });
+                triggerSystem.add(doneLoop);
+                onDoneMsg = `\nonDone loop #${doneLoop.id}: fires when monitor completes — no polling needed`;
+            }
             return Promise.resolve(textResult(`Monitor #${entry.id} started: ${entry.command.slice(0, 60)}\n` +
                 `Output stream: monitor:output (monitorId: ${entry.id})\n` +
-                `Timeout: ${params.timeout ? `${params.timeout / 1000}s` : "none"}`));
+                `Timeout: ${params.timeout ? `${params.timeout / 1000}s` : "none"}${onDoneMsg}`));
         },
     });
     // ──────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trevonistrevon/pi-loop",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "A pi extension for cron/event-based agent re-wake loops and background process monitoring.",
   "author": "trevonistrevon",
   "license": "MIT",

package/src/index.ts

@@ -439,18 +439,35 @@ Use "pause" to temporarily stop a loop without removing it. Use "delete" to perm
   pi.registerTool({
     name: "MonitorCreate",
     label: "MonitorCreate",
-    description: `Start a background command and stream its output via pi events.
+    description: `Run a shell command in the background and get notified when it finishes. The core tool for async/parallel work.
 
-The monitor runs a shell command in the background. Each output line is emitted as a "monitor:output" pi event. Use this to watch logs, tail files, poll APIs, etc.
+Fire off a build check, CI monitor, experiment, script, or any slow command — then keep working. Output streams back as "monitor:output" events. When the process exits, "monitor:done" fires (or "monitor:error" on failure).
 
-Events emitted:
-- "monitor:output" — { monitorId, line, timestamp } for each output line
-- "monitor:done" — { monitorId, exitCode } on clean exit
-- "monitor:error" — { monitorId, error } on failure`,
+If you pass onDone with a prompt, the monitor auto-creates a one-shot completion loop — you get a system reminder with the exit code and output line count. No need to poll or create a separate loop.
+
+DO NOT use raw Bash while/sleep/for loops to watch something. DO NOT run slow commands inline that could be offloaded. Use MonitorCreate to run work in parallel while you continue.
+
+## When to Use
+
+Default to MonitorCreate for any long-running or background work:\n- Watch a CI/CD build (hut, gh, curl polling) while you work on something else\n- Run experiments, benchmarks, or training scripts in parallel\n- Tail a log or poll an API endpoint\n- Fire off a slow curl/fetch and check the result later\n- Run any script or command you don't need to wait on inline
+
+## Events emitted
+
+- "monitor:output" — { monitorId, line, timestamp } for each output line\n- "monitor:done" — { monitorId, exitCode, outputLines } on clean exit\n- "monitor:error" — { monitorId, error } on failure
+
+## onDone — auto-notify on completion
+
+Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fires when the process exits. The system reminder includes the exit code and output line count.\n\nExample: MonitorCreate command="python train.py" onDone="Check training results and report best loss"\nExample: MonitorCreate command="hut builds show 1769753" onDone="Analyze the build result and report status"`,
+    promptGuidelines: [
+      "Default to MonitorCreate for any long-running or background command — releases the agent to keep working on other tasks in parallel.",
+      "When the user asks to monitor CI builds, watch a build, check a remote job, or run an experiment, use MonitorCreate instead of inline bash/curl/wait.",
+      "Use onDone to auto-notify when a background command finishes — the agent will pick up the results automatically.",
+    ],
     parameters: Type.Object({
       command: Type.String({ description: "Shell command to run in background" }),
       description: Type.Optional(Type.String({ description: "Human-readable description" })),
       timeout: Type.Optional(Type.Number({ description: "Auto-stop after N ms (default: 300000, 0 = no timeout)", default: 300000 })),
+      onDone: Type.Optional(Type.String({ description: "Prompt to run when the monitor completes. Auto-creates a one-shot completion loop — no need for a separate LoopCreate." })),
     }),
 
     execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
@@ -461,10 +478,18 @@ Events emitted:
       const entry = monitorManager.create(params.command, params.description, params.timeout);
       widget.update();
 
+      let onDoneMsg = "";
+      if (params.onDone) {
+        const doneTrigger: Trigger = { type: "event", source: "monitor:done", filter: JSON.stringify({ monitorId: entry.id }) };
+        const doneLoop = store.create(doneTrigger, params.onDone, { recurring: false });
+        triggerSystem.add(doneLoop);
+        onDoneMsg = `\nonDone loop #${doneLoop.id}: fires when monitor completes — no polling needed`;
+      }
+
       return Promise.resolve(textResult(
         `Monitor #${entry.id} started: ${entry.command.slice(0, 60)}\n` +
         `Output stream: monitor:output (monitorId: ${entry.id})\n` +
-        `Timeout: ${params.timeout ? `${params.timeout / 1000}s` : "none"}`
+        `Timeout: ${params.timeout ? `${params.timeout / 1000}s` : "none"}${onDoneMsg}`
       ));
     },
   });