@trevonistrevon/pi-loop 0.4.7 → 0.4.9

package/dist/index.js

@@ -183,6 +183,7 @@ export default function (pi) {
         if (nativeTaskStore) {
             nativeTaskStore.sweepCompleted();
             widget.update();
+            await cleanupTaskBacklogLoops();
         }
     }
     let agentRunning = false;
@@ -271,11 +272,13 @@ export default function (pi) {
         });
         return true;
     }
-    async function flushPendingNotifications() {
+    async function flushPendingNotifications(options) {
         if (flushPromise)
             return flushPromise;
         flushPromise = (async () => {
-            if (agentRunning || _latestCtx?.hasPendingMessages())
+            if (agentRunning)
+                return;
+            if (!options?.ignorePendingMessages && _latestCtx?.hasPendingMessages())
                 return;
             const entries = [...pendingNotifications.entries()]
                 .sort(([, left], [, right]) => left.timestamp - right.timestamp);
@@ -375,7 +378,8 @@ export default function (pi) {
         agentRunning = false;
         _latestCtx = ctx;
         widget.setUICtx(ctx.ui);
-        await flushPendingNotifications();
+        await flushPendingNotifications({ ignorePendingMessages: true });
+        await cleanupTaskBacklogLoops();
         await pumpLoops();
     });
     pi.on("session_shutdown", async () => {
@@ -466,6 +470,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
 - **prompt**: what to do when the loop fires (e.g., "check if the build passed")
 - **recurring**: repeat or fire once (default: true)
 - **autoTask**: when pi-tasks is loaded or native task fallback is active, auto-create a task on each fire
+- **taskBacklog**: mark this as a task-backlog worker loop so it auto-deletes when pending tasks reach zero
 - **readOnly**: restrict the agent to read-only tools when this loop fires (default: false)
 - **maxFires**: auto-stop after N fires — prevents infinite token burn on polling loops`,
         promptGuidelines: [
@@ -485,6 +490,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
             "## Task-driven workflows",
             "Do not rely on a past 'tasks:created' event to replay. If tasks already exist, bootstrap the first pass in the current turn or use a hybrid/event loop that can catch future task creation and a cron safety-net.",
             "Use autoTask only when you want the loop itself to create a task on each fire. For processing an existing task backlog, leave autoTask off and have the loop run TaskList to pick the next pending task.",
+            "Set taskBacklog: true for task-worker loops that process the existing pending queue. Task-backlog loops bootstrap against existing pending tasks and auto-delete when the queue reaches zero.",
             "When no tasks are pending, the loop should stop itself or skip the wake entirely — no tokens burned on empty polls.",
             "After creating a loop, tell the user the loop ID so they can cancel it with LoopDelete.",
         ],
@@ -493,13 +499,14 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
             prompt: Type.String({ description: "Prompt to run when the loop fires" }),
             recurring: Type.Optional(Type.Boolean({ description: "Whether loop repeats (default: true)", default: true })),
             autoTask: Type.Optional(Type.Boolean({ description: "Auto-create pi-tasks task on fire", default: false })),
+            taskBacklog: Type.Optional(Type.Boolean({ description: "Mark as a task-backlog worker loop that auto-deletes when pending tasks reach zero", default: false })),
             triggerType: Type.Optional(Type.String({ description: "cron, event, or hybrid (inferred from trigger string if omitted)", enum: ["cron", "event", "hybrid"] })),
             debounceMs: Type.Optional(Type.Number({ description: "Debounce for hybrid triggers (default: 30000)", default: 30000 })),
             readOnly: Type.Optional(Type.Boolean({ description: "Restrict the agent to read-only tools when this loop fires (default: false)", default: false })),
             maxFires: Type.Optional(Type.Number({ description: "Auto-stop after N fires. Prevents infinite token burn on polling loops." })),
         }),
         async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-            const { trigger: triggerInput, prompt, recurring, autoTask, triggerType, debounceMs, readOnly, maxFires } = params;
+            const { trigger: triggerInput, prompt, recurring, autoTask, taskBacklog, triggerType, debounceMs, readOnly, maxFires } = params;
             let trigger;
             const inferred = triggerType ?? inferTriggerType(triggerInput);
             if (inferred === "cron") {
@@ -526,6 +533,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
             const entry = store.create(trigger, prompt, {
                 recurring: recurring ?? (inferred !== "event"),
                 autoTask,
+                taskBacklog,
                 readOnly,
                 maxFires,
             });
@@ -556,6 +564,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
                 `Trigger: ${triggerDesc}\n` +
                 `Recurring: ${entry.recurring}\n` +
                 (entry.autoTask ? `Auto-task: enabled\n` : "") +
+                (entry.taskBacklog ? `Task-backlog: enabled\n` : "") +
                 (bootstrapped ? "Bootstrap: queued initial wake for existing pending tasks\n" : "") +
                 ((tasksAvailable || nativeTasksRegistered) ? "" : "(task system not ready yet — autoTask may not fire until native fallback or pi-tasks becomes available)\n") +
                 `ID: ${entry.id} (use LoopDelete to cancel)`));
@@ -928,10 +937,33 @@ Use MonitorList to find the monitor ID, then stop it with this tool.`,
     }
     const AUTO_TASK_WORKER_THRESHOLD = 5;
     const AUTO_TASK_WORKER_PROMPT = "Run TaskList, pick next pending task, mark it in_progress, implement it, run validation, complete it. If no pending tasks remain, call LoopDelete on your own loop ID.";
-    function findAutoTaskWorkerLoop() {
-        return store.list().find(entry => entry.status === "active"
+    function isAutoTaskWorkerLoop(entry) {
+        return entry.status === "active"
             && entry.prompt === AUTO_TASK_WORKER_PROMPT
-            && triggerHasEventSource(entry.trigger, "tasks:created"));
+            && triggerHasEventSource(entry.trigger, "tasks:created");
+    }
+    function isTaskBacklogLoop(entry) {
+        return entry.status === "active"
+            && triggerHasEventSource(entry.trigger, "tasks:created")
+            && (entry.taskBacklog === true || isAutoTaskWorkerLoop(entry));
+    }
+    function findAutoTaskWorkerLoop() {
+        return store.list().find(isAutoTaskWorkerLoop);
+    }
+    async function cleanupTaskBacklogLoops() {
+        const backlogLoops = store.list().filter(isTaskBacklogLoop);
+        if (backlogLoops.length === 0)
+            return 0;
+        const pending = await hasPendingTasks();
+        if (pending < 0 || pending > 0)
+            return 0;
+        for (const entry of backlogLoops) {
+            debug(`task backlog loop #${entry.id} — no pending tasks remain, deleting`);
+            triggerSystem.remove(entry.id);
+            store.delete(entry.id);
+        }
+        widget.update();
+        return backlogLoops.length;
     }
     async function ensureAutoTaskWorkerLoop(taskStore) {
         if (taskStore.pendingCount() < AUTO_TASK_WORKER_THRESHOLD)
@@ -947,6 +979,7 @@ Use MonitorList to find the monitor ID, then stop it with this tool.`,
         };
         const entry = store.create(trigger, AUTO_TASK_WORKER_PROMPT, {
             recurring: true,
+            taskBacklog: true,
             maxFires: 30,
         });
         triggerSystem.add(entry);
@@ -1035,6 +1068,7 @@ Use MonitorList to find the monitor ID, then stop it with this tool.`,
             ui.notify(`Task #${task.id} reopened`, "info");
         }
         widget.update();
+        await cleanupTaskBacklogLoops();
         return viewNativeTasks(ui);
     }
     // ── Native task tools (only when pi-tasks is absent) ──
@@ -1147,7 +1181,7 @@ Parameters: id (required), status, subject, description`,
                 subject: Type.Optional(Type.String({ description: "New title" })),
                 description: Type.Optional(Type.String({ description: "New description" })),
             }),
-            execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
                 const { id, status, subject, description } = params;
                 const entry = taskStore.update(id, {
                     status: status,
@@ -1157,6 +1191,7 @@ Parameters: id (required), status, subject, description`,
                 if (!entry)
                     return Promise.resolve(textResult(`Task #${id} not found`));
                 widget.update();
+                await cleanupTaskBacklogLoops();
                 const statusMsg = status ? ` → ${status}` : "";
                 return Promise.resolve(textResult(`Task #${id} updated${statusMsg}`));
             },
@@ -1168,11 +1203,13 @@ Parameters: id (required), status, subject, description`,
             parameters: Type.Object({
                 id: Type.String({ description: "Task ID to delete" }),
             }),
-            execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
                 const deleted = taskStore.delete(params.id);
                 widget.update();
-                if (deleted)
+                if (deleted) {
+                    await cleanupTaskBacklogLoops();
                     return Promise.resolve(textResult(`Task #${params.id} deleted`));
+                }
                 return Promise.resolve(textResult(`Task #${params.id} not found`));
             },
         });

package/dist/store.d.ts

@@ -11,6 +11,7 @@ export declare class LoopStore {
     create(trigger: Trigger, prompt: string, opts: {
         recurring: boolean;
         autoTask?: boolean;
+        taskBacklog?: boolean;
         readOnly?: boolean;
         maxFires?: number;
     }): LoopEntry;

package/dist/store.js

@@ -117,6 +117,7 @@ export class LoopStore {
                 status: "active",
                 recurring: opts.recurring,
                 autoTask: opts.autoTask,
+                taskBacklog: opts.taskBacklog,
                 readOnly: opts.readOnly,
                 maxFires: opts.maxFires,
                 fireCount: 0,

package/dist/types.d.ts

@@ -28,6 +28,7 @@ export interface LoopEntry {
     updatedAt: number;
     expiresAt: number;
     autoTask?: boolean;
+    taskBacklog?: boolean;
     readOnly?: boolean;
     maxFires?: number;
     fireCount?: number;

package/package.json

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

package/src/index.ts

@@ -196,6 +196,7 @@ export default function (pi: ExtensionAPI) {
     if (nativeTaskStore) {
       nativeTaskStore.sweepCompleted();
       widget.update();
+      await cleanupTaskBacklogLoops();
     }
   }
 
@@ -292,11 +293,12 @@ export default function (pi: ExtensionAPI) {
     return true;
   }
 
-  async function flushPendingNotifications(): Promise<void> {
+  async function flushPendingNotifications(options?: { ignorePendingMessages?: boolean }): Promise<void> {
     if (flushPromise) return flushPromise;
 
     flushPromise = (async () => {
-      if (agentRunning || _latestCtx?.hasPendingMessages()) return;
+      if (agentRunning) return;
+      if (!options?.ignorePendingMessages && _latestCtx?.hasPendingMessages()) return;
 
       const entries = [...pendingNotifications.entries()]
         .sort(([, left], [, right]) => left.timestamp - right.timestamp);
@@ -408,7 +410,8 @@ export default function (pi: ExtensionAPI) {
     agentRunning = false;
     _latestCtx = ctx;
     widget.setUICtx(ctx.ui);
-    await flushPendingNotifications();
+    await flushPendingNotifications({ ignorePendingMessages: true });
+    await cleanupTaskBacklogLoops();
     await pumpLoops();
   });
 
@@ -507,6 +510,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
 - **prompt**: what to do when the loop fires (e.g., "check if the build passed")
 - **recurring**: repeat or fire once (default: true)
 - **autoTask**: when pi-tasks is loaded or native task fallback is active, auto-create a task on each fire
+- **taskBacklog**: mark this as a task-backlog worker loop so it auto-deletes when pending tasks reach zero
 - **readOnly**: restrict the agent to read-only tools when this loop fires (default: false)
 - **maxFires**: auto-stop after N fires — prevents infinite token burn on polling loops`,
     promptGuidelines: [
@@ -526,6 +530,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
       "## Task-driven workflows",
       "Do not rely on a past 'tasks:created' event to replay. If tasks already exist, bootstrap the first pass in the current turn or use a hybrid/event loop that can catch future task creation and a cron safety-net.",
       "Use autoTask only when you want the loop itself to create a task on each fire. For processing an existing task backlog, leave autoTask off and have the loop run TaskList to pick the next pending task.",
+      "Set taskBacklog: true for task-worker loops that process the existing pending queue. Task-backlog loops bootstrap against existing pending tasks and auto-delete when the queue reaches zero.",
       "When no tasks are pending, the loop should stop itself or skip the wake entirely — no tokens burned on empty polls.",
       "After creating a loop, tell the user the loop ID so they can cancel it with LoopDelete.",
     ],
@@ -534,6 +539,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
       prompt: Type.String({ description: "Prompt to run when the loop fires" }),
       recurring: Type.Optional(Type.Boolean({ description: "Whether loop repeats (default: true)", default: true })),
       autoTask: Type.Optional(Type.Boolean({ description: "Auto-create pi-tasks task on fire", default: false })),
+      taskBacklog: Type.Optional(Type.Boolean({ description: "Mark as a task-backlog worker loop that auto-deletes when pending tasks reach zero", default: false })),
       triggerType: Type.Optional(Type.String({ description: "cron, event, or hybrid (inferred from trigger string if omitted)", enum: ["cron", "event", "hybrid"] })),
       debounceMs: Type.Optional(Type.Number({ description: "Debounce for hybrid triggers (default: 30000)", default: 30000 })),
       readOnly: Type.Optional(Type.Boolean({ description: "Restrict the agent to read-only tools when this loop fires (default: false)", default: false })),
@@ -541,7 +547,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
     }),
 
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-      const { trigger: triggerInput, prompt, recurring, autoTask, triggerType, debounceMs, readOnly, maxFires } = params;
+      const { trigger: triggerInput, prompt, recurring, autoTask, taskBacklog, triggerType, debounceMs, readOnly, maxFires } = params;
 
       let trigger: Trigger;
       const inferred = triggerType ?? inferTriggerType(triggerInput);
@@ -569,6 +575,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
       const entry = store.create(trigger, prompt, {
         recurring: recurring ?? (inferred !== "event"),
         autoTask,
+        taskBacklog,
         readOnly,
         maxFires,
       });
@@ -605,6 +612,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
         `Trigger: ${triggerDesc}\n` +
         `Recurring: ${entry.recurring}\n` +
         (entry.autoTask ? `Auto-task: enabled\n` : "") +
+        (entry.taskBacklog ? `Task-backlog: enabled\n` : "") +
         (bootstrapped ? "Bootstrap: queued initial wake for existing pending tasks\n" : "") +
         ((tasksAvailable || nativeTasksRegistered) ? "" : "(task system not ready yet — autoTask may not fire until native fallback or pi-tasks becomes available)\n") +
         `ID: ${entry.id} (use LoopDelete to cancel)`
@@ -1008,12 +1016,36 @@ Use MonitorList to find the monitor ID, then stop it with this tool.`,
   const AUTO_TASK_WORKER_THRESHOLD = 5;
   const AUTO_TASK_WORKER_PROMPT = "Run TaskList, pick next pending task, mark it in_progress, implement it, run validation, complete it. If no pending tasks remain, call LoopDelete on your own loop ID.";
 
-  function findAutoTaskWorkerLoop(): LoopEntry | undefined {
-    return store.list().find(entry =>
-      entry.status === "active"
+  function isAutoTaskWorkerLoop(entry: LoopEntry): boolean {
+    return entry.status === "active"
       && entry.prompt === AUTO_TASK_WORKER_PROMPT
+      && triggerHasEventSource(entry.trigger, "tasks:created");
+  }
+
+  function isTaskBacklogLoop(entry: LoopEntry): boolean {
+    return entry.status === "active"
       && triggerHasEventSource(entry.trigger, "tasks:created")
-    );
+      && (entry.taskBacklog === true || isAutoTaskWorkerLoop(entry));
+  }
+
+  function findAutoTaskWorkerLoop(): LoopEntry | undefined {
+    return store.list().find(isAutoTaskWorkerLoop);
+  }
+
+  async function cleanupTaskBacklogLoops(): Promise<number> {
+    const backlogLoops = store.list().filter(isTaskBacklogLoop);
+    if (backlogLoops.length === 0) return 0;
+
+    const pending = await hasPendingTasks();
+    if (pending < 0 || pending > 0) return 0;
+
+    for (const entry of backlogLoops) {
+      debug(`task backlog loop #${entry.id} — no pending tasks remain, deleting`);
+      triggerSystem.remove(entry.id);
+      store.delete(entry.id);
+    }
+    widget.update();
+    return backlogLoops.length;
   }
 
   async function ensureAutoTaskWorkerLoop(taskStore: TaskStore): Promise<{ entry?: LoopEntry; created: boolean }> {
@@ -1030,6 +1062,7 @@ Use MonitorList to find the monitor ID, then stop it with this tool.`,
     };
     const entry = store.create(trigger, AUTO_TASK_WORKER_PROMPT, {
       recurring: true,
+      taskBacklog: true,
       maxFires: 30,
     });
     triggerSystem.add(entry);
@@ -1119,6 +1152,7 @@ Use MonitorList to find the monitor ID, then stop it with this tool.`,
     }
 
     widget.update();
+    await cleanupTaskBacklogLoops();
     return viewNativeTasks(ui);
   }
 
@@ -1237,7 +1271,7 @@ Parameters: id (required), status, subject, description`,
         subject: Type.Optional(Type.String({ description: "New title" })),
         description: Type.Optional(Type.String({ description: "New description" })),
       }),
-      execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
         const { id, status, subject, description } = params;
         const entry = taskStore.update(id, {
           status: status as "pending" | "in_progress" | "completed" | undefined,
@@ -1246,6 +1280,7 @@ Parameters: id (required), status, subject, description`,
         });
         if (!entry) return Promise.resolve(textResult(`Task #${id} not found`));
         widget.update();
+        await cleanupTaskBacklogLoops();
         const statusMsg = status ? ` → ${status}` : "";
         return Promise.resolve(textResult(`Task #${id} updated${statusMsg}`));
       },
@@ -1258,10 +1293,13 @@ Parameters: id (required), status, subject, description`,
       parameters: Type.Object({
         id: Type.String({ description: "Task ID to delete" }),
       }),
-      execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
         const deleted = taskStore.delete(params.id);
         widget.update();
-        if (deleted) return Promise.resolve(textResult(`Task #${params.id} deleted`));
+        if (deleted) {
+          await cleanupTaskBacklogLoops();
+          return Promise.resolve(textResult(`Task #${params.id} deleted`));
+        }
         return Promise.resolve(textResult(`Task #${params.id} not found`));
       },
     });

package/src/store.ts

@@ -95,7 +95,7 @@ export class LoopStore {
     }
   }
 
-  create(trigger: Trigger, prompt: string, opts: { recurring: boolean; autoTask?: boolean; readOnly?: boolean; maxFires?: number }): LoopEntry {
+  create(trigger: Trigger, prompt: string, opts: { recurring: boolean; autoTask?: boolean; taskBacklog?: boolean; readOnly?: boolean; maxFires?: number }): LoopEntry {
     return this.withLock(() => {
       if (this.loops.size >= MAX_LOOPS) {
         throw new Error(`Maximum of ${MAX_LOOPS} loops reached. Delete some before creating new ones.`);
@@ -108,6 +108,7 @@ export class LoopStore {
         status: "active",
         recurring: opts.recurring,
         autoTask: opts.autoTask,
+        taskBacklog: opts.taskBacklog,
         readOnly: opts.readOnly,
         maxFires: opts.maxFires,
         fireCount: 0,

package/src/types.ts

@@ -30,6 +30,7 @@ export interface LoopEntry {
   updatedAt: number;
   expiresAt: number;
   autoTask?: boolean;
+  taskBacklog?: boolean;
   readOnly?: boolean;
   maxFires?: number;
   fireCount?: number;