pi-all-notification 1.0.3 → 1.0.5

package/README.md

@@ -22,7 +22,9 @@ pi install npm:pi-all-notification
 
 ### Agent 自动触发
 
-Agent 完成响应时自动通知（`agent_end` 事件）。可在设置面板 toggle 触发时机。
+一轮运行**最终结束**时自动通知（Pi 的 `agent_settled` 事件）。自然结束发 `✅ Complete`，被用户取消发 `⏹ Cancelled`，两者不会混为一谈。可在设置面板 toggle 触发时机。
+
+> 用的是 `agent_settled` 而不是 `agent_end`：`agent_end` 之后还可能跟着重试、压缩恢复或排队的消息，在那里发通知既可能过早，也无法区分「完成」和「被取消」。
 
 ### Agent 手动调用
 
@@ -105,7 +107,7 @@ Webhook 支持 GET 和 POST，Body 模板支持变量替换：
 
 | 事件 | 默认 | 说明 |
 |------|------|------|
-| `agent_end` | ✅ | Agent 完成响应，等待输入 |
+| `agent_end` | ✅ | 一轮运行结束（自然完成 `✅` 或被取消 `⏹`） |
 | `agent_start` | ⬜ | Agent 开始处理 |
 | `tool_error` | ⬜ | 工具执行出错 |
 

package/extensions/index.ts

@@ -18,6 +18,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { execSync } from "node:child_process";
+import { describeBeforeAgentStart, settleNotification } from "./settle.ts";
 
 // ─── Types ────────────────────────────────────────────────────
 
@@ -46,6 +47,10 @@ interface WebhookConfig extends ChannelConfig {
 }
 
 interface TriggerConfig {
+  /**
+   * Notify when a run settles: naturally (`✅ Complete`) or cancelled (`⏹ Cancelled`).
+   * Named `agent_end` for backward compatibility with existing config files.
+   */
   agent_end: boolean;
   agent_start: boolean;
   tool_error: boolean;
@@ -252,6 +257,14 @@ function settingLabel(emoji: string, name: string, enabled: boolean, extra?: str
 
 export default function (pi: ExtensionAPI) {
   let projectName = "";
+  /**
+   * The prompt that started the current run, for the completion notification.
+   *
+   * `agent_settled` carries no messages, so the text is kept from
+   * `before_agent_start` instead; `agent_end` used to read it off
+   * `event.messages`, which `agent_settled` does not have.
+   */
+  let lastTaskDescription: string | null = null;
 
   // ── notify_user agent tool ────────────────────────────
   pi.registerTool({
@@ -681,7 +694,7 @@ export default function (pi: ExtensionAPI) {
     while (true) {
       const t = cfg.triggers;
       const items = [
-        { label: settingLabel("🏁", "agent_end (response complete)", t.agent_end), value: "agent_end" },
+        { label: settingLabel("🏁", "agent_end (run settled: complete or cancelled)", t.agent_end), value: "agent_end" },
         { label: settingLabel("🚀", "agent_start (processing begins)", t.agent_start), value: "agent_start" },
         { label: settingLabel("❌", "tool_error (tool execution error)", t.tool_error), value: "tool_error" },
         { label: "← Back", value: "back" },
@@ -747,6 +760,12 @@ export default function (pi: ExtensionAPI) {
     projectName = ctx.cwd.split(/[/\\]/).pop() || "";
   });
 
+  // Capture the prompt for the completion notification: `agent_settled` carries
+  // no messages, and this is the last point the prompt text is available.
+  pi.on("before_agent_start", (event, _ctx) => {
+    lastTaskDescription = describeBeforeAgentStart(event);
+  });
+
   pi.on("agent_start", (_event, ctx) => {
     projectName = ctx.cwd.split(/[/\\]/).pop() || "";
     const cfg = loadConfig();
@@ -762,28 +781,22 @@ export default function (pi: ExtensionAPI) {
     fireAll(cfg, vars);
   });
 
-  pi.on("agent_end", (event, _ctx) => {
+  // `agent_settled` is Pi's final notification boundary and is the only event
+  // that says whether the run was cancelled. `agent_end` fires earlier and can
+  // still be followed by retries, recovery or queued work, so a notification
+  // sent there can be both premature and wrong about how the run finished.
+  pi.on("agent_settled", (event, _ctx) => {
     const cfg = loadConfig();
     if (!cfg.triggers.agent_end) return;
 
-    let taskDesc = projectName;
-    if (event.messages?.length) {
-      for (let i = event.messages.length - 1; i >= 0; i--) {
-        const m = event.messages[i] as any;
-        if (m.role === "user" && m.content) {
-          const raw = typeof m.content === "string" ? m.content.trim() : "";
-          const firstLine = raw.split(/\n/)[0] || "";
-          taskDesc = firstLine.length > 40 ? firstLine.slice(0, 37) + "..." : firstLine;
-          break;
-        }
-      }
-    }
-
+    const decision = settleNotification(
+      event as { aborted?: unknown },
+      projectName,
+      lastTaskDescription,
+    );
     const vars: NotificationVars = {
-      title: "pi ✅ Complete",
-      message: taskDesc,
+      ...decision,
       project: projectName,
-      emoji: "✅",
       timestamp: new Date().toISOString(),
     };
     fireAll(cfg, vars);

package/extensions/settle.ts

@@ -0,0 +1,75 @@
+/**
+ * What a settled run should notify about.
+ *
+ * Pi's `agent_settled` is the final notification boundary and the only event
+ * that reports whether the run was aborted. `agent_end` fires earlier and may
+ * still be followed by retries, recovery or queued work, so a notification sent
+ * there can be both premature and wrong about how the run finished. This module
+ * holds the decision alone, so it is testable without loading the extension.
+ */
+
+export interface SettleNotification {
+  title: string;
+  message: string;
+  emoji: string;
+}
+
+/** A run's prompt, collapsed to one short line for a notification body. */
+export function describeTask(prompt: unknown): string | null {
+  if (typeof prompt !== "string") return null;
+  const firstLine = prompt.trim().split(/\n/)[0] ?? "";
+  if (!firstLine) return null;
+  return firstLine.length > 40 ? `${firstLine.slice(0, 37)}...` : firstLine;
+}
+
+/**
+ * Task text from `before_agent_start`.
+ *
+ * Pi 1.3 also fires this event for runs started by a custom message, where the
+ * event carries `message` instead of `prompt`.
+ */
+export function describeBeforeAgentStart(event: unknown): string | null {
+  if (!event || typeof event !== "object") return null;
+  const { prompt, message } = event as { prompt?: unknown; message?: unknown };
+  const fromPrompt = describeTask(prompt);
+  if (fromPrompt) return fromPrompt;
+  if (!message || typeof message !== "object") return null;
+  const content = (message as { content?: unknown }).content;
+  if (typeof content === "string") return describeTask(content);
+  if (!Array.isArray(content)) return null;
+  const text = content
+    .map((item) =>
+      item && typeof item === "object" && (item as { type?: unknown }).type === "text"
+        ? (item as { text?: unknown }).text
+        : undefined,
+    )
+    .filter((item): item is string => typeof item === "string")
+    .join("\n");
+  return describeTask(text);
+}
+
+/**
+ * The notification for a settled run.
+ *
+ * A cancelled run says so instead of reporting success: `aborted` distinguishes
+ * a run the person stopped from one that finished on its own, and calling a
+ * cancellation "Complete" is the bug this guards.
+ */
+export function settleNotification(
+  event: { aborted?: unknown },
+  projectName: string,
+  taskDescription: string | null,
+): SettleNotification {
+  if (event?.aborted === true) {
+    return {
+      title: "pi ⏹ Cancelled",
+      message: `Run cancelled — ${projectName}`,
+      emoji: "⏹",
+    };
+  }
+  return {
+    title: "pi ✅ Complete",
+    message: taskDescription ?? projectName,
+    emoji: "✅",
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-all-notification",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Multi-channel notification for pi: macOS desktop, Bark push, custom webhook",
   "keywords": [
     "pi-package",
@@ -19,6 +19,12 @@
       "./extensions/index.ts"
     ]
   },
+  "scripts": {
+    "test": "node --import tsx --test tests/*.test.ts"
+  },
+  "devDependencies": {
+    "tsx": "^4.23.15"
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^1.1.0"
   }

package/tests/settle.test.ts

@@ -0,0 +1,81 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { describeBeforeAgentStart, describeTask, settleNotification } from "../extensions/settle.ts";
+
+describe("describeTask", () => {
+  it("takes the first line of the prompt", () => {
+    assert.equal(describeTask("Fix the build\nand then tag it"), "Fix the build");
+  });
+
+  it("truncates a long first line", () => {
+    const long = "a".repeat(100);
+    const result = describeTask(long);
+    assert.equal(result, `${"a".repeat(37)}...`);
+    assert.equal(result?.length, 40);
+  });
+
+  it("returns null for empty or non-string prompts", () => {
+    assert.equal(describeTask(""), null);
+    assert.equal(describeTask("   \n  "), null);
+    assert.equal(describeTask(undefined), null);
+    assert.equal(describeTask({ text: "hi" }), null);
+  });
+});
+
+describe("describeBeforeAgentStart", () => {
+  it("reads the prompt from a user run", () => {
+    assert.equal(describeBeforeAgentStart({ messageType: "user", prompt: "Fix the build" }), "Fix the build");
+  });
+
+  it("reads text content from a custom-message run", () => {
+    const event = {
+      messageType: "custom",
+      message: { role: "custom", content: [{ type: "text", text: "Review the release\nand tag it" }] },
+    };
+    assert.equal(describeBeforeAgentStart(event), "Review the release");
+  });
+
+  it("reads string content from a custom-message run", () => {
+    const event = {
+      messageType: "custom",
+      message: { role: "custom", content: "Review the release" },
+    };
+    assert.equal(describeBeforeAgentStart(event), "Review the release");
+  });
+
+  it("ignores non-text custom content", () => {
+    assert.equal(
+      describeBeforeAgentStart({
+        messageType: "custom",
+        message: { role: "custom", content: [{ type: "image", data: "..." }] },
+      }),
+      null,
+    );
+  });
+});
+
+describe("settleNotification", () => {
+  it("reports a natural finish as complete", () => {
+    const note = settleNotification({ aborted: false }, "pi-plugins", "Run the tests");
+    assert.equal(note.emoji, "✅");
+    assert.match(note.title, /Complete/);
+    assert.equal(note.message, "Run the tests");
+  });
+
+  it("reports a cancelled run as cancelled, not complete", () => {
+    const note = settleNotification({ aborted: true }, "pi-plugins", "Run the tests");
+    assert.equal(note.emoji, "⏹");
+    assert.match(note.title, /Cancelled/);
+    assert.match(note.message, /cancelled/i);
+  });
+
+  it("falls back to the project name when no prompt was captured", () => {
+    const note = settleNotification({ aborted: false }, "pi-plugins", null);
+    assert.equal(note.message, "pi-plugins");
+  });
+
+  it("treats an absent aborted flag as a natural finish", () => {
+    const note = settleNotification({}, "pi-plugins", "task");
+    assert.equal(note.emoji, "✅");
+  });
+});