@pi-unipi/notify 0.1.1

package/platforms/node-notifier.d.ts

@@ -0,0 +1,20 @@
+declare module "node-notifier" {
+  interface Notification {
+    title?: string;
+    message?: string;
+    appID?: string;
+    sound?: boolean | string;
+    icon?: string;
+    wait?: boolean;
+  }
+
+  interface Notifier {
+    notify(
+      notification: Notification,
+      callback: (err: Error | null, data: any) => void
+    ): void;
+  }
+
+  const notifier: Notifier;
+  export default notifier;
+}

package/platforms/telegram.ts

@@ -0,0 +1,77 @@
+/**
+ * @pi-unipi/notify — Telegram notification platform
+ *
+ * Sends notifications via Telegram Bot API.
+ * Supports auto-detection of chat ID via polling getUpdates.
+ */
+
+/** Send a notification via Telegram Bot API */
+export async function sendTelegramNotification(
+  botToken: string,
+  chatId: string,
+  title: string,
+  message: string
+): Promise<void> {
+  const text = `*${escapeMarkdown(title)}*\n${escapeMarkdown(message)}`;
+  const url = `https://api.telegram.org/bot${botToken}/sendMessage`;
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      chat_id: chatId,
+      text,
+      parse_mode: "MarkdownV2",
+    }),
+  });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "<no body>");
+    throw new Error(
+      `Telegram API error ${response.status}: ${body}`
+    );
+  }
+}
+
+/**
+ * Poll Telegram getUpdates to detect the chat ID from a user message.
+ * Returns the chat ID string, or null if no message found.
+ */
+export async function pollForChatId(
+  botToken: string,
+  signal?: AbortSignal
+): Promise<string | null> {
+  const url = `https://api.telegram.org/bot${botToken}/getUpdates?allowed_updates=["message"]`;
+
+  try {
+    const response = await fetch(url, { signal });
+    const data = (await response.json()) as {
+      ok: boolean;
+      result: Array<{
+        message?: { chat?: { id?: number } };
+        callback_query?: { message?: { chat?: { id?: number } } };
+      }>;
+    };
+
+    if (data.ok && data.result.length > 0) {
+      const lastUpdate = data.result[data.result.length - 1];
+      const chatId =
+        lastUpdate.message?.chat?.id ||
+        lastUpdate.callback_query?.message?.chat?.id;
+      if (chatId) {
+        return String(chatId);
+      }
+    }
+  } catch (err) {
+    if (signal?.aborted) throw err;
+    // Network error — return null to allow retry
+    return null;
+  }
+
+  return null;
+}
+
+/** Escape special MarkdownV2 characters */
+function escapeMarkdown(text: string): string {
+  return text.replace(/[_*\[\]()~`>#+\-=|{}.!\\]/g, "\\$&");
+}

package/settings.ts

@@ -0,0 +1,115 @@
+/**
+ * @pi-unipi/notify — Configuration management
+ *
+ * Loads, saves, and validates notification config from ~/.unipi/config/notify/config.json
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { dirname, join } from "path";
+import { homedir } from "os";
+import { NOTIFY_DIRS } from "@pi-unipi/core";
+import type { NotifyConfig } from "./types.js";
+
+/** Resolve config path (expands ~ to homedir) */
+function resolveConfigPath(): string {
+  const base = NOTIFY_DIRS.CONFIG.replace("~", homedir());
+  return join(base, "config.json");
+}
+
+/** Default configuration — native enabled, gotify/telegram disabled */
+export const DEFAULT_CONFIG: NotifyConfig = {
+  defaultPlatforms: ["native"],
+  events: {
+    workflow_end: { enabled: true, platforms: [] },
+    ralph_loop_end: { enabled: true, platforms: [] },
+    mcp_server_error: { enabled: true, platforms: [] },
+    agent_end: { enabled: false, platforms: [] },
+    memory_consolidated: { enabled: false, platforms: [] },
+    session_shutdown: { enabled: false, platforms: [] },
+  },
+  native: {
+    enabled: true,
+  },
+  gotify: {
+    enabled: false,
+    priority: 5,
+  },
+  telegram: {
+    enabled: false,
+  },
+};
+
+/** Load config from disk, returning defaults if missing or invalid */
+export function loadConfig(): NotifyConfig {
+  const configPath = resolveConfigPath();
+  try {
+    if (existsSync(configPath)) {
+      const raw = readFileSync(configPath, "utf-8");
+      const parsed = JSON.parse(raw) as Partial<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
+    );
+  }
+  return { ...DEFAULT_CONFIG };
+}
+
+/** Save config to disk, creating directory if needed */
+export function saveConfig(config: NotifyConfig): void {
+  const configPath = resolveConfigPath();
+  const dir = dirname(configPath);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+
+/** Update config with partial changes */
+export function updateConfig(partial: Partial<NotifyConfig>): NotifyConfig {
+  const current = loadConfig();
+  const updated = { ...current, ...partial };
+  saveConfig(updated);
+  return updated;
+}
+
+/** Validate that a config has required fields for enabled platforms */
+export function validateConfig(config: NotifyConfig): string[] {
+  const errors: string[] = [];
+
+  if (config.gotify.enabled) {
+    if (!config.gotify.serverUrl) {
+      errors.push("Gotify: serverUrl is required");
+    }
+    if (!config.gotify.appToken) {
+      errors.push("Gotify: appToken is required");
+    }
+  }
+
+  if (config.telegram.enabled) {
+    if (!config.telegram.botToken) {
+      errors.push("Telegram: botToken is required");
+    }
+    if (!config.telegram.chatId) {
+      errors.push("Telegram: chatId is required");
+    }
+  }
+
+  if (config.gotify.priority < 1 || config.gotify.priority > 10) {
+    errors.push("Gotify: priority must be between 1 and 10");
+  }
+
+  return errors;
+}
+
+/** Merge loaded config with defaults to ensure all fields exist */
+function mergeWithDefaults(loaded: Partial<NotifyConfig>): NotifyConfig {
+  return {
+    defaultPlatforms: loaded.defaultPlatforms ?? DEFAULT_CONFIG.defaultPlatforms,
+    events: { ...DEFAULT_CONFIG.events, ...loaded.events },
+    native: { ...DEFAULT_CONFIG.native, ...loaded.native },
+    gotify: { ...DEFAULT_CONFIG.gotify, ...loaded.gotify },
+    telegram: { ...DEFAULT_CONFIG.telegram, ...loaded.telegram },
+  };
+}

package/skills/configure-notify/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: configure-notify
+description: >
+  Help user configure Pi notification settings — platforms (native, Gotify, Telegram),
+  events, and per-event routing. Guide through setup or make changes directly.
+---
+
+# Configure Notify
+
+Help users configure the `@pi-unipi/notify` notification system.
+
+## When to use
+
+- User asks to set up notifications
+- User asks to enable/configure Gotify, Telegram, or native notifications
+- User wants to change which events trigger notifications
+- User asks about notification settings
+
+## Config location
+
+`~/.unipi/config/notify/config.json`
+
+## Config structure
+
+```json
+{
+  "defaultPlatforms": ["native"],
+  "events": {
+    "workflow_end": { "enabled": true, "platforms": [] },
+    "ralph_loop_end": { "enabled": true, "platforms": [] },
+    "mcp_server_error": { "enabled": true, "platforms": [] },
+    "agent_end": { "enabled": false, "platforms": [] },
+    "memory_consolidated": { "enabled": false, "platforms": [] },
+    "session_shutdown": { "enabled": false, "platforms": [] }
+  },
+  "native": {
+    "enabled": true,
+    "windowsAppId": null
+  },
+  "gotify": {
+    "enabled": false,
+    "serverUrl": null,
+    "appToken": null,
+    "priority": 5
+  },
+  "telegram": {
+    "enabled": false,
+    "botToken": null,
+    "chatId": null
+  }
+}
+```
+
+## Platforms
+
+### Native OS (default: enabled)
+
+Desktop notifications via node-notifier. Works out of the box on Windows, macOS, Linux.
+
+### Gotify (default: disabled)
+
+Self-hosted push notification server. Requires:
+- `serverUrl` — URL of your Gotify server (e.g. `https://gotify.example.com`)
+- `appToken` — Application token from Gotify web UI (Apps → Create Application)
+- `priority` — 1-10 (default: 5)
+
+**Setup options:**
+1. **Interactive overlay:** Tell user to run `/unipi:notify-set-gotify` 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
+
+### Telegram (default: disabled)
+
+Bot API notifications. Requires:
+- `botToken` — From @BotFather
+- `chatId` — Auto-detected by `/unipi:notify-set-tg`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/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-test` | Send test notification to all enabled platforms |
+
+## Events
+
+| 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 |
+
+Each event can override `platforms` — empty array means use `defaultPlatforms`.
+
+## Agent workflow
+
+### Reading current config
+
+```bash
+cat ~/.unipi/config/notify/config.json
+```
+
+### Updating config programmatically
+
+Read the JSON, make changes, write it back. Example:
+
+```json
+// To enable Gotify:
+{
+  "gotify": {
+    "enabled": true,
+    "serverUrl": "https://gotify.example.com",
+    "appToken": "AT_xxxxx",
+    "priority": 7
+  }
+}
+```
+
+### Guiding user to interactive setup
+
+For Gotify: suggest running `/unipi:notify-set-gotify`
+For Telegram: suggest running `/unipi:notify-set-tg`
+For general settings: suggest `/unipi:notify-settings`
+
+## Validation rules
+
+- Gotify: `serverUrl` and `appToken` required when enabled
+- Gotify: `priority` must be 1-10
+- Telegram: `botToken` and `chatId` required when enabled

package/skills/notify/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: notify
+description: >
+  Cross-platform notification system for Pi. Use notify_user when you need
+  to urgently alert the user about critical findings, errors, or completion
+  of long-running tasks.
+allowed-tools:
+  - notify_user
+---
+
+# Notify User
+
+Use the `notify_user` tool to send notifications to the user's configured
+platforms (native OS, Gotify, Telegram).
+
+## When to use notify_user
+
+- Critical errors that need immediate attention
+- Completion of long-running tasks (after user has been waiting)
+- Security concerns or suspicious activity detected
+- Results that the user explicitly asked to be notified about
+
+## When NOT to use notify_user
+
+- Routine status updates (use normal message instead)
+- Non-urgent information (let user read at their pace)
+- Every turn completion (spammy)
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `message` | string | required | Notification body |
+| `title` | string? | "Pi Notification" | Notification title |
+| `priority` | string? | "normal" | "low", "normal", or "high" |
+| `platforms` | string[]? | all enabled | Override which platforms to use |
+
+## Examples
+
+Alert on critical error:
+```
+notify_user({
+  title: "Build Failed",
+  message: "TypeScript compilation failed with 12 errors. Check src/auth.ts.",
+  priority: "high"
+})
+```
+
+Task completion:
+```
+notify_user({
+  title: "Deployment Complete",
+  message: "Successfully deployed to production. All health checks passed.",
+  priority: "normal"
+})
+```

package/tools.ts

@@ -0,0 +1,96 @@
+/**
+ * @pi-unipi/notify — Agent tool registration
+ *
+ * Registers the `notify_user` tool for ad-hoc notifications.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { NOTIFY_TOOLS } from "@pi-unipi/core";
+import { loadConfig } from "./settings.js";
+import { dispatchNotification } from "./events.js";
+import type { NotifyDispatchResult } from "./types.js";
+
+/** Schema for notify_user tool parameters */
+const NotifyUserSchema = Type.Object({
+  message: Type.String({ description: "Notification message body" }),
+  title: Type.Optional(
+    Type.String({ description: "Notification title (default: Pi Notification)" })
+  ),
+  priority: Type.Optional(
+    Type.String({
+      enum: ["low", "normal", "high"],
+      default: "normal",
+      description: "Priority level",
+    })
+  ),
+  platforms: Type.Optional(
+    Type.Array(
+      Type.String({ enum: ["native", "gotify", "telegram"] }),
+      { description: "Override platforms for this notification" }
+    )
+  ),
+});
+
+/**
+ * Register the notify_user tool with pi.
+ */
+export function registerNotifyTools(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: NOTIFY_TOOLS.NOTIFY_USER,
+    label: "Notify User",
+    description:
+      "Send a notification to the user's configured platforms (native OS, Gotify, Telegram). " +
+      "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) {
+      const {
+        message,
+        title,
+        priority: _priority,
+        platforms,
+      } = params as {
+        message: string;
+        title?: string;
+        priority?: "low" | "normal" | "high";
+        platforms?: Array<"native" | "gotify" | "telegram">;
+      };
+
+      const config = loadConfig();
+
+      // Resolve title
+      const notifTitle = title || "Pi Notification";
+
+      // Resolve platforms — use params.platforms or global defaults
+      const notifPlatforms = platforms || config.defaultPlatforms;
+
+      // Dispatch notification
+      const result: NotifyDispatchResult = await dispatchNotification(
+        pi,
+        notifTitle,
+        message,
+        notifPlatforms,
+        "agent_tool",
+        config
+      );
+
+      // Format result
+      const platformResults = result.results.map(
+        (r) => `${r.platform}: ${r.success ? "✓ sent" : `✗ ${r.error || "failed"}`}`
+      );
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Notification sent to ${result.results.length} platform(s):\n${platformResults.join("\n")}`,
+          },
+        ],
+        details: {
+          platforms: result.results.map((r) => r.platform),
+          allSuccess: result.allSuccess,
+        },
+      };
+    },
+  });
+}