@trevonistrevon/pi-loop 0.4.1 → 0.4.2

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

@@ -972,6 +972,10 @@ 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" }),
@@ -1012,6 +1016,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.2",
   "description": "A pi extension for cron/event-based agent re-wake loops and background process monitoring.",
   "author": "trevonistrevon",
   "license": "MIT",

package/src/index.ts

@@ -1057,6 +1057,10 @@ 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" }),
@@ -1099,6 +1103,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"] })),