@pi-unipi/notify 2.3.0 → 2.4.1

package/README.md

@@ -47,6 +47,8 @@ notify_user({
 })
 ```
 
+An explicit semantic priority overrides configured urgency for that dispatch on platforms that support it: `low`/`normal`/`high` map to Gotify `2`/`5`/`8` and ntfy `2`/`3`/`5`. Native and Telegram have no priority input and ignore it. When omitted, Gotify and ntfy retain their configured numeric priorities.
+
 ## Platforms
 
 ### Native OS

package/events.ts

@@ -7,7 +7,7 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { UNIPI_EVENTS, emitEvent } from "@pi-unipi/core";
-import type { NotifyConfig, NotifyPlatform, NotifyDispatchResult } from "./types.js";
+import type { NotifyConfig, NotifyPlatform, NotifyDispatchResult, NotifyPriority } from "./types.js";
 import { loadNtfyConfig } from "./ntfy-config.js";
 import { sendNativeNotification, SuppressedError } from "./platforms/native.js";
 import { sendGotifyNotification } from "./platforms/gotify.js";
@@ -170,7 +170,8 @@ export async function dispatchNotification(
   eventPlatforms: NotifyPlatform[],
   eventType: string,
   config: NotifyConfig,
-  cwd: string
+  cwd: string,
+  priority?: NotifyPriority,
 ): Promise<NotifyDispatchResult> {
   // Resolve ntfy config from project/global ntfy.json
   const ntfyConfig = loadNtfyConfig(cwd);
@@ -194,8 +195,8 @@ export async function dispatchNotification(
   const results = await Promise.all(
     enabledPlatforms.map(async (platform) => {
       try {
-        await sendToPlatform(platform, title, message, config, cwd);
-        return { platform, success: true };
+        const effectivePriority = await sendToPlatform(platform, title, message, config, cwd, priority);
+        return { platform, success: true, ...(effectivePriority === undefined ? {} : { priority: effectivePriority }) };
       } catch (err) {
         // SuppressedError is intentional, not a failure
         if (err instanceof SuppressedError) {
@@ -230,20 +231,29 @@ export async function dispatchNotification(
 }
 
 /** Send to a single platform */
+export function mapNotifyPriority(platform: "gotify" | "ntfy", priority: NotifyPriority): number {
+  const mappings = {
+    gotify: { low: 2, normal: 5, high: 8 },
+    ntfy: { low: 2, normal: 3, high: 5 },
+  } as const;
+  return mappings[platform][priority];
+}
+
 async function sendToPlatform(
   platform: NotifyPlatform,
   title: string,
   message: string,
   config: NotifyConfig,
-  cwd: string
-): Promise<void> {
+  cwd: string,
+  priority?: NotifyPriority,
+): Promise<number | undefined> {
   switch (platform) {
     case "native":
       await sendNativeNotification(title, message, {
         windowsAppId: config.native.windowsAppId,
         suppressWhenFocused: config.native.suppressWhenFocused,
       });
-      break;
+      return undefined;
     case "gotify":
       if (!config.gotify.serverUrl || !config.gotify.appToken) {
         throw new Error("Gotify: serverUrl and appToken are required");
@@ -253,9 +263,9 @@ async function sendToPlatform(
         config.gotify.appToken,
         title,
         message,
-        config.gotify.priority
+        priority ? mapNotifyPriority("gotify", priority) : config.gotify.priority
       );
-      break;
+      return priority ? mapNotifyPriority("gotify", priority) : config.gotify.priority;
     case "telegram":
       if (!config.telegram.botToken || !config.telegram.chatId) {
         throw new Error("Telegram: botToken and chatId are required");
@@ -266,10 +276,10 @@ async function sendToPlatform(
         title,
         message
       );
-      break;
+      return undefined;
     case "ntfy": {
       const ntfyConfig = loadNtfyConfig(cwd);
-      if (!ntfyConfig.enabled) return;
+      if (!ntfyConfig.enabled) return undefined;
       if (!ntfyConfig.serverUrl || !ntfyConfig.topic) {
         throw new Error("ntfy: serverUrl and topic are required");
       }
@@ -278,10 +288,10 @@ async function sendToPlatform(
         ntfyConfig.topic,
         title,
         message,
-        ntfyConfig.priority,
+        priority ? mapNotifyPriority("ntfy", priority) : ntfyConfig.priority,
         ntfyConfig.token
       );
-      break;
+      return priority ? mapNotifyPriority("ntfy", priority) : ntfyConfig.priority;
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/notify",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "description": "Cross-platform notification extension for Pi — native OS, Gotify, and Telegram notifications for agent lifecycle events",
   "type": "module",
   "main": "index.ts",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.3.0",
+    "@pi-unipi/core": "2.4.1",
     "node-notifier": "^10.0.1"
   },
   "peerDependencies": {

package/tools.ts

@@ -8,7 +8,8 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { Type } from "typebox";
 import { NOTIFY_TOOLS } from "@pi-unipi/core";
 import { loadConfig } from "./settings.js";
-import { dispatchNotification } from "./events.js";
+import { dispatchNotification, mapNotifyPriority } from "./events.js";
+import type { NotifyPriority } from "./types.js";
 
 /** Schema for notify_user tool parameters */
 const NotifyUserSchema = Type.Object({
@@ -19,7 +20,6 @@ const NotifyUserSchema = Type.Object({
   priority: Type.Optional(
     Type.String({
       enum: ["low", "normal", "high"],
-      default: "normal",
       description: "Priority level",
     })
   ),
@@ -46,12 +46,12 @@ export function registerNotifyTools(pi: ExtensionAPI): void {
       const {
         message,
         title,
-        priority: _priority,
+        priority,
         platforms,
       } = params as {
         message: string;
         title?: string;
-        priority?: "low" | "normal" | "high";
+        priority?: NotifyPriority;
         platforms?: Array<"native" | "gotify" | "telegram" | "ntfy">;
       };
 
@@ -65,18 +65,27 @@ export function registerNotifyTools(pi: ExtensionAPI): void {
 
       // Fire-and-forget: dispatch in background so the tool doesn't block the agent
       const cwd = process.cwd();
-      dispatchNotification(
+      const dispatchPromise = dispatchNotification(
         pi,
         notifTitle,
         message,
         notifPlatforms,
         "agent_tool",
         config,
-        cwd
-      ).catch(() => {
+        cwd,
+        priority,
+      );
+      void dispatchPromise.catch(() => {
         // Silently ignore — background dispatch failure is non-blocking.
       });
 
+      const priorityByPlatform = priority ? Object.fromEntries(
+        notifPlatforms.flatMap((platform) => {
+          if (platform === "gotify" || platform === "ntfy") return [[platform, mapNotifyPriority(platform, priority)]];
+          return [];
+        }),
+      ) : undefined;
+
       return {
         content: [
           {
@@ -84,7 +93,7 @@ export function registerNotifyTools(pi: ExtensionAPI): void {
             text: `Notification sending to ${notifPlatforms.length} platform(s): ${notifPlatforms.join(", ")}`,
           },
         ],
-        details: { platforms: notifPlatforms },
+        details: { platforms: notifPlatforms, priority, priorityByPlatform },
       };
     },
   });

package/types.ts

@@ -90,13 +90,15 @@ export interface NotifyConfig {
 }
 
 /** Parameters for the notify_user agent tool */
+export type NotifyPriority = "low" | "normal" | "high";
+
 export interface NotifyUserParams {
   /** Notification message body */
   message: string;
   /** Notification title (default: "Pi Notification") */
   title?: string;
   /** Priority level */
-  priority?: "low" | "normal" | "high";
+  priority?: NotifyPriority;
   /** Override platforms for this notification */
   platforms?: NotifyPlatform[];
 }
@@ -109,6 +111,8 @@ export interface NotifyResult {
   success: boolean;
   /** True when the notification was intentionally suppressed (e.g. window focused) */
   suppressed?: boolean;
+  /** Effective numeric priority for platforms that support it. */
+  priority?: number;
   /** Error message if failed */
   error?: string;
 }