@trevonistrevon/pi-loop 0.4.1 → 0.4.3

package/AGENTS.md

@@ -32,9 +32,15 @@ src/
 - 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
+- Runtime tracker UI uses `UICtx.setStatus()` for compact single-line state
 - Tests co-located in `test/`, named `<module>.test.ts`
 
+## Tool Schema Discipline
+- Tool calls must use the exact schema field names from the tool definition. Do not invent aliases.
+- Example: `TaskUpdate` uses `id`, not `taskId`.
+- When a tool validation error clearly indicates an immediately recoverable schema mismatch, correct it silently and retry. Do not emit user-facing chatter like "retrying with the correct shape" unless the recovery itself changes the user's understanding.
+- When adding or revising tool prompt guidance, include concrete parameter-name reminders for commonly miscalled tools.
+
 ## File Locking Pattern
 Copy TaskStore from pi-tasks: `O_EXCL` lockfile, stale PID detection, `LOCK_RETRY_MS`/`LOCK_MAX_RETRIES`
 
@@ -44,14 +50,8 @@ Three trigger types, all stored as `LoopEntry.trigger`:
 - `{ 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>
-```
+## Re-wake via In-Memory Pending Notifications
+When a loop fires, the scheduler calls `onLoopFire()` which emits `pi.events("loop:fire", ...)`. The extension buffers a pending notification in memory, re-checks whether the wake is still relevant, and only then injects a `pi.sendMessage()` custom message to wake the agent. Do not rely on early queued follow-up user messages for loop delivery; those are not extension-cancelable once handed to pi's queue.
 
 ## 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"`.

package/dist/index.js

@@ -209,6 +209,35 @@ export default function (pi) {
             message: buildLoopFireMessage(data),
         };
     }
+    function triggerHasEventSource(trigger, source) {
+        if (typeof trigger === "string")
+            return false;
+        return trigger.type === "event"
+            ? trigger.source === source
+            : trigger.type === "hybrid"
+                ? trigger.event.source === source
+                : false;
+    }
+    async function maybeBootstrapTaskLoop(entry) {
+        if (!entry.recurring)
+            return false;
+        if (!triggerHasEventSource(entry.trigger, "tasks:created"))
+            return false;
+        const pending = await hasPendingTasks();
+        if (pending <= 0)
+            return false;
+        debug(`loop #${entry.id} — bootstrapping existing pending tasks (${pending})`);
+        await queueOrDeliverNotification({
+            loopId: entry.id,
+            prompt: entry.prompt,
+            trigger: entry.trigger,
+            timestamp: Date.now(),
+            readOnly: entry.readOnly,
+            recurring: false,
+            autoTask: true,
+        });
+        return true;
+    }
     async function deliverNotification(notification) {
         if (notification.autoTask) {
             const pending = await hasPendingTasks();
@@ -425,8 +454,9 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
             "## readOnly mode",
             "Set readOnly: true for loops that only observe and report (checks, status polls). This prevents unintended changes.",
             "## Task-driven workflows",
-            "After creating tasks with TaskCreate, use an event loop with autoTask: true so the system checks for pending tasks before firing: LoopCreate trigger='tasks:created' triggerType='event' autoTask: true maxFires: 30 prompt='Run TaskList, pick the next available pending task, work on it.'",
-            "When no tasks are pending, the loop skips the wake entirely — no tokens burned on empty polls.",
+            "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.",
+            "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.",
         ],
         parameters: Type.Object({
@@ -439,7 +469,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
             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." })),
         }),
-        execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
             const { trigger: triggerInput, prompt, recurring, autoTask, triggerType, debounceMs, readOnly, maxFires } = params;
             let trigger;
             const inferred = triggerType ?? inferTriggerType(triggerInput);
@@ -487,6 +517,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
                 }
                 catch { /* filter parse failure, ignore */ }
             }
+            const bootstrapped = await maybeBootstrapTaskLoop(entry);
             widget.update();
             const triggerDesc = trigger.type === "cron"
                 ? `schedule: ${trigger.schedule}`
@@ -497,6 +528,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` : "") +
+                (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)`));
         },
@@ -956,6 +988,12 @@ Use MonitorList to find the monitor ID, then stop it with this tool.`,
                 }
                 if (trimmed) {
                     const entry = nativeTaskStore.create(trimmed.slice(0, 80), trimmed);
+                    pi.events.emit("tasks:created", {
+                        taskId: entry.id,
+                        subject: entry.subject,
+                        description: entry.description,
+                        status: entry.status,
+                    });
                     widget.update();
                     ctx.ui.notify(`Task #${entry.id} created`, "info");
                     return;
@@ -972,12 +1010,22 @@ Fields:
 - subject: brief actionable title
 - description: detailed requirements
 - metadata: optional tags/metadata`,
+            promptGuidelines: [
+                "Use TaskCreate to track complex multi-step work across turns.",
+                "TaskCreate accepts `subject` and `description` parameters only — do not invent extra fields unless the schema explicitly adds them.",
+            ],
             parameters: Type.Object({
                 subject: Type.String({ description: "Brief actionable title for the task" }),
                 description: Type.String({ description: "Detailed description of what needs to be done" }),
             }),
             execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
                 const entry = taskStore.create(params.subject, params.description);
+                pi.events.emit("tasks:created", {
+                    taskId: entry.id,
+                    subject: entry.subject,
+                    description: entry.description,
+                    status: entry.status,
+                });
                 widget.update();
                 return Promise.resolve(textResult(`Task #${entry.id} created: ${entry.subject}`));
             },
@@ -1012,6 +1060,11 @@ Fields:
             description: `Update task status or details. Set status to "in_progress" before starting work, "completed" when done.
 
 Statuses: pending → in_progress → completed`,
+            promptGuidelines: [
+                "Use TaskUpdate with parameter `id`, not `taskId`.",
+                "TaskUpdate accepts only `id`, `status`, `subject`, and `description`.",
+                "When a tool validation error clearly indicates a recoverable schema mismatch, correct the arguments and retry without narrating the recovery unless the user needs to know.",
+            ],
             parameters: Type.Object({
                 id: Type.String({ description: "Task ID to update" }),
                 status: Type.Optional(Type.String({ description: "New status", enum: ["pending", "in_progress", "completed"] })),

package/package.json

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

package/src/index.ts

@@ -229,6 +229,35 @@ export default function (pi: ExtensionAPI) {
     };
   }
 
+  function triggerHasEventSource(trigger: Trigger | string, source: string): boolean {
+    if (typeof trigger === "string") return false;
+    return trigger.type === "event"
+      ? trigger.source === source
+      : trigger.type === "hybrid"
+        ? trigger.event.source === source
+        : false;
+  }
+
+  async function maybeBootstrapTaskLoop(entry: LoopEntry): Promise<boolean> {
+    if (!entry.recurring) return false;
+    if (!triggerHasEventSource(entry.trigger, "tasks:created")) return false;
+
+    const pending = await hasPendingTasks();
+    if (pending <= 0) return false;
+
+    debug(`loop #${entry.id} — bootstrapping existing pending tasks (${pending})`);
+    await queueOrDeliverNotification({
+      loopId: entry.id,
+      prompt: entry.prompt,
+      trigger: entry.trigger,
+      timestamp: Date.now(),
+      readOnly: entry.readOnly,
+      recurring: false,
+      autoTask: true,
+    });
+    return true;
+  }
+
   async function deliverNotification(notification: PendingNotification): Promise<boolean> {
     if (notification.autoTask) {
       const pending = await hasPendingTasks();
@@ -470,8 +499,9 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
       "## readOnly mode",
       "Set readOnly: true for loops that only observe and report (checks, status polls). This prevents unintended changes.",
       "## Task-driven workflows",
-      "After creating tasks with TaskCreate, use an event loop with autoTask: true so the system checks for pending tasks before firing: LoopCreate trigger='tasks:created' triggerType='event' autoTask: true maxFires: 30 prompt='Run TaskList, pick the next available pending task, work on it.'",
-      "When no tasks are pending, the loop skips the wake entirely — no tokens burned on empty polls.",
+      "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.",
+      "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.",
     ],
     parameters: Type.Object({
@@ -485,7 +515,7 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
       maxFires: Type.Optional(Type.Number({ description: "Auto-stop after N fires. Prevents infinite token burn on polling loops." })),
     }),
 
-    execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       const { trigger: triggerInput, prompt, recurring, autoTask, triggerType, debounceMs, readOnly, maxFires } = params;
 
       let trigger: Trigger;
@@ -536,6 +566,8 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
         } catch { /* filter parse failure, ignore */ }
       }
 
+      const bootstrapped = await maybeBootstrapTaskLoop(entry);
+
       widget.update();
 
       const triggerDesc = trigger.type === "cron"
@@ -549,6 +581,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` : "") +
+        (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)`
       ));
@@ -1040,6 +1073,12 @@ Use MonitorList to find the monitor ID, then stop it with this tool.`,
         }
         if (trimmed) {
           const entry = nativeTaskStore.create(trimmed.slice(0, 80), trimmed);
+          pi.events.emit("tasks:created", {
+            taskId: entry.id,
+            subject: entry.subject,
+            description: entry.description,
+            status: entry.status,
+          });
           widget.update();
           ctx.ui.notify(`Task #${entry.id} created`, "info");
           return;
@@ -1057,12 +1096,22 @@ Fields:
 - subject: brief actionable title
 - description: detailed requirements
 - metadata: optional tags/metadata`,
+      promptGuidelines: [
+        "Use TaskCreate to track complex multi-step work across turns.",
+        "TaskCreate accepts `subject` and `description` parameters only — do not invent extra fields unless the schema explicitly adds them.",
+      ],
       parameters: Type.Object({
         subject: Type.String({ description: "Brief actionable title for the task" }),
         description: Type.String({ description: "Detailed description of what needs to be done" }),
       }),
       execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
         const entry = taskStore.create(params.subject, params.description);
+        pi.events.emit("tasks:created", {
+          taskId: entry.id,
+          subject: entry.subject,
+          description: entry.description,
+          status: entry.status,
+        });
         widget.update();
         return Promise.resolve(textResult(`Task #${entry.id} created: ${entry.subject}`));
       },
@@ -1099,6 +1148,11 @@ Fields:
       description: `Update task status or details. Set status to "in_progress" before starting work, "completed" when done.
 
 Statuses: pending → in_progress → completed`,
+      promptGuidelines: [
+        "Use TaskUpdate with parameter `id`, not `taskId`.",
+        "TaskUpdate accepts only `id`, `status`, `subject`, and `description`.",
+        "When a tool validation error clearly indicates a recoverable schema mismatch, correct the arguments and retry without narrating the recovery unless the user needs to know.",
+      ],
       parameters: Type.Object({
         id: Type.String({ description: "Task ID to update" }),
         status: Type.Optional(Type.String({ description: "New status", enum: ["pending", "in_progress", "completed"] })),