@trevonistrevon/pi-loop 0.6.0 → 0.6.2

package/dist/tools/loop-tools.js

@@ -1,4 +1,5 @@
 import { Type } from "typebox";
+import { formatTrigger } from "../loop-format.js";
 import { parseInterval } from "../loop-parse.js";
 import { textResult } from "./tool-result.js";
 function validateTrigger(trigger) {
@@ -40,6 +41,67 @@ function formatRemaining(ms) {
         return `${Math.round(ms / 60000)}m`;
     return `${Math.round(ms / 3600000)}h`;
 }
+function parseDelayMs(input) {
+    const match = input.trim().match(/^(\d+)\s*(s|m|h|d)$/i);
+    if (!match)
+        return undefined;
+    const value = Number.parseInt(match[1] ?? "", 10);
+    const unit = (match[2] ?? "").toLowerCase();
+    const multiplier = unit === "s" ? 1000 : unit === "m" ? 60000 : unit === "h" ? 3600000 : 86400000;
+    return value * multiplier;
+}
+function resolveNextWakeAt(nextInterval) {
+    if (!nextInterval)
+        return { nextWakeAt: undefined };
+    const parsedDelayMs = parseDelayMs(nextInterval);
+    if (!parsedDelayMs)
+        return { error: `Invalid nextInterval "${nextInterval}". Use formats like 3m, 30s, or 1h.` };
+    return { nextWakeAt: Date.now() + parsedDelayMs };
+}
+function formatDynamicUpdateResult(id, iteration, nextWakeAt) {
+    const mode = nextWakeAt === undefined
+        ? "Next wake: when idle"
+        : `Next wake: ${formatRemaining(Math.max(0, nextWakeAt - Date.now()))}`;
+    return `Dynamic loop #${id} updated\n` +
+        `Iteration: ${iteration ?? "?"}` +
+        `\n${mode}`;
+}
+function formatDeletionTombstone(id, tombstone) {
+    const detail = tombstone.pendingCount === undefined ? "" : ` (pending: ${tombstone.pendingCount})`;
+    return `Loop #${id} already auto-deleted: ${tombstone.reason}${detail}`;
+}
+function continueDynamicLoop(params, entry, store, triggerSystem) {
+    const { nextWakeAt, error } = resolveNextWakeAt(params.nextInterval);
+    if (error)
+        return error;
+    const updated = store.updateDynamic(params.id, {
+        prompt: params.prompt,
+        dynamic: {
+            goal: params.prompt ?? entry.dynamic.goal,
+            state: params.state,
+            metrics: params.metrics,
+            doneCriteria: params.doneCriteria,
+            iteration: (entry.dynamic.iteration ?? 0) + 1,
+            nextWakeAt,
+            awaitingUpdate: false,
+            lastUpdatedAt: Date.now(),
+        },
+    });
+    if (updated) {
+        triggerSystem.remove(params.id);
+        triggerSystem.add(updated);
+    }
+    return formatDynamicUpdateResult(params.id, updated?.dynamic?.iteration, nextWakeAt);
+}
+function stopDynamicLoop(params, store, triggerSystem) {
+    triggerSystem.remove(params.id);
+    if (params.status === "completed") {
+        store.delete(params.id);
+        return `Dynamic loop #${params.id} completed and deleted`;
+    }
+    store.pause(params.id);
+    return `Dynamic loop #${params.id} paused`;
+}
 export function registerLoopTools(options) {
     const { pi, getStore, getTriggerSystem, getScheduler, getMonitorManager, updateWidget, maybeBootstrapTaskLoop, isTaskSystemReady, } = options;
     pi.registerTool({
@@ -160,11 +222,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
             }
             const bootstrapped = await maybeBootstrapTaskLoop(entry);
             updateWidget();
-            const triggerDesc = trigger.type === "cron"
-                ? `schedule: ${trigger.schedule}`
-                : trigger.type === "event"
-                    ? `event: ${trigger.source}`
-                    : `hybrid: cron ${trigger.cron} + event ${trigger.event.source}`;
+            const triggerDesc = formatTrigger(trigger, "create");
             return Promise.resolve(textResult(`Loop #${entry.id} created: ${entry.prompt.slice(0, 60)}\n` +
                 `Trigger: ${triggerDesc}\n` +
                 `Recurring: ${entry.recurring}\n` +
@@ -188,12 +246,8 @@ Use this before creating new loops to avoid duplicates, or to find IDs for LoopD
                 return Promise.resolve(textResult("No loops configured. Use LoopCreate to set up a schedule."));
             const lines = [];
             for (const entry of loops) {
-                const triggerDesc = entry.trigger.type === "cron"
-                    ? `cron: ${entry.trigger.schedule}`
-                    : entry.trigger.type === "event"
-                        ? `event: ${entry.trigger.source}`
-                        : `hybrid: ${entry.trigger.cron} + ${entry.trigger.event.source}`;
-                const nextFire = entry.trigger.type !== "event" ? getScheduler().nextFire(entry.id) : undefined;
+                const triggerDesc = formatTrigger(entry.trigger, "list");
+                const nextFire = entry.trigger.type === "cron" || entry.trigger.type === "hybrid" || entry.dynamic?.nextWakeAt !== undefined ? getScheduler().nextFire(entry.id) : undefined;
                 const statusIcon = entry.status === "active" ? "*" : entry.status === "paused" ? "-" : "x";
                 let line = `${statusIcon} #${entry.id} [${entry.status}] ${entry.prompt.slice(0, 60)}`;
                 line += ` (${triggerDesc})`;
@@ -210,6 +264,37 @@ Use this before creating new loops to avoid duplicates, or to find IDs for LoopD
             return Promise.resolve(textResult(lines.join("\n")));
         },
     });
+    pi.registerTool({
+        name: "LoopUpdate",
+        label: "LoopUpdate",
+        description: `Update progress for a dynamic loop.
+
+Use this after a dynamic loop wake. Mark status as "continue" with updated state/metrics and optional nextInterval, "completed" when the goal is done, or "paused" to stop temporarily.`,
+        parameters: Type.Object({
+            id: Type.String({ description: "Dynamic loop ID to update" }),
+            status: Type.String({ description: "continue, completed, or paused", enum: ["continue", "completed", "paused"] }),
+            state: Type.Optional(Type.String({ description: "Current progress/state summary" })),
+            metrics: Type.Optional(Type.String({ description: "Current metrics/check results" })),
+            doneCriteria: Type.Optional(Type.String({ description: "Definition of done for the dynamic loop" })),
+            nextInterval: Type.Optional(Type.String({ description: "When to wake next, e.g. 3m, 30s, 1h" })),
+            prompt: Type.Optional(Type.String({ description: "Optional updated goal/prompt text" })),
+        }),
+        execute(_toolCallId, params) {
+            const store = getStore();
+            const triggerSystem = getTriggerSystem();
+            const entry = store.get(params.id);
+            if (!entry)
+                return Promise.resolve(textResult(`Loop #${params.id} not found`));
+            if (entry.trigger.type !== "dynamic" || !entry.dynamic) {
+                return Promise.resolve(textResult(`Loop #${params.id} is not a dynamic loop`));
+            }
+            const message = params.status === "continue"
+                ? continueDynamicLoop(params, entry, store, triggerSystem)
+                : stopDynamicLoop(params, store, triggerSystem);
+            updateWidget();
+            return Promise.resolve(textResult(message));
+        },
+    });
     pi.registerTool({
         name: "LoopDelete",
         label: "LoopDelete",
@@ -224,8 +309,12 @@ Use "pause" to temporarily stop a loop without removing it. Use "delete" to perm
             const { id, action } = params;
             if (action === "pause") {
                 const entry = getStore().pause(id);
-                if (!entry)
+                if (!entry) {
+                    const tombstone = getStore().getDeletionTombstone(id);
+                    if (tombstone)
+                        return Promise.resolve(textResult(formatDeletionTombstone(id, tombstone)));
                     return Promise.resolve(textResult(`Loop #${id} not found`));
+                }
                 getTriggerSystem().remove(id);
                 updateWidget();
                 return Promise.resolve(textResult(`Loop #${id} paused`));
@@ -235,6 +324,9 @@ Use "pause" to temporarily stop a loop without removing it. Use "delete" to perm
             updateWidget();
             if (deleted)
                 return Promise.resolve(textResult(`Loop #${id} deleted`));
+            const tombstone = getStore().getDeletionTombstone(id);
+            if (tombstone)
+                return Promise.resolve(textResult(formatDeletionTombstone(id, tombstone)));
             return Promise.resolve(textResult(`Loop #${id} not found`));
         },
     });

package/dist/tools/monitor-tools.js

@@ -30,7 +30,7 @@ Default to MonitorCreate for any long-running or background work:\n- Watch a CI/
 
 ## 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 completion wake 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"`,
+Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fires when the process exits, fails, or times out. The completion wake lets the agent inspect the final status and buffered output.\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.",

package/dist/trigger-system.js

@@ -28,7 +28,7 @@ export class TriggerSystem {
         this.hybridTimers.clear();
     }
     add(entry) {
-        if (entry.trigger.type === "cron" || entry.trigger.type === "hybrid") {
+        if (entry.trigger.type === "cron" || entry.trigger.type === "hybrid" || entry.trigger.type === "dynamic") {
             this.scheduler.add(entry);
         }
         if (entry.trigger.type === "event" || entry.trigger.type === "hybrid") {

package/dist/types.d.ts

@@ -1,3 +1,12 @@
+export type LoopDeletionReason = "task_backlog_empty";
+export interface LoopDeletionTombstone {
+    id: string;
+    reason: LoopDeletionReason;
+    deletedAt: number;
+    prompt: string;
+    pendingCount?: number;
+}
+export type LoopDeletionTombstoneInput = Omit<LoopDeletionTombstone, "id" | "deletedAt" | "prompt">;
 export type LoopStatus = "active" | "paused";
 export interface CronTrigger {
     type: "cron";
@@ -17,7 +26,20 @@ export interface HybridTrigger {
     };
     debounceMs: number;
 }
-export type Trigger = CronTrigger | EventTrigger | HybridTrigger;
+export interface DynamicTrigger {
+    type: "dynamic";
+}
+export type Trigger = CronTrigger | EventTrigger | HybridTrigger | DynamicTrigger;
+export interface DynamicLoopState {
+    goal: string;
+    state?: string;
+    metrics?: string;
+    doneCriteria?: string;
+    iteration: number;
+    nextWakeAt?: number;
+    awaitingUpdate?: boolean;
+    lastUpdatedAt?: number;
+}
 export interface LoopEntry {
     id: string;
     prompt: string;
@@ -32,6 +54,7 @@ export interface LoopEntry {
     readOnly?: boolean;
     maxFires?: number;
     fireCount?: number;
+    dynamic?: DynamicLoopState;
 }
 export interface LoopStoreData {
     nextId: number;

package/docs/USAGE_GUIDE.md

@@ -0,0 +1,185 @@
+# pi-loop usage guide
+
+`pi-loop` re-wakes a pi agent from schedules and events, runs self-paced goal loops, and monitors background commands. This guide covers the operational details; see the [README](../README.md) for installation and a quick start.
+
+## Loops
+
+### Scheduled loops
+
+Use `/loop <interval> <prompt>` or `LoopCreate`:
+
+```text
+/loop 5m check the deploy
+LoopCreate trigger="0 9 * * 1-5" prompt="Review weekday alerts" maxFires=10
+```
+
+Intervals such as `5m`, `2h`, and `1d` are converted to cron expressions. Full five-field cron expressions are also accepted. Cron and hybrid loops track their next fire time and deliver only when the agent is idle.
+
+Use `maxFires` for polling or other bounded work so a loop cannot run indefinitely. Recurring loops expire after seven days.
+
+### Event loops
+
+Event loops react to pi events instead of polling:
+
+```text
+/loop event tasks:created process the backlog
+LoopCreate trigger="tool_execution_end" prompt="Review the completed tool call" triggerType="event" recurring=true
+```
+
+`LoopCreate` event loops are one-shot by default. Set `recurring=true` to keep listening. Prefer events when a relevant source exists; use hybrid triggers when an event needs a scheduled safety net.
+
+### Hybrid loops
+
+A hybrid trigger combines cron and event delivery with a debounce window:
+
+```text
+LoopCreate trigger="cron:5m event:tasks:created" prompt="Process pending tasks" triggerType="hybrid" debounceMs=30000
+```
+
+### Dynamic goal loops
+
+Free text passed to `/loop` creates a self-paced dynamic goal:
+
+```text
+/loop finish the release
+```
+
+The first wake is immediate when the agent is idle. After each iteration, the agent calls `LoopUpdate`:
+
+```text
+LoopUpdate id="1" status="continue" state="Tests pass; reviewing package"
+LoopUpdate id="1" status="continue" nextInterval="3m"
+LoopUpdate id="1" status="paused" state="Waiting for credentials"
+LoopUpdate id="1" status="completed"
+```
+
+- `continue` saves progress and wakes again when idle.
+- `continue` with `nextInterval` schedules a timed wake.
+- `paused` preserves progress without firing.
+- `completed` finishes and deletes the loop.
+
+Paused dynamic loops can be resumed from the `/loop` menu. If an in-memory wake is lost during a restart or session switch, persisted dynamic state recovers it.
+
+### Inspecting and stopping loops
+
+```text
+LoopList
+LoopDelete id="1" action="pause"
+LoopDelete id="1" action="delete"
+```
+
+`LoopDelete` defaults to `action="delete"`.
+
+## Background monitors
+
+`MonitorCreate` runs a shell command without blocking the agent:
+
+```text
+MonitorCreate command="npm test" description="Run test suite" onDone="Inspect the result and fix failures"
+```
+
+Output is buffered and emitted as `monitor:output`. A monitor finishes as one of:
+
+- clean exit: emits `monitor:done`
+- nonzero exit or spawn failure: emits `monitor:error`
+- timeout: stops the process, emits `monitor:error`, and reports the timeout
+- explicit `MonitorStop`: cancels the monitor without an `onDone` wake
+
+Pass `onDone` whenever the agent should resume work after completion. Its one-shot wake fires on success, failure, or timeout. The default timeout is five minutes; use `timeout=0` to disable it.
+
+```text
+MonitorList
+MonitorStop monitorId="1"
+```
+
+`MonitorList` includes status, exit code when available, output count, and the last five buffered lines. Finished monitors remain briefly available before pruning.
+
+## Task integration
+
+### With pi-tasks
+
+When [@tintinweb/pi-tasks](https://github.com/tintinweb/pi-tasks) is available, `pi-loop` uses it over the task RPC channels. Set `autoTask=true` on `LoopCreate` to create a tracked task for each fire.
+
+### Native fallback
+
+If `pi-tasks` does not answer during startup detection, `pi-loop` registers:
+
+```text
+TaskCreate subject="Fix deploy polling" description="Replace polling with an event-driven loop"
+TaskList
+TaskUpdate id="1" status="in_progress"
+TaskUpdate id="1" status="completed"
+TaskDelete id="1"
+```
+
+The native provider is selected for the session and exposes `/tasks`, compact status-line tracking, persisted task state, lifecycle events, and task RPC replies.
+
+Set `taskBacklog=true` on a loop that processes existing pending tasks. Backlog workers bootstrap when tasks already exist and delete themselves when the queue drains. `autoTask` serves a different purpose: it creates a new task on each loop fire.
+
+## Events
+
+Monitor events:
+
+- `monitor:output`
+- `monitor:done`
+- `monitor:error`
+
+Native task lifecycle events:
+
+- `tasks:created`
+- `tasks:started`
+- `tasks:completed`
+- `tasks:reopened`
+- `tasks:updated`
+- `tasks:deleted`
+- `tasks:backlog_empty`
+- `loops:autodeleted`
+
+Task event payloads include `previousStatus`. Transition events report the status before the transition; details-only `tasks:updated` events report the status current at edit time.
+
+## Cross-extension task RPC
+
+External consumers should import only from `@trevonistrevon/pi-loop/api`; deep `src/` imports are blocked by the package export map.
+
+```ts
+import { TASKS_RPC, rpcCall } from "@trevonistrevon/pi-loop/api";
+
+const { id, task } = await rpcCall(pi.events, TASKS_RPC.create, {
+  subject: "Fix deploy polling",
+  description: "Replace polling with an event-driven loop",
+});
+```
+
+`rpcCall` rejects on failure or timeout. The native provider supports:
+
+| Channel | Request | Reply |
+|---|---|---|
+| `tasks:rpc:ping` | `{}` | `{ version, provider }` |
+| `tasks:rpc:pending` | `{}` | `{ pending }` |
+| `tasks:rpc:create` | `{ subject, description, metadata? }` | `{ id, task }` |
+| `tasks:rpc:clean` | `{}` | `{ pruned }` |
+| `tasks:rpc:update` | `{ id, status?, subject?, description? }` | `{ task }` |
+
+Requests include `requestId`; replies arrive on `<channel>:reply:<requestId>` as `{ success: true, data }` or `{ success: false, error }`.
+
+## Persistence and configuration
+
+| Variable | Effect | Default |
+|---|---|---|
+| `PI_LOOP` | Store path override; use `off` to disable persistence | derived from scope |
+| `PI_LOOP_SCOPE` | `memory`, `session`, or `project` | `session` |
+| `PI_LOOP_DEBUG` | Debug logging to stderr | unset |
+
+Scope behavior:
+
+- `session`: persists loops and tasks per session ID while isolating concurrent sessions and worktrees
+- `memory`: keeps all state ephemeral
+- `project`: shares persisted automation across sessions in the repository
+
+Session files live under `.pi/loops/` and `.pi/tasks/`. Keep `session` as the normal default; use `project` only when shared automation is intentional.
+
+## Status line and limits
+
+The TUI status line summarizes active loops, monitors, and native tasks. Use `LoopList`, `MonitorList`, and `/tasks` for detail. The status clears when no work is active.
+
+The runtime allows at most 25 active loops and 25 running monitors.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trevonistrevon/pi-loop",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "A pi extension for cron/event-based agent re-wake loops and background process monitoring.",
   "author": "trevonistrevon",
   "license": "MIT",
@@ -17,20 +17,29 @@
     "monitor",
     "scheduler"
   ],
+  "files": [
+    "src/",
+    "dist/",
+    "docs/USAGE_GUIDE.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "exports": {
     ".": "./src/index.ts",
     "./api": "./src/api.ts",
     "./package.json": "./package.json"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.75.5",
-    "@earendil-works/pi-tui": "^0.75.5"
+    "@earendil-works/pi-coding-agent": "^0.80.10",
+    "@earendil-works/pi-tui": "^0.80.10"
   },
   "dependencies": {
     "typebox": "^1.1.34"
   },
   "scripts": {
-    "build": "tsc",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc",
     "prepublishOnly": "npm run lint && npm run typecheck && npm run test && npm run build",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",