@pi-unipi/notify 0.1.1

package/README.md

@@ -0,0 +1,103 @@
+# @pi-unipi/notify
+
+Cross-platform notification extension for Pi. Sends push notifications to native OS, Gotify, and Telegram when agent lifecycle events occur.
+
+## What it does
+
+- Listens to Pi lifecycle events (workflow complete, Ralph loop done, MCP errors, etc.)
+- Routes notifications to your configured platforms
+- Provides `notify_user` tool for agent-initiated notifications
+- Per-event platform configuration with sensible defaults
+
+## Installation
+
+Part of the `@pi-unipi/unipi` meta-package. No separate install needed.
+
+## Platforms
+
+### Native OS (default)
+
+Desktop notifications via [node-notifier](https://github.com/mikaelbr/node-notifier):
+- **Windows:** SnoreToast (no admin required)
+- **macOS:** terminal-notifier
+- **Linux:** notify-send / libnotify
+
+Zero configuration — works out of the box.
+
+### Gotify
+
+Self-hosted push notification server. Configure in settings:
+
+```json
+{
+  "gotify": {
+    "enabled": true,
+    "serverUrl": "https://your-gotify-server.com",
+    "appToken": "your-app-token",
+    "priority": 5
+  }
+}
+```
+
+### Telegram
+
+Bot API notifications. Run setup command:
+
+```
+/unipi:notify-set-tg
+```
+
+This guides you through:
+1. Creating a bot via @BotFather
+2. Pasting the bot token
+3. Auto-detecting your chat ID
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/unipi:notify-settings` | Open settings overlay to configure platforms and events |
+| `/unipi:notify-set-tg` | Interactive Telegram bot setup |
+| `/unipi:notify-test` | Send test notification to all enabled platforms |
+
+## Agent Tool
+
+The `notify_user` tool is available to the agent for ad-hoc notifications:
+
+```
+notify_user({
+  title: "Build Failed",
+  message: "TypeScript compilation failed with 12 errors.",
+  priority: "high"
+})
+```
+
+See the bundled `notify` skill for full parameter documentation.
+
+## Event Configuration
+
+Notifications are triggered by these events (configurable in settings):
+
+| Event | Default | Description |
+|-------|---------|-------------|
+| `workflow_end` | On | Workflow command completes |
+| `ralph_loop_end` | On | Ralph loop completes |
+| `mcp_server_error` | On | MCP server error |
+| `agent_end` | Off | Agent finishes responding |
+| `memory_consolidated` | Off | Memory auto-saved |
+| `session_shutdown` | Off | Session ends |
+
+## Configuration
+
+Settings stored at `~/.unipi/config/notify/config.json`. Edit via:
+- Settings overlay: `/unipi:notify-settings`
+- Manual JSON editing
+- The agent can read config via the settings module
+
+## Info-Screen Integration
+
+The notify module registers with the info screen showing:
+- Enabled platform count
+- Active event subscriptions
+- Last notification timestamp
+- Total notifications sent this session

package/commands.ts

@@ -0,0 +1,210 @@
+/**
+ * @pi-unipi/notify — Command registration
+ *
+ * Registers slash commands for notification configuration and testing.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { UNIPI_PREFIX } from "@pi-unipi/core";
+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 { loadConfig } from "./settings.js";
+import { sendNativeNotification } from "./platforms/native.js";
+import { sendGotifyNotification } from "./platforms/gotify.js";
+import { sendTelegramNotification } from "./platforms/telegram.js";
+
+/**
+ * Register notify commands.
+ */
+export function registerNotifyCommands(pi: ExtensionAPI): void {
+  // /unipi:notify-settings — Opens settings TUI overlay
+  pi.registerCommand(
+    `${UNIPI_PREFIX}${NOTIFY_COMMANDS.SETTINGS}`,
+    {
+      description: "Configure notification platforms and events",
+      handler: async (_args: string, ctx: ExtensionContext) => {
+        if (!ctx.hasUI) {
+          ctx.ui.notify("Settings require an interactive UI.", "warning");
+          return;
+        }
+
+        ctx.ui.custom(
+          (tui: any, theme: any, _keybindings: any, done: any) => {
+            const overlay = new NotifySettingsOverlay();
+            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-set-gotify — Interactive Gotify setup
+  pi.registerCommand(
+    `${UNIPI_PREFIX}${NOTIFY_COMMANDS.SET_GOTIFY}`,
+    {
+      description: "Set up Gotify push notifications with connection test",
+      handler: async (_args: string, ctx: ExtensionContext) => {
+        if (!ctx.hasUI) {
+          ctx.ui.notify("Gotify setup requires an interactive UI.", "warning");
+          return;
+        }
+
+        ctx.ui.custom(
+          (tui: any, theme: any, _keybindings: any, done: any) => {
+            const overlay = new GotifySetupOverlay();
+            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-set-tg — Interactive Telegram setup
+  pi.registerCommand(
+    `${UNIPI_PREFIX}${NOTIFY_COMMANDS.SET_TG}`,
+    {
+      description: "Set up Telegram bot notifications with auto-detection",
+      handler: async (_args: string, ctx: ExtensionContext) => {
+        if (!ctx.hasUI) {
+          ctx.ui.notify("Telegram setup requires an interactive UI.", "warning");
+          return;
+        }
+
+        ctx.ui.custom(
+          (tui: any, theme: any, _keybindings: any, done: any) => {
+            const overlay = new TelegramSetupOverlay();
+            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}`,
+    {
+      description: "Send a test notification to all enabled platforms",
+      handler: async (_args: string, ctx: ExtensionContext) => {
+        const config = loadConfig();
+        const title = "Pi — Test Notification";
+        const message = `Test notification sent at ${new Date().toLocaleTimeString()}`;
+        const results: string[] = [];
+
+        // Native
+        if (config.native.enabled) {
+          try {
+            await sendNativeNotification(title, message, {
+              windowsAppId: config.native.windowsAppId,
+            });
+            results.push("✓ Native: sent");
+          } catch (err) {
+            results.push(
+              `✗ Native: ${err instanceof Error ? err.message : "failed"}`
+            );
+          }
+        }
+
+        // Gotify
+        if (config.gotify.enabled && config.gotify.serverUrl && config.gotify.appToken) {
+          try {
+            await sendGotifyNotification(
+              config.gotify.serverUrl,
+              config.gotify.appToken,
+              title,
+              message,
+              config.gotify.priority
+            );
+            results.push("✓ Gotify: sent");
+          } catch (err) {
+            results.push(
+              `✗ Gotify: ${err instanceof Error ? err.message : "failed"}`
+            );
+          }
+        }
+
+        // Telegram
+        if (config.telegram.enabled && config.telegram.botToken && config.telegram.chatId) {
+          try {
+            await sendTelegramNotification(
+              config.telegram.botToken,
+              config.telegram.chatId,
+              title,
+              message
+            );
+            results.push("✓ Telegram: sent");
+          } catch (err) {
+            results.push(
+              `✗ Telegram: ${err instanceof Error ? err.message : "failed"}`
+            );
+          }
+        }
+
+        if (results.length === 0) {
+          ctx.ui.notify("No platforms enabled. Use /unipi:notify-settings first.", "warning");
+        } else {
+          ctx.ui.notify(`Test results:\n${results.join("\n")}`, "info");
+        }
+      },
+    }
+  );
+}

package/events.ts

@@ -0,0 +1,192 @@
+/**
+ * @pi-unipi/notify — Event subscription registry
+ *
+ * Maps pi lifecycle events to notification dispatch.
+ * Supports built-in events and dynamic discovery via MODULE_READY.
+ */
+
+import type { ExtensionAPI } 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 { loadConfig } from "./settings.js";
+
+/** Built-in event definitions — maps event key to pi hook + display label */
+export const BUILTIN_EVENTS: Record<
+  string,
+  { hook: string; label: string }
+> = {
+  agent_end: { hook: "agent_end", label: "Agent Complete" },
+  workflow_end: { hook: UNIPI_EVENTS.WORKFLOW_END, label: "Workflow Done" },
+  ralph_loop_end: { hook: UNIPI_EVENTS.RALPH_LOOP_END, label: "Ralph Complete" },
+  mcp_server_error: { hook: UNIPI_EVENTS.MCP_SERVER_ERROR, label: "MCP Error" },
+  memory_consolidated: { hook: UNIPI_EVENTS.MEMORY_CONSOLIDATED, label: "Memory Saved" },
+  session_shutdown: { hook: "session_shutdown", label: "Session End" },
+};
+
+/** Stores registered listener cleanup functions */
+const cleanupFns: Array<() => void> = [];
+
+/**
+ * Register event listeners for all enabled notification events.
+ * Attaches listeners to pi hooks and routes notifications to platforms.
+ */
+export function registerEventListeners(
+  pi: ExtensionAPI,
+  config: NotifyConfig
+): void {
+  // Register built-in events
+  for (const [eventKey, def] of Object.entries(BUILTIN_EVENTS)) {
+    const eventConfig = config.events[eventKey];
+    if (!eventConfig?.enabled) continue;
+
+    const handler = async (payload: unknown) => {
+      const title = `Pi — ${def.label}`;
+      const message = buildEventMessage(eventKey, payload);
+      await dispatchNotification(pi, title, message, eventConfig.platforms, eventKey, config);
+    };
+
+    (pi as any).on(def.hook, handler);
+    cleanupFns.push(() => {
+      (pi as any).off(def.hook, handler);
+    });
+  }
+
+  // Listen for dynamic module events
+  const moduleHandler = async (payload: unknown) => {
+    const modPayload = payload as { name?: string; tools?: string[] };
+    if (modPayload?.name && modPayload.name !== "@pi-unipi/notify") {
+      // Module announced — check if it has events we should subscribe to
+      // For now, modules register their own events through MODULE_READY
+    }
+  };
+  (pi as any).on(UNIPI_EVENTS.MODULE_READY, moduleHandler);
+  cleanupFns.push(() => {
+    (pi as any).off(UNIPI_EVENTS.MODULE_READY, moduleHandler);
+  });
+}
+
+/** Remove all registered event listeners */
+export function unregisterEventListeners(): void {
+  for (const cleanup of cleanupFns) {
+    cleanup();
+  }
+  cleanupFns.length = 0;
+}
+
+/**
+ * Dispatch a notification to the configured platforms.
+ * Sends to all specified platforms (or defaults) in parallel.
+ */
+export async function dispatchNotification(
+  pi: ExtensionAPI,
+  title: string,
+  message: string,
+  eventPlatforms: NotifyPlatform[],
+  eventType: string,
+  config: NotifyConfig
+): Promise<NotifyDispatchResult> {
+  const platforms =
+    eventPlatforms.length > 0 ? eventPlatforms : 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;
+    return false;
+  });
+
+  const results = await Promise.all(
+    enabledPlatforms.map(async (platform) => {
+      try {
+        await sendToPlatform(platform, title, message, config);
+        return { platform, success: true };
+      } catch (err) {
+        console.error(
+          `[notify] Failed to send via ${platform}:`,
+          err instanceof Error ? err.message : err
+        );
+        return {
+          platform,
+          success: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    })
+  );
+
+  const allSuccess = results.length > 0 && results.every((r) => r.success);
+
+  // Emit notification sent event
+  emitEvent(pi, UNIPI_EVENTS.NOTIFICATION_SENT, {
+    eventType,
+    platforms: enabledPlatforms,
+    success: allSuccess,
+    timestamp: new Date().toISOString(),
+  });
+
+  return { results, allSuccess };
+}
+
+/** Send to a single platform */
+async function sendToPlatform(
+  platform: NotifyPlatform,
+  title: string,
+  message: string,
+  config: NotifyConfig
+): Promise<void> {
+  switch (platform) {
+    case "native":
+      await sendNativeNotification(title, message, {
+        windowsAppId: config.native.windowsAppId,
+      });
+      break;
+    case "gotify":
+      if (!config.gotify.serverUrl || !config.gotify.appToken) {
+        throw new Error("Gotify: serverUrl and appToken are required");
+      }
+      await sendGotifyNotification(
+        config.gotify.serverUrl,
+        config.gotify.appToken,
+        title,
+        message,
+        config.gotify.priority
+      );
+      break;
+    case "telegram":
+      if (!config.telegram.botToken || !config.telegram.chatId) {
+        throw new Error("Telegram: botToken and chatId are required");
+      }
+      await sendTelegramNotification(
+        config.telegram.botToken,
+        config.telegram.chatId,
+        title,
+        message
+      );
+      break;
+  }
+}
+
+/** Build notification message from event key and payload */
+function buildEventMessage(eventKey: string, payload: unknown): string {
+  const p = payload as Record<string, unknown>;
+
+  switch (eventKey) {
+    case "workflow_end":
+      return `Workflow ${String(p.command || "unknown")}${p.success === false ? " failed" : " completed"}`;
+    case "ralph_loop_end":
+      return `Ralph loop "${String(p.name || "unknown")}" ${p.status || "completed"}`;
+    case "mcp_server_error":
+      return `Server "${String(p.name || "unknown")}" error: ${String(p.error || "unknown error")}`;
+    case "agent_end":
+      return "Agent finished responding";
+    case "memory_consolidated":
+      return `Memory consolidated (${p.count || 0} items)`;
+    case "session_shutdown":
+      return "Session ending";
+    default:
+      return p.message ? String(p.message) : "Event occurred";
+  }
+}

package/index.ts

@@ -0,0 +1,57 @@
+/**
+ * @pi-unipi/notify — Extension entry
+ *
+ * Cross-platform notification system for Pi.
+ * Bridges agent lifecycle events to external platforms (native OS, Gotify, Telegram).
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import {
+  UNIPI_EVENTS,
+  MODULES,
+  NOTIFY_TOOLS,
+  emitEvent,
+  getPackageVersion,
+} from "@pi-unipi/core";
+import { registerNotifyTools } from "./tools.js";
+import { registerNotifyCommands } from "./commands.js";
+import { loadConfig } from "./settings.js";
+import {
+  registerEventListeners,
+  unregisterEventListeners,
+} from "./events.js";
+
+/** Package version */
+const VERSION = getPackageVersion(new URL(".", import.meta.url).pathname);
+
+export default function (pi: ExtensionAPI) {
+  // Register skills directory
+  const skillsDir = new URL("./skills", import.meta.url).pathname;
+  pi.on("resources_discover", async () => {
+    return {
+      skillPaths: [skillsDir],
+    };
+  });
+
+  // Register tools and commands
+  registerNotifyTools(pi);
+  registerNotifyCommands(pi);
+
+  // Session lifecycle — register events and announce module
+  pi.on("session_start", async () => {
+    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"],
+      tools: [NOTIFY_TOOLS.NOTIFY_USER],
+    });
+  });
+
+  // Cleanup on session shutdown
+  pi.on("session_shutdown", async () => {
+    unregisterEventListeners();
+  });
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@pi-unipi/notify",
+  "version": "0.1.1",
+  "description": "Cross-platform notification extension for Pi — native OS, Gotify, and Telegram notifications for agent lifecycle events",
+  "type": "module",
+  "license": "MIT",
+  "author": "Neuron Mr White",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Neuron-Mr-White/unipi.git",
+    "directory": "packages/notify"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "unipi",
+    "notify",
+    "notifications"
+  ],
+  "files": [
+    "index.ts",
+    "tools.ts",
+    "commands.ts",
+    "settings.ts",
+    "events.ts",
+    "types.ts",
+    "platforms/*",
+    "tui/*",
+    "skills/**/*",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "index.ts"
+    ],
+    "skills": [
+      "skills"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pi-unipi/core": "*",
+    "node-notifier": "^10.0.1"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  }
+}

package/platforms/gotify.ts

@@ -0,0 +1,36 @@
+/**
+ * @pi-unipi/notify — Gotify notification platform
+ *
+ * Sends push notifications to a Gotify server via HTTP POST.
+ * Gotify is a self-hosted push notification server.
+ */
+
+/** Send a notification to Gotify server */
+export async function sendGotifyNotification(
+  serverUrl: string,
+  appToken: string,
+  title: string,
+  message: string,
+  priority: number = 5
+): Promise<void> {
+  const url = serverUrl.replace(/\/$/, "") + "/message";
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Gotify-Key": appToken,
+    },
+    body: JSON.stringify({
+      title,
+      message,
+      priority,
+    }),
+  });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "<no body>");
+    throw new Error(
+      `Gotify API error ${response.status}: ${body}`
+    );
+  }
+}

package/platforms/native.ts

@@ -0,0 +1,47 @@
+/**
+ * @pi-unipi/notify — Native OS notification platform
+ *
+ * Wraps node-notifier for cross-platform desktop notifications.
+ * Windows: SnoreToast (no admin required)
+ * macOS: terminal-notifier
+ * Linux: notify-send / libnotify
+ */
+
+import notifier from "node-notifier";
+
+/** Options for native notification */
+export interface NativeNotificationOptions {
+  /** Windows appID to show instead of "SnoreToast" */
+  windowsAppId?: string;
+}
+
+/**
+ * Send a native OS notification.
+ * Resolves when notification is shown, rejects on error.
+ */
+export async function sendNativeNotification(
+  title: string,
+  message: string,
+  options?: NativeNotificationOptions
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    notifier.notify(
+      {
+        title,
+        message,
+        appID: options?.windowsAppId,
+      },
+      (err: Error | null) => {
+        if (err) {
+          reject(
+            new Error(
+              `Native notification failed: ${err.message}`
+            )
+          );
+        } else {
+          resolve();
+        }
+      }
+    );
+  });
+}