@vs4vijay/piverse 0.1.0 → 0.6.0

package/extensions/pi-queue/README.md

@@ -0,0 +1,178 @@
+# @vs4vijay/pi-queue
+
+Queue messages to run after the current Pi agent turn settles.
+
+## Install
+
+Install from npm, then add it to your pi config:
+
+```
+pi install npm:@vs4vijay/pi-queue
+```
+
+In your pi config, reference the package as an extension:
+
+```json
+{
+  "pi": {
+    "extensions": ["@vs4vijay/pi-queue"]
+  }
+}
+```
+
+Or, when developing in this repo, reference the extension path directly:
+
+```json
+{
+  "pi": {
+    "extensions": ["./extensions/pi-queue/src/index.ts"]
+  }
+}
+```
+
+## Commands
+
+All commands are available as both `/queue-*` and `/q-*`.
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `/queue <message>` | `/q <message>` | Add a message to the queue |
+| `/queue` | `/q` | Show pending messages with index numbers |
+| `/queue-clear` | `/q-clear` | Clear all queued messages |
+| `/queue-pause` | `/q-pause` | Pause auto-firing (queue stays intact) |
+| `/queue-resume` | `/q-resume` | Resume auto-firing and fire next immediately |
+| `/queue-flush` | `/q-flush` | Drain all remaining messages, one per turn, ignoring pause / error stop |
+| `/queue-rm <index>` | `/q-rm <index>` | Remove item at position (1-based) |
+| `/queue-next <msg>` | `/q-next <msg>` | Insert message at front (fires next) |
+| `/queue-file <path>` | `/q-file <path>` | Queue lines from a file (skips `#` comments) |
+
+## How It Works
+
+Queued messages are intentionally delivered **after** the current turn settles. The extension listens for the `agent_settled` event and only then fires the next message as a new user message — so follow-ups you queue mid-run never interrupt the turn in progress. They execute cleanly afterwards, one at a time.
+
+1. You `/q` one or more messages while the agent is working (or idle).
+2. The extension listens for the `agent_settled` event — fired when the agent fully settles.
+3. On settle, the next queued message fires as a new user message via `pi.sendUserMessage()`.
+4. Messages execute one at a time, in FIFO order.
+5. Slash commands (messages starting with `/`) are dispatched through the command system automatically.
+
+## Example usage
+
+Queue follow-ups while the agent is working:
+
+```
+> /queue refactor the auth module next
+Queued #1: "refactor the auth module next"
+
+> /queue run the test suite
+Queued #2: "run the test suite"
+
+> /queue
+Queued (2):
+1. refactor the auth module next
+2. run the test suite
+```
+
+Once the current turn settles, the queued messages fire one at a time as new user messages:
+
+```
+→ Queue: running 1/2   # "refactor the auth module next" is sent
+→ Queue: running 2/2   # "run the test suite" is sent
+```
+
+Changed your mind? Clear the queue instead:
+
+```
+> /queue-clear
+Cleared 2 queued message(s)
+```
+
+With nothing queued:
+
+```
+> /queue
+Queue is empty. /queue <message> to add.
+```
+
+If the queue is paused and empty:
+
+```
+> /queue-pause
+Queue paused.
+
+> /queue
+Queue is empty and paused. /queue <message> to add.
+```
+
+## Features
+
+### Stop on Error
+
+If a tool error occurs during a turn, the queue auto-pauses and notifies you. Use `/q-resume` to continue, or `/q-rm` to skip the problematic next item.
+
+### Progress
+
+During a drain sequence, you'll see: `Queue: running 2/5` — showing which item is firing out of the total batch.
+
+### Queue from File
+
+Load a batch of messages from a file:
+
+```
+# tasks.txt
+add error handling to the auth module
+write tests for it
+# this line is skipped
+update the README
+```
+
+```
+/q-file tasks.txt
+→ Queued 3 item(s) from tasks.txt
+```
+
+### Flush
+
+`/q-flush` drains **all** remaining queued messages back-to-back, one per turn — overriding both a manual pause and the stop-on-error behavior. Useful when you want the whole backlog fired off at once regardless of a mid-batch error.
+
+```
+> /q-flush
+Flush armed — firing all 3 remaining, one per turn.
+→ Queue: running 1/3
+→ Queue: running 2/3
+→ Queue: running 3/3
+```
+
+Running `/q-flush` on an empty queue reports `Queue already empty.`
+
+## Persistence
+
+Queue state and pause flag persist across `/reload` and session restarts via `session_shutdown`/`session_start` hooks.
+
+## Example
+
+```
+> /q add error handling to the auth module
+Queued #1: "add error handling to the auth module"
+
+> /q write tests for it
+Queued #2: "write tests for it"
+
+> /q
+Queued (2):
+1. add error handling to the auth module
+2. write tests for it
+
+> /q-next fix the lint errors first
+Inserted at #1: "fix the lint errors first" (3 total)
+
+> /q-pause
+Queue paused.
+
+> /q-rm 3
+Removed #3: "write tests for it" (2 remaining)
+
+> /q-resume
+Queue resumed. Firing next (2 remaining).
+→ Queue: running 1/2
+```

package/extensions/pi-queue/package.json

@@ -1,9 +1,19 @@
 {
   "name": "@vs4vijay/pi-queue",
-  "version": "0.1.0",
+  "version": "0.6.0",
   "description": "Queue messages to run after the current Pi session turn settles",
   "type": "module",
   "keywords": ["pi-package"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vs4vijay/piverse.git"
+  },
+  "author": "vs4vijay",
+  "homepage": "https://github.com/vs4vijay/piverse",
+  "bugs": {
+    "url": "https://github.com/vs4vijay/piverse/issues"
+  },
   "pi": {
     "extensions": ["./src/index.ts"]
   },
@@ -12,5 +22,8 @@
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
   }
 }

package/extensions/pi-queue/plan.md

@@ -0,0 +1,79 @@
+# pi-queue — Feature Plan
+
+## Current State
+
+FIFO message queue that fires after each agent turn settles. Commands: `/queue <msg>`, `/queue` (show), `/queue-clear`, `/queue-pause`, `/queue-resume`, `/queue-flush`, `/queue-rm`, `/queue-next`, `/queue-file`. Persists across session restarts. Auto-pauses on tool error; flushes override both pause and error stop.
+
+All planned features below are implemented.
+
+---
+
+## Planned Features
+
+### 1. Alias: `/q`
+
+- Register `/q` as an alias for `/queue` (same handler).
+- Similarly `/q-pause`, `/q-resume`, `/q-rm`, `/q-next`, `/q-file`, `/q-clear`.
+- Shorter to type during fast workflows.
+- **Done.**
+
+### 2. Pause / Resume
+
+- `/queue-pause` — stops auto-firing on `agent_settled`. Queue stays intact.
+- `/queue-resume` — re-enables auto-firing and immediately fires next if agent is idle.
+- Show paused state in `/queue` output (e.g., `"Queued (3, PAUSED)"`); when paused and empty, show a combined empty+paused message.
+- **Done.**
+
+### 3. Remove / Priority Insert
+
+- `/queue-rm <index>` — remove item at position (1-based).
+- `/queue-next <message>` — insert at position 1 (fire next).
+- **Done.**
+
+### 4. Stop on Error
+
+- If the agent's previous turn produced an error (tool failure, error event), auto-pause the queue.
+- Notify: `"Queue paused — previous turn had errors. /queue-resume to continue."`.
+- Error detection: watch `tool_result` events for `isError`.
+- **Done.**
+
+### 5. Progress Notification
+
+- On each `agent_settled` drain, notify: `"Queue: running 2/5"`.
+- Track total at start of drain batch vs remaining.
+- Reset counter when queue empties or new items are added after drain completes.
+- **Done.**
+
+### 6. Queue from File
+
+- `/queue-file <path>` — read file, each non-empty line becomes a queued message.
+- Skip lines starting with `#` (comments).
+- Report count added.
+- **Done.**
+
+### 7. Flush
+
+- `/queue-flush` — arm a drain that fires **all** remaining messages, one per `agent_settled`, ignoring both the manual pause and the stop-on-error pause, until the queue is empty.
+- Repeatedly sending `pi.sendUserMessage` one per turn keeps the extension's "fire after settle, one at a time" model intact and lets each message complete cleanly.
+- **Done.**
+
+---
+
+## Implementation Order
+
+| Phase | Features | Reason |
+|-------|----------|--------|
+| 1 | Alias, Pause/Resume, Remove, Queue-next | Steer a running queue |
+| 2 | Stop on Error, Progress | Safety + visibility |
+| 3 | Queue from File | Batch input |
+| 4 | Flush | Drain the whole backlog on demand |
+
+---
+
+## Notes
+
+- All commands register via `pi.registerCommand`. Each command gets both `/queue-*` and `/q-*` variants.
+- State additions (pause flag, progress counter) persist via existing `session_shutdown`/`session_start` pattern. The transient `flushing` flag resets on empty and on session start.
+- The queue sends messages as-is — shell commands ("run npm test") work because the agent interprets them like any user message.
+- Slash commands (e.g., `/review src/index.ts`, `/commit`) are supported: when a queued message starts with `/`, pass `{ expandPromptTemplates: true }` to `pi.sendUserMessage()` so it routes through the command dispatcher instead of going to the agent as plain text.
+- Handlers type their context as `ExtensionCommandContext` from `@earendil-works/pi-coding-agent`.

package/extensions/pi-queue/src/index.ts

@@ -1,52 +1,160 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 
 export default function (pi: ExtensionAPI) {
   let queue: string[] = [];
+  let paused = false;
+  let lastTurnHadError = false;
+  let drainTotal = 0;
+  let flushing = false;
 
-  pi.registerCommand("queue", {
-    description: "Queue a message to send after the current turn settles. No args = show queue.",
-    handler: async (args, ctx) => {
-      if (!args.trim()) {
-        if (queue.length === 0) {
-          ctx.ui.notify("Queue is empty. /queue <message> to add.", "info");
-        } else {
-          const display = queue.map((m, i) => `${i + 1}. ${m}`).join("\n");
-          ctx.ui.notify(`Queued (${queue.length}):\n${display}`, "info");
-        }
-        return;
+  // Register command under both /queue-* and /q-* names
+  function cmd(name: string, description: string, handler: (args: string, ctx: ExtensionCommandContext) => Promise<void>) {
+    const opts = { description, handler };
+    pi.registerCommand(`queue${name}`, opts);
+    pi.registerCommand(`q${name}`, opts);
+  }
+
+  cmd("", "Queue a message to send after the current turn settles. No args = show queue.", async (args, ctx) => {
+    if (!args.trim()) {
+      if (queue.length === 0) {
+        ctx.ui.notify(
+          paused
+            ? "Queue is empty and paused. /queue <message> to add."
+            : "Queue is empty. /queue <message> to add.",
+          "info"
+        );
+      } else {
+        const label = paused ? `Queued (${queue.length}, PAUSED)` : `Queued (${queue.length})`;
+        const display = queue.map((m, i) => `${i + 1}. ${m}`).join("\n");
+        ctx.ui.notify(`${label}:\n${display}`, "info");
       }
-      queue.push(args.trim());
-      ctx.ui.notify(`Queued #${queue.length}: "${args.trim()}"`, "info");
-    },
+      return;
+    }
+    queue.push(args.trim());
+    ctx.ui.notify(`Queued #${queue.length}: "${args.trim()}"`, "info");
+  });
+
+  cmd("-clear", "Clear all queued messages", async (_args, ctx) => {
+    const count = queue.length;
+    queue = [];
+    ctx.ui.notify(count ? `Cleared ${count} queued message(s)` : "Queue already empty", "info");
+  });
+
+  cmd("-pause", "Pause queue auto-firing", async (_args, ctx) => {
+    paused = true;
+    ctx.ui.notify("Queue paused.", "info");
+  });
+
+  cmd("-resume", "Resume queue auto-firing", async (_args, ctx) => {
+    paused = false;
+    if (queue.length > 0) {
+      ctx.ui.notify(`Queue resumed. Firing next (${queue.length} remaining).`, "info");
+      const next = queue.shift()!;
+      const opts = next.startsWith("/") ? { expandPromptTemplates: true } : {};
+      pi.sendUserMessage(next, opts);
+    } else {
+      ctx.ui.notify("Queue resumed (empty).", "info");
+    }
+  });
+
+  cmd("-flush", "Drain all remaining queued messages, one per turn, ignoring pause/error stop", async (_args, ctx) => {
+    if (queue.length === 0) {
+      ctx.ui.notify("Queue already empty.", "info");
+      return;
+    }
+    flushing = true;
+    paused = false;
+    ctx.ui.notify(`Flush armed — firing all ${queue.length} remaining, one per turn.`, "info");
+  });
+
+  cmd("-rm", "Remove a queued item by index (1-based)", async (args, ctx) => {
+    const idx = parseInt(args.trim(), 10);
+    if (isNaN(idx) || idx < 1 || idx > queue.length) {
+      ctx.ui.notify(`Invalid index. Use 1-${queue.length}.`, "warning");
+      return;
+    }
+    const [removed] = queue.splice(idx - 1, 1);
+    ctx.ui.notify(`Removed #${idx}: "${removed}" (${queue.length} remaining)`, "info");
+  });
+
+  cmd("-next", "Insert a message at the front of the queue (fires next)", async (args, ctx) => {
+    const msg = args.trim();
+    if (!msg) {
+      ctx.ui.notify("Usage: /queue-next <message>", "warning");
+      return;
+    }
+    queue.unshift(msg);
+    ctx.ui.notify(`Inserted at #1: "${msg}" (${queue.length} total)`, "info");
+  });
+
+  cmd("-file", "Queue messages from a file (one per line, # comments skipped)", async (args, ctx) => {
+    const filePath = args.trim();
+    if (!filePath) {
+      ctx.ui.notify("Usage: /queue-file <path>", "warning");
+      return;
+    }
+    const resolved = resolve(process.cwd(), filePath);
+    let content: string;
+    try {
+      content = readFileSync(resolved, "utf-8");
+    } catch {
+      ctx.ui.notify(`Cannot read file: ${resolved}`, "error");
+      return;
+    }
+    const lines = content.split("\n").filter((l) => l.trim() && !l.trim().startsWith("#"));
+    for (const line of lines) queue.push(line.trim());
+    ctx.ui.notify(`Queued ${lines.length} item(s) from ${filePath}`, "info");
   });
 
-  pi.registerCommand("queue-clear", {
-    description: "Clear all queued messages",
-    handler: async (_args, ctx) => {
-      const count = queue.length;
-      queue = [];
-      ctx.ui.notify(count ? `Cleared ${count} queued message(s)` : "Queue already empty", "info");
-    },
+  pi.on("tool_result", async (event) => {
+    if (event.isError) lastTurnHadError = true;
   });
 
-  pi.on("agent_settled", async () => {
-    if (queue.length === 0) return;
+  pi.on("agent_settled", async (_event, ctx) => {
+    if (queue.length === 0) {
+      drainTotal = 0;
+      flushing = false;
+      return;
+    }
+    if (!flushing) {
+      if (lastTurnHadError) {
+        paused = true;
+        lastTurnHadError = false;
+        ctx.ui.notify("Queue paused — previous turn had errors. /queue-resume to continue.", "warning");
+        return;
+      }
+      if (paused) return;
+    }
+    lastTurnHadError = false;
+
+    // Track progress
+    if (drainTotal === 0) drainTotal = queue.length;
+    const current = drainTotal - queue.length + 1;
+    ctx.ui.notify(`Queue: running ${current}/${drainTotal}`, "info");
+
     const next = queue.shift()!;
-    pi.sendUserMessage(next);
+    const opts = next.startsWith("/") ? { expandPromptTemplates: true } : {};
+    pi.sendUserMessage(next, opts);
   });
 
   pi.on("session_start", async (_event, ctx) => {
     queue = [];
+    paused = false;
+    flushing = false;
     for (const entry of ctx.sessionManager.getEntries()) {
       if (entry.type === "custom" && entry.customType === "piverse-queue-state") {
-        queue = (entry.data as { queue: string[] }).queue ?? [];
+        const data = entry.data as { queue: string[]; paused?: boolean };
+        queue = data.queue ?? [];
+        paused = data.paused ?? false;
       }
     }
   });
 
   pi.on("session_shutdown", async () => {
-    if (queue.length > 0) {
-      pi.appendEntry("piverse-queue-state", { queue });
+    if (queue.length > 0 || paused) {
+      pi.appendEntry("piverse-queue-state", { queue, paused });
     }
   });
 }

package/package.json

@@ -1,17 +1,33 @@
 {
   "name": "@vs4vijay/piverse",
-  "version": "0.1.0",
-  "description": "A multi-extension ecosystem for the Pi coding agent",
-  "keywords": ["pi-package"],
+  "version": "0.6.0",
+  "description": "A multi-extension ecosystem for the Pi coding agent — message queueing (/queue) and project notes (/notes) extensions",
+  "keywords": [
+    "pi-package"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vs4vijay/piverse.git"
+  },
+  "author": "vs4vijay",
+  "homepage": "https://github.com/vs4vijay/piverse",
+  "bugs": {
+    "url": "https://github.com/vs4vijay/piverse/issues"
+  },
   "type": "module",
   "pi": {
-    "extensions": ["./extensions/pi-queue/src/index.ts"]
+    "extensions": [
+      "./extensions/pi-queue/src/index.ts",
+      "./extensions/pi-notes/src/index.ts"
+    ]
   },
   "scripts": {
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-tui": "^0.84.2",
     "typebox": "*"
   },
   "devDependencies": {