@pi-unipi/unipi 2.1.3 → 2.2.1

package/packages/notify/platforms/native.ts

@@ -0,0 +1,79 @@
+/**
+ * @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";
+import { isWindowFocused } from "./focus.js";
+
+/** Options for native notification */
+export interface NativeNotificationOptions {
+  /** Windows appID to show instead of "SnoreToast" */
+  windowsAppId?: string;
+  /**
+   * When true, suppresses the notification if the terminal window is
+   * the foreground (active) window. Only effective on platforms where
+   * `isWindowFocused` is implemented (currently Windows).
+   */
+  suppressWhenFocused?: boolean;
+}
+
+/**
+ * Thrown by sendNativeNotification when the notification was suppressed
+ * because suppressWhenFocused is set and the terminal window is focused.
+ *
+ * Callers should catch this and treat it as intentional suppression,
+ * NOT as a send failure.
+ */
+export class SuppressedError extends Error {
+  constructor() {
+    super("Notification suppressed: terminal window is focused");
+    this.name = "SuppressedError";
+  }
+}
+
+/**
+ * Send a native OS notification.
+ *
+ * When `suppressWhenFocused` is true and `isWindowFocused()` returns true
+ * (i.e. the terminal is the foreground window), the notification is
+ * suppressed and the promise rejects with SuppressedError.
+ *
+ * Resolves when notification is shown, rejects with SuppressedError on
+ * suppression or with a standard Error on failure.
+ */
+export async function sendNativeNotification(
+  title: string,
+  message: string,
+  options?: NativeNotificationOptions
+): Promise<void> {
+  // Suppress if the terminal window is currently focused
+  if (options?.suppressWhenFocused && await isWindowFocused()) {
+    throw new SuppressedError();
+  }
+
+  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();
+        }
+      }
+    );
+  });
+}

package/packages/notify/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/packages/notify/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/packages/notify/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/packages/notify/settings.ts

@@ -28,6 +28,7 @@ export const DEFAULT_CONFIG: NotifyConfig = {
     memory_consolidated: { enabled: false, platforms: [] },
     session_shutdown: { enabled: false, platforms: [] },
     ask_user_prompt: { enabled: false, platforms: [] },
+    permission_request: { enabled: false, platforms: [] },
   },
   native: {
     enabled: true,

package/packages/notify/skills/configure-notify/SKILL.md

@@ -36,7 +36,9 @@ Help users configure the `@pi-unipi/notify` notification system.
     "agent_end": { "enabled": false, "platforms": [] },
     "agent_settled": { "enabled": false, "platforms": [] },
     "memory_consolidated": { "enabled": false, "platforms": [] },
-    "session_shutdown": { "enabled": false, "platforms": [] }
+    "session_shutdown": { "enabled": false, "platforms": [] },
+    "ask_user_prompt": { "enabled": false, "platforms": [] },
+    "permission_request": { "enabled": false, "platforms": [] }
   },
   "native": {
     "enabled": true,
@@ -155,9 +157,34 @@ ntfy uses dedicated `ntfy.json` files at both global and project scope, with ful
 | `agent_settled` | Off | Agent fully settles after retries, compaction, and queued continuations |
 | `memory_consolidated` | Off | Memory auto-saved |
 | `session_shutdown` | Off | Session ends |
+| `ask_user_prompt` | Off | Agent asked a question and is waiting for an answer |
+| `permission_request` | Off | A permission prompt is about to be shown |
 
 Each event can override `platforms` — empty array means use `defaultPlatforms`.
 
+### `permission_request`
+
+Fires on the `permissions:ui_prompt` broadcast from
+[`@gotgenes/pi-permission-system`](https://www.npmjs.com/package/@gotgenes/pi-permission-system),
+emitted immediately before the user-facing permission UI is invoked. Policy
+auto-allow, policy deny, session approvals, and infrastructure auto-allowed
+requests do **not** emit it, so this event does not produce notification spam.
+Forwarded subagent prompts are handled too — the parent UI session emits the
+event right before showing the forwarded dialog, and the notification is
+suffixed with `(forwarded)`.
+
+The notification is formatted defensively from the payload's `agentName`,
+`surface`, `value` and `message` fields:
+
+```text
+Pi — Permission Request
+Current agent requested bash 'npm test'. Allow this command?
+```
+
+Enable it when you run Pi in a background pane and don't want to miss a
+permission prompt. If the permission system is not installed the event simply
+never fires.
+
 ## Agent workflow
 
 ### Reading current config

package/packages/notify/src/__tests__/permission-prompt-message.test.ts

@@ -0,0 +1,172 @@
+/**
+ * Tests for buildPermissionPromptMessage — the `permissions:ui_prompt`
+ * payload projection used by the `permission_request` notify event.
+ *
+ * The test fixtures use `satisfies PermissionPromptEventPayload` to
+ * enforce the payload contract at compile time.
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  buildPermissionPromptMessage,
+  type PermissionPromptEventPayload,
+} from "../../permission-prompt-message.ts";
+
+describe("buildPermissionPromptMessage", () => {
+  it("formats a standard bash permission payload", () => {
+    const payload = {
+      requestId: "req-1",
+      source: "tool",
+      surface: "bash",
+      value: "npm test",
+      agentName: "Current agent",
+      message: "Allow this command?",
+    } satisfies PermissionPromptEventPayload;
+
+    assert.equal(
+      buildPermissionPromptMessage(payload),
+      "Current agent requested bash 'npm test'. Allow this command?",
+    );
+  });
+
+  it("falls back to \"Agent\" when agentName is absent", () => {
+    const payload = {
+      surface: "edit",
+      value: "src/index.ts",
+    } satisfies PermissionPromptEventPayload;
+
+    assert.equal(
+      buildPermissionPromptMessage(payload),
+      "Agent requested edit 'src/index.ts'.",
+    );
+  });
+
+  it("marks forwarded subagent prompts", () => {
+    const payload = {
+      surface: "mcp",
+      value: "github.create_issue",
+      agentName: "explore",
+      forwarding: { from: "subagent-1" },
+    } satisfies PermissionPromptEventPayload;
+
+    assert.equal(
+      buildPermissionPromptMessage(payload),
+      "explore requested mcp 'github.create_issue'. (forwarded)",
+    );
+  });
+
+  it("does not mark prompts when forwarding is explicitly falsy", () => {
+    for (const forwarding of [false, null, "", 0, {}, []]) {
+      const payload = {
+        surface: "read",
+        value: "/etc/hosts",
+        forwarding,
+      } satisfies PermissionPromptEventPayload;
+
+      const result = buildPermissionPromptMessage(payload);
+      assert.equal(
+        result.includes("(forwarded)"),
+        false,
+        `expected no forwarded marker for ${JSON.stringify(forwarding)}`,
+      );
+    }
+  });
+
+  it("uses surface alone when no value is provided", () => {
+    const payload = { surface: "bash" } satisfies PermissionPromptEventPayload;
+
+    assert.equal(
+      buildPermissionPromptMessage(payload),
+      "Agent requested bash access.",
+    );
+  });
+
+  it("uses value alone when no surface is provided", () => {
+    const payload = { value: "rm -rf build" } satisfies PermissionPromptEventPayload;
+
+    assert.equal(
+      buildPermissionPromptMessage(payload),
+      "Agent requested 'rm -rf build'.",
+    );
+  });
+
+  it("falls back to the message when surface and value are missing", () => {
+    const payload = {
+      requestId: "req-2",
+      message: "Allow access to the workspace?",
+    } satisfies PermissionPromptEventPayload;
+
+    assert.equal(
+      buildPermissionPromptMessage(payload),
+      "Allow access to the workspace?",
+    );
+  });
+
+  it("does not duplicate the message when it equals the request clause", () => {
+    const payload = {
+      surface: "bash",
+      value: "npm test",
+      agentName: "Current agent",
+      message: "Current agent requested bash 'npm test'.",
+    } satisfies PermissionPromptEventPayload;
+
+    assert.equal(
+      buildPermissionPromptMessage(payload),
+      "Current agent requested bash 'npm test'.",
+    );
+  });
+
+  it("returns a generic fallback for an empty payload", () => {
+    assert.equal(
+      buildPermissionPromptMessage({}),
+      "Pi is waiting for a permission decision.",
+    );
+  });
+
+  it("handles null, undefined and non-object payloads without throwing", () => {
+    for (const payload of [null, undefined, 42, "nope", true]) {
+      assert.equal(
+        buildPermissionPromptMessage(payload),
+        "Pi is waiting for a permission decision.",
+      );
+    }
+  });
+
+  it("treats empty and whitespace-only strings as absent", () => {
+    const payload = {
+      surface: "   ",
+      value: "",
+      agentName: "  ",
+      message: "\t\n",
+    } satisfies PermissionPromptEventPayload;
+
+    assert.equal(
+      buildPermissionPromptMessage(payload),
+      "Pi is waiting for a permission decision.",
+    );
+  });
+
+  it("ignores non-string surface/value/message fields", () => {
+    const payload = {
+      surface: 123,
+      value: { cmd: "ls" },
+      message: ["a"],
+    } as unknown as PermissionPromptEventPayload;
+
+    assert.equal(
+      buildPermissionPromptMessage(payload),
+      "Pi is waiting for a permission decision.",
+    );
+  });
+
+  it("still reports a forwarded prompt with no other detail", () => {
+    const payload = { forwarding: true } satisfies PermissionPromptEventPayload;
+
+    assert.equal(
+      buildPermissionPromptMessage(payload),
+      "Pi is waiting for a permission decision. (forwarded)",
+    );
+  });
+});