@pi-unipi/notify 0.1.5 → 0.1.6

package/README.md

@@ -1,6 +1,6 @@
 # @pi-unipi/notify
 
-Cross-platform notification extension for Pi. Sends push notifications to native OS, Gotify, and Telegram when agent lifecycle events occur.
+Cross-platform notification extension for Pi. Sends push notifications to native OS, Gotify, Telegram, and ntfy when agent lifecycle events occur.
 
 ## What it does
 
@@ -52,12 +52,35 @@ This guides you through:
 2. Pasting the bot token
 3. Auto-detecting your chat ID
 
+### ntfy
+
+HTTP-based pub-sub notifications via [ntfy.sh](https://ntfy.sh) or self-hosted. Run setup command:
+
+```
+/unipi:notify-set-ntfy
+```
+
+Or configure manually:
+
+```json
+{
+  "ntfy": {
+    "enabled": true,
+    "serverUrl": "https://ntfy.sh",
+    "topic": "your-topic-name",
+    "priority": 3
+  }
+}
+```
+
 ## Commands
 
 | Command | Description |
 |---------|-------------|
 | `/unipi:notify-settings` | Open settings overlay to configure platforms and events |
+| `/unipi:notify-set-gotify` | Configure Gotify server connection |
 | `/unipi:notify-set-tg` | Interactive Telegram bot setup |
+| `/unipi:notify-set-ntfy` | Configure ntfy topic and server |
 | `/unipi:notify-test` | Send test notification to all enabled platforms |
 
 ## Agent Tool

package/commands.ts

@@ -10,10 +10,13 @@ import { NOTIFY_COMMANDS } from "@pi-unipi/core";
 import { NotifySettingsOverlay } from "./tui/settings-overlay.js";
 import { GotifySetupOverlay } from "./tui/gotify-setup.js";
 import { TelegramSetupOverlay } from "./tui/telegram-setup.js";
+import { NtfySetupOverlay } from "./tui/ntfy-setup.js";
+import { RecapModelSelectorOverlay } from "./tui/recap-model-selector.js";
 import { loadConfig } from "./settings.js";
 import { sendNativeNotification } from "./platforms/native.js";
 import { sendGotifyNotification } from "./platforms/gotify.js";
 import { sendTelegramNotification } from "./platforms/telegram.js";
+import { sendNtfyNotification } from "./platforms/ntfy.js";
 
 /**
  * Register notify commands.
@@ -36,6 +39,34 @@ export function registerNotifyCommands(pi: ExtensionAPI): void {
             overlay.setTheme(theme);
             overlay.onClose = () => done(undefined);
             overlay.requestRender = () => tui.requestRender();
+            overlay.onOpenModelSelector = () => {
+              // Open model selector as nested overlay
+              ctx.ui.custom(
+                (innerTui: any, innerTheme: any, _innerKb: any, innerDone: any) => {
+                  const selector = new RecapModelSelectorOverlay();
+                  selector.setTheme(innerTheme);
+                  selector.onClose = () => innerDone(undefined);
+                  selector.requestRender = () => innerTui.requestRender();
+                  return {
+                    render: (w: number) => selector.render(w),
+                    invalidate: () => selector.invalidate(),
+                    handleInput: (data: string) => {
+                      selector.handleInput(data);
+                      innerTui.requestRender();
+                    },
+                  };
+                },
+                {
+                  overlay: true,
+                  overlayOptions: {
+                    width: "60%",
+                    minWidth: 40,
+                    anchor: "center",
+                    margin: 4,
+                  },
+                }
+              );
+            };
             return {
               render: (w: number) => overlay.render(w),
               invalidate: () => overlay.invalidate(),
@@ -59,6 +90,46 @@ export function registerNotifyCommands(pi: ExtensionAPI): void {
     }
   );
 
+  // /unipi:notify-recap-model — Open recap model selector directly
+  pi.registerCommand(
+    `${UNIPI_PREFIX}${NOTIFY_COMMANDS.RECAP_MODEL}`,
+    {
+      description: "Select model for notification recaps",
+      handler: async (_args: string, ctx: ExtensionContext) => {
+        if (!ctx.hasUI) {
+          ctx.ui.notify("Model selector requires an interactive UI.", "warning");
+          return;
+        }
+
+        ctx.ui.custom(
+          (tui: any, theme: any, _keybindings: any, done: any) => {
+            const overlay = new RecapModelSelectorOverlay();
+            overlay.setTheme(theme);
+            overlay.onClose = () => done(undefined);
+            overlay.requestRender = () => tui.requestRender();
+            return {
+              render: (w: number) => overlay.render(w),
+              invalidate: () => overlay.invalidate(),
+              handleInput: (data: string) => {
+                overlay.handleInput(data);
+                tui.requestRender();
+              },
+            };
+          },
+          {
+            overlay: true,
+            overlayOptions: {
+              width: "60%",
+              minWidth: 40,
+              anchor: "center",
+              margin: 4,
+            },
+          }
+        );
+      },
+    }
+  );
+
   // /unipi:notify-set-gotify — Interactive Gotify setup
   pi.registerCommand(
     `${UNIPI_PREFIX}${NOTIFY_COMMANDS.SET_GOTIFY}`,
@@ -139,6 +210,46 @@ export function registerNotifyCommands(pi: ExtensionAPI): void {
     }
   );
 
+  // /unipi:notify-set-ntfy — Interactive ntfy setup
+  pi.registerCommand(
+    `${UNIPI_PREFIX}${NOTIFY_COMMANDS.SET_NTFY}`,
+    {
+      description: "Set up ntfy push notifications with connection test",
+      handler: async (_args: string, ctx: ExtensionContext) => {
+        if (!ctx.hasUI) {
+          ctx.ui.notify("ntfy setup requires an interactive UI.", "warning");
+          return;
+        }
+
+        ctx.ui.custom(
+          (tui: any, theme: any, _keybindings: any, done: any) => {
+            const overlay = new NtfySetupOverlay();
+            overlay.setTheme(theme);
+            overlay.onClose = () => done(undefined);
+            overlay.requestRender = () => tui.requestRender();
+            return {
+              render: (w: number) => overlay.render(w),
+              invalidate: () => overlay.invalidate(),
+              handleInput: (data: string) => {
+                overlay.handleInput(data);
+                tui.requestRender();
+              },
+            };
+          },
+          {
+            overlay: true,
+            overlayOptions: {
+              width: "80%",
+              minWidth: 60,
+              anchor: "center",
+              margin: 2,
+            },
+          }
+        );
+      },
+    }
+  );
+
   // /unipi:notify-test — Send test notification to all enabled platforms
   pi.registerCommand(
     `${UNIPI_PREFIX}${NOTIFY_COMMANDS.TEST}`,
@@ -199,6 +310,25 @@ export function registerNotifyCommands(pi: ExtensionAPI): void {
           }
         }
 
+        // ntfy
+        if (config.ntfy.enabled && config.ntfy.serverUrl && config.ntfy.topic) {
+          try {
+            await sendNtfyNotification(
+              config.ntfy.serverUrl,
+              config.ntfy.topic,
+              title,
+              message,
+              config.ntfy.priority,
+              config.ntfy.token
+            );
+            results.push("✓ ntfy: sent");
+          } catch (err) {
+            results.push(
+              `✗ ntfy: ${err instanceof Error ? err.message : "failed"}`
+            );
+          }
+        }
+
         if (results.length === 0) {
           ctx.ui.notify("No platforms enabled. Use /unipi:notify-settings first.", "warning");
         } else {

package/events.ts

@@ -5,12 +5,27 @@
  * Supports built-in events and dynamic discovery via MODULE_READY.
  */
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { UNIPI_EVENTS, emitEvent } from "@pi-unipi/core";
 import type { NotifyConfig, NotifyPlatform, NotifyDispatchResult } from "./types.js";
 import { sendNativeNotification } from "./platforms/native.js";
 import { sendGotifyNotification } from "./platforms/gotify.js";
 import { sendTelegramNotification } from "./platforms/telegram.js";
+import { sendNtfyNotification } from "./platforms/ntfy.js";
+import { summarizeLastMessage } from "./summarize.js";
+
+/** Stored session context for modelRegistry access */
+let sessionCtx: ExtensionContext | null = null;
+
+/** Store session context (called from index.ts on session_start) */
+export function setSessionContext(ctx: ExtensionContext): void {
+  sessionCtx = ctx;
+}
+
+/** Clear session context (called on session_shutdown) */
+export function clearSessionContext(): void {
+  sessionCtx = null;
+}
 
 /** Built-in event definitions — maps event key to pi hook + display label */
 export const BUILTIN_EVENTS: Record<
@@ -34,8 +49,10 @@ export function registerEventListeners(
   pi: ExtensionAPI,
   config: NotifyConfig
 ): void {
-  // Register built-in events
+  // Register built-in events (except agent_end which has custom logic)
   for (const [eventKey, def] of Object.entries(BUILTIN_EVENTS)) {
+    if (eventKey === "agent_end") continue; // handled separately below
+
     const eventConfig = config.events[eventKey];
     if (!eventConfig?.enabled) continue;
 
@@ -48,6 +65,51 @@ export function registerEventListeners(
     (pi as any).on(def.hook, handler);
   }
 
+  // agent_end — custom handler with session name and recap support
+  const agentEndConfig = config.events["agent_end"];
+  if (agentEndConfig?.enabled) {
+    const handler = async (payload: unknown) => {
+      const sessionName = pi.getSessionName?.();
+      const title = `Pi — ${BUILTIN_EVENTS.agent_end.label}`;
+      let message: string;
+
+      if (config.recap.enabled) {
+        // Recap mode: summarize last assistant message
+        const lastText = extractLastAssistantText(payload);
+        if (lastText && sessionCtx?.modelRegistry) {
+          const provider = extractProvider(config.recap.model);
+          const modelId = extractModelId(config.recap.model);
+          const model = sessionCtx.modelRegistry.find(provider, modelId);
+          if (model) {
+            try {
+              const apiKeyResult = await sessionCtx.modelRegistry.getApiKeyAndHeaders(model);
+              const apiKey = apiKeyResult.ok ? (apiKeyResult as { apiKey?: string }).apiKey : undefined;
+              if (apiKey) {
+                const recap = await summarizeLastMessage(lastText, apiKey, model.baseUrl, model.api, modelId);
+                message = sessionName ? `${sessionName}: ${recap}` : recap;
+              } else {
+                message = buildAgentEndMessage(sessionName);
+              }
+            } catch {
+              message = buildAgentEndMessage(sessionName);
+            }
+          } else {
+            message = buildAgentEndMessage(sessionName);
+          }
+        } else {
+          message = buildAgentEndMessage(sessionName);
+        }
+      } else {
+        // No recap: use session name based message
+        message = buildAgentEndMessage(sessionName);
+      }
+
+      await dispatchNotification(pi, title, message, agentEndConfig.platforms, "agent_end", config);
+    };
+
+    (pi as any).on("agent_end", handler);
+  }
+
   // Listen for dynamic module events
   const moduleHandler = async (payload: unknown) => {
     const modPayload = payload as { name?: string; tools?: string[] };
@@ -59,6 +121,16 @@ export function registerEventListeners(
   (pi as any).on(UNIPI_EVENTS.MODULE_READY, moduleHandler);
 }
 
+/** Get all platforms that are currently enabled in config */
+function getEnabledPlatforms(config: NotifyConfig): NotifyPlatform[] {
+  const enabled: NotifyPlatform[] = [];
+  if (config.native.enabled) enabled.push("native");
+  if (config.gotify.enabled) enabled.push("gotify");
+  if (config.telegram.enabled) enabled.push("telegram");
+  if (config.ntfy.enabled) enabled.push("ntfy");
+  return enabled;
+}
+
 /** No-op — cleanup handled by session teardown */
 export function unregisterEventListeners(): void {}
 
@@ -74,13 +146,19 @@ export async function dispatchNotification(
   eventType: string,
   config: NotifyConfig
 ): Promise<NotifyDispatchResult> {
+  // Resolve platforms: event-specific → all enabled → global defaults
   const platforms =
-    eventPlatforms.length > 0 ? eventPlatforms : config.defaultPlatforms;
+    eventPlatforms.length > 0
+      ? eventPlatforms
+      : getEnabledPlatforms(config).length > 0
+        ? getEnabledPlatforms(config)
+        : config.defaultPlatforms;
 
   const enabledPlatforms = platforms.filter((p) => {
     if (p === "native") return config.native.enabled;
     if (p === "gotify") return config.gotify.enabled;
     if (p === "telegram") return config.telegram.enabled;
+    if (p === "ntfy") return config.ntfy.enabled;
     return false;
   });
 
@@ -152,6 +230,19 @@ async function sendToPlatform(
         message
       );
       break;
+    case "ntfy":
+      if (!config.ntfy.serverUrl || !config.ntfy.topic) {
+        throw new Error("ntfy: serverUrl and topic are required");
+      }
+      await sendNtfyNotification(
+        config.ntfy.serverUrl,
+        config.ntfy.topic,
+        title,
+        message,
+        config.ntfy.priority,
+        config.ntfy.token
+      );
+      break;
   }
 }
 
@@ -180,3 +271,59 @@ function buildEventMessage(eventKey: string, payload: unknown): string {
       return p.message ? String(p.message) : "Event occurred";
   }
 }
+
+/** Build agent_end message using session name */
+function buildAgentEndMessage(sessionName: string | undefined): string {
+  if (sessionName) return `${sessionName} - Agent is complete`;
+  return "Agent is complete";
+}
+
+/** Extract text from the last assistant message in agent_end payload */
+function extractLastAssistantText(payload: unknown): string | null {
+  const p = payload as { messages?: Array<{ role?: string; content?: unknown }> };
+  if (!p?.messages || !Array.isArray(p.messages)) return null;
+
+  // Find last assistant message
+  for (let i = p.messages.length - 1; i >= 0; i--) {
+    const msg = p.messages[i];
+    if (msg?.role !== "assistant") continue;
+
+    const content = msg.content;
+    if (typeof content === "string") return content;
+    if (Array.isArray(content)) {
+      // Extract text blocks from content array
+      const textParts: string[] = [];
+      for (const block of content) {
+        if (typeof block === "object" && block !== null) {
+          const b = block as { type?: string; text?: string };
+          if (b.type === "text" && typeof b.text === "string") {
+            textParts.push(b.text);
+          }
+        }
+      }
+      if (textParts.length > 0) return textParts.join("\n");
+    }
+  }
+
+  return null;
+}
+
+/** Extract provider from model reference (e.g. "openrouter/openai/gpt-oss-20b" → "openrouter") */
+function extractProvider(modelRef: string): string {
+  const slashIdx = modelRef.indexOf("/");
+  return slashIdx > 0 ? modelRef.slice(0, slashIdx) : modelRef;
+}
+
+/** Extract model ID from full reference (e.g. "openrouter/openai/gpt-oss-20b" → "openai/gpt-oss-20b") */
+function extractModelId(modelRef: string): string {
+  const slashIdx = modelRef.indexOf("/");
+  return slashIdx > 0 ? modelRef.slice(slashIdx + 1) : modelRef;
+}
+
+/** Resolve API key for a provider from environment variables */
+function resolveApiKey(modelRef: string): string | undefined {
+  const provider = extractProvider(modelRef);
+  // Try standard env var patterns
+  const envKey = `${provider.toUpperCase().replace(/-/g, "_")}_API_KEY`;
+  return process.env[envKey];
+}

package/index.ts

@@ -19,6 +19,8 @@ import { loadConfig } from "./settings.js";
 import {
   registerEventListeners,
   unregisterEventListeners,
+  setSessionContext,
+  clearSessionContext,
 } from "./events.js";
 
 /** Package version */
@@ -38,20 +40,22 @@ export default function (pi: ExtensionAPI) {
   registerNotifyCommands(pi);
 
   // Session lifecycle — register events and announce module
-  pi.on("session_start", async () => {
+  pi.on("session_start", async (_event, ctx) => {
+    setSessionContext(ctx);
     const config = loadConfig();
     registerEventListeners(pi, config);
 
     emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
       name: MODULES.NOTIFY,
       version: VERSION,
-      commands: ["unipi:notify-settings", "unipi:notify-set-gotify", "unipi:notify-set-tg", "unipi:notify-test"],
+      commands: ["unipi:notify-settings", "unipi:notify-set-gotify", "unipi:notify-set-tg", "unipi:notify-set-ntfy", "unipi:notify-test", "unipi:notify-recap-model"],
       tools: [NOTIFY_TOOLS.NOTIFY_USER],
     });
   });
 
   // Cleanup on session shutdown
   pi.on("session_shutdown", async () => {
+    clearSessionContext();
     unregisterEventListeners();
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/notify",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Cross-platform notification extension for Pi — native OS, Gotify, and Telegram notifications for agent lifecycle events",
   "type": "module",
   "license": "MIT",

package/platforms/ntfy.ts

@@ -0,0 +1,48 @@
+/**
+ * @pi-unipi/notify — ntfy notification platform
+ *
+ * Sends push notifications to an ntfy server via HTTP POST.
+ * ntfy is a simple HTTP-based pub-sub notification service.
+ * Supports self-hosted instances and ntfy.sh (public).
+ */
+
+/** Send a notification to an ntfy server */
+export async function sendNtfyNotification(
+  serverUrl: string,
+  topic: string,
+  title: string,
+  message: string,
+  priority: number = 3,
+  token?: string
+): Promise<void> {
+  // ntfy supports POSTing to the server root with a JSON body that carries
+  // topic/title/message/priority. JSON bodies are UTF-8 safe, unlike HTTP
+  // headers which must be ByteString (Latin-1) and reject characters like
+  // em dash (U+2014). See https://docs.ntfy.sh/publish/#publish-as-json
+  const url = serverUrl.replace(/\/$/, "");
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+
+  if (token) {
+    headers["Authorization"] = `Bearer ${token}`;
+  }
+
+  const body = JSON.stringify({
+    topic,
+    title,
+    message,
+    priority: Math.max(1, Math.min(5, priority)),
+  });
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers,
+    body,
+  });
+
+  if (!response.ok) {
+    const resBody = await response.text().catch(() => "<no body>");
+    throw new Error(`ntfy API error ${response.status}: ${resBody}`);
+  }
+}

package/settings.ts

@@ -38,6 +38,15 @@ export const DEFAULT_CONFIG: NotifyConfig = {
   telegram: {
     enabled: false,
   },
+  ntfy: {
+    enabled: false,
+    serverUrl: "https://ntfy.sh",
+    priority: 3,
+  },
+  recap: {
+    enabled: false,
+    model: "openrouter/openai/gpt-oss-20b",
+  },
 };
 
 /** Load config from disk, returning defaults if missing or invalid */
@@ -50,11 +59,8 @@ export function loadConfig(): NotifyConfig {
       // Merge with defaults to ensure new fields are present
       return mergeWithDefaults(parsed);
     }
-  } catch (err) {
-    console.warn(
-      `[notify] Failed to load config from ${configPath}, using defaults:`,
-      err
-    );
+  } catch (_err) {
+    // Config load failure — using defaults silently.
   }
   return { ...DEFAULT_CONFIG };
 }
@@ -101,6 +107,19 @@ export function validateConfig(config: NotifyConfig): string[] {
     errors.push("Gotify: priority must be between 1 and 10");
   }
 
+  if (config.ntfy.enabled) {
+    if (!config.ntfy.serverUrl) {
+      errors.push("ntfy: serverUrl is required");
+    }
+    if (!config.ntfy.topic) {
+      errors.push("ntfy: topic is required");
+    }
+  }
+
+  if (config.ntfy.priority < 1 || config.ntfy.priority > 5) {
+    errors.push("ntfy: priority must be between 1 and 5");
+  }
+
   return errors;
 }
 
@@ -112,5 +131,7 @@ function mergeWithDefaults(loaded: Partial<NotifyConfig>): NotifyConfig {
     native: { ...DEFAULT_CONFIG.native, ...loaded.native },
     gotify: { ...DEFAULT_CONFIG.gotify, ...loaded.gotify },
     telegram: { ...DEFAULT_CONFIG.telegram, ...loaded.telegram },
+    ntfy: { ...DEFAULT_CONFIG.ntfy, ...loaded.ntfy },
+    recap: { ...DEFAULT_CONFIG.recap, ...loaded.recap },
   };
 }

package/skills/configure-notify/SKILL.md

@@ -47,6 +47,13 @@ Help users configure the `@pi-unipi/notify` notification system.
     "enabled": false,
     "botToken": null,
     "chatId": null
+  },
+  "ntfy": {
+    "enabled": false,
+    "serverUrl": "https://ntfy.sh",
+    "topic": null,
+    "token": null,
+    "priority": 3
   }
 }
 ```
@@ -75,6 +82,20 @@ Bot API notifications. Requires:
 - `botToken` — From @BotFather
 - `chatId` — Auto-detected by `/unipi:notify-set-tg`
 
+### ntfy (default: disabled)
+
+Simple HTTP-based pub-sub notification service. Supports public [ntfy.sh](https://ntfy.sh) and self-hosted instances.
+Requires:
+- `serverUrl` — ntfy server URL (default: `https://ntfy.sh`)
+- `topic` — Topic name to publish to (acts as a channel)
+- `token` — Optional access token for authenticated servers
+- `priority` — 1-5 (default: 3)
+
+**Setup options:**
+1. **Interactive overlay:** Run `/unipi:notify-set-ntfy` for guided setup with connection test
+2. **Manual config:** Edit `config.json` directly with the fields above
+3. **Agent can write config:** Read the current config, merge changes, write back
+
 ## Commands
 
 | Command | Description |
@@ -82,6 +103,7 @@ Bot API notifications. Requires:
 | `/unipi:notify-settings` | TUI overlay to toggle platforms and events |
 | `/unipi:notify-set-gotify` | Interactive Gotify setup wizard |
 | `/unipi:notify-set-tg` | Interactive Telegram setup wizard |
+| `/unipi:notify-set-ntfy` | Interactive ntfy setup wizard |
 | `/unipi:notify-test` | Send test notification to all enabled platforms |
 
 ## Events
@@ -125,6 +147,7 @@ Read the JSON, make changes, write it back. Example:
 
 For Gotify: suggest running `/unipi:notify-set-gotify`
 For Telegram: suggest running `/unipi:notify-set-tg`
+For ntfy: suggest running `/unipi:notify-set-ntfy`
 For general settings: suggest `/unipi:notify-settings`
 
 ## Validation rules
@@ -132,3 +155,5 @@ For general settings: suggest `/unipi:notify-settings`
 - Gotify: `serverUrl` and `appToken` required when enabled
 - Gotify: `priority` must be 1-10
 - Telegram: `botToken` and `chatId` required when enabled
+- ntfy: `serverUrl` and `topic` required when enabled
+- ntfy: `priority` must be 1-5

package/tools.ts

@@ -26,7 +26,7 @@ const NotifyUserSchema = Type.Object({
   ),
   platforms: Type.Optional(
     Type.Array(
-      Type.String({ enum: ["native", "gotify", "telegram"] }),
+      Type.String({ enum: ["native", "gotify", "telegram", "ntfy"] }),
       { description: "Override platforms for this notification" }
     )
   ),
@@ -40,7 +40,7 @@ export function registerNotifyTools(pi: ExtensionAPI): void {
     name: NOTIFY_TOOLS.NOTIFY_USER,
     label: "Notify User",
     description:
-      "Send a notification to the user's configured platforms (native OS, Gotify, Telegram). " +
+      "Send a notification to the user's configured platforms (native OS, Gotify, Telegram, ntfy). " +
       "Use for critical errors, completion of long-running tasks, or when the user explicitly asked to be notified.",
     parameters: NotifyUserSchema,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx: ExtensionContext) {
@@ -53,7 +53,7 @@ export function registerNotifyTools(pi: ExtensionAPI): void {
         message: string;
         title?: string;
         priority?: "low" | "normal" | "high";
-        platforms?: Array<"native" | "gotify" | "telegram">;
+        platforms?: Array<"native" | "gotify" | "telegram" | "ntfy">;
       };
 
       const config = loadConfig();