@pi-unipi/notify 2.0.2 → 2.0.4

package/README.md

@@ -2,7 +2,7 @@
 
 Push notifications when things happen. Workflow finishes, Ralph loop completes, MCP server errors — notify sends alerts to native OS, Gotify, Telegram, or ntfy.
 
-Configure once, get alerts everywhere. Per-event platform routing lets you send critical errors to Telegram and routine completions to Gotify.
+Configure once, get alerts everywhere. Per-event platform routing lets you send critical errors to Telegram and routine completions to Gotify. Native desktop notifications can also be suppressed while the Pi window is focused.
 
 ## Commands
 
@@ -53,7 +53,7 @@ Desktop notifications via [node-notifier](https://github.com/mikaelbr/node-notif
 - **macOS:** terminal-notifier
 - **Linux:** notify-send / libnotify
 
-Zero configuration — works out of the box.
+Zero configuration — works out of the box. Set `native.suppressWhenFocused` to `true` to skip native notifications when the active/focused window is already Pi.
 
 ### Gotify
 

package/commands.ts

@@ -14,7 +14,7 @@ import { NtfySetupOverlay } from "./tui/ntfy-setup.js";
 import { RecapModelSelectorOverlay } from "./tui/recap-model-selector.js";
 import { loadConfig } from "./settings.js";
 import { loadNtfyConfig } from "./ntfy-config.js";
-import { sendNativeNotification } from "./platforms/native.js";
+import { sendNativeNotification, SuppressedError } from "./platforms/native.js";
 import { sendGotifyNotification } from "./platforms/gotify.js";
 import { sendTelegramNotification } from "./platforms/telegram.js";
 import { sendNtfyNotification } from "./platforms/ntfy.js";
@@ -267,12 +267,17 @@ export function registerNotifyCommands(pi: ExtensionAPI): void {
           try {
             await sendNativeNotification(title, message, {
               windowsAppId: config.native.windowsAppId,
+              suppressWhenFocused: config.native.suppressWhenFocused,
             });
             results.push("✓ Native: sent");
           } catch (err) {
-            results.push(
-              `✗ Native: ${err instanceof Error ? err.message : "failed"}`
-            );
+            if (err instanceof SuppressedError) {
+              results.push("— Native: suppressed (window focused)");
+            } else {
+              results.push(
+                `✗ Native: ${err instanceof Error ? err.message : "failed"}`
+              );
+            }
           }
         }
 

package/events.ts

@@ -9,7 +9,7 @@ import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-age
 import { UNIPI_EVENTS, emitEvent } from "@pi-unipi/core";
 import type { NotifyConfig, NotifyPlatform, NotifyDispatchResult } from "./types.js";
 import { loadNtfyConfig } from "./ntfy-config.js";
-import { sendNativeNotification } from "./platforms/native.js";
+import { sendNativeNotification, SuppressedError } from "./platforms/native.js";
 import { sendGotifyNotification } from "./platforms/gotify.js";
 import { sendTelegramNotification } from "./platforms/telegram.js";
 import { sendNtfyNotification } from "./platforms/ntfy.js";
@@ -184,6 +184,10 @@ export async function dispatchNotification(
         await sendToPlatform(platform, title, message, config, cwd);
         return { platform, success: true };
       } catch (err) {
+        // SuppressedError is intentional, not a failure
+        if (err instanceof SuppressedError) {
+          return { platform, success: true, suppressed: true };
+        }
         // Silently ignore — platform send failure is tracked in results.
         return {
           platform,
@@ -194,13 +198,18 @@ export async function dispatchNotification(
     })
   );
 
-  const allSuccess = results.length > 0 && results.every((r) => r.success);
+  const unsuppressed = results.filter((r) => !r.suppressed);
+  const allSuccess = results.length > 0 && unsuppressed.every((r) => r.success);
+  const suppressedPlatforms = results
+    .filter((r) => r.suppressed)
+    .map((r) => r.platform);
 
   // Emit notification sent event
   emitEvent(pi, UNIPI_EVENTS.NOTIFICATION_SENT, {
     eventType,
     platforms: enabledPlatforms,
     success: allSuccess,
+    ...(suppressedPlatforms.length > 0 && { suppressedPlatforms }),
     timestamp: new Date().toISOString(),
   });
 
@@ -219,6 +228,7 @@ async function sendToPlatform(
     case "native":
       await sendNativeNotification(title, message, {
         windowsAppId: config.native.windowsAppId,
+        suppressWhenFocused: config.native.suppressWhenFocused,
       });
       break;
     case "gotify":

package/package.json

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

package/platforms/focus-win.ts

@@ -0,0 +1,123 @@
+/**
+ * @pi-unipi/notify — Windows focus detection
+ *
+ * Checks whether the terminal window is the foreground (active) window
+ * by walking the WMI process tree upward from the current process PID
+ * and comparing each ancestor against the foreground window's owner PID.
+ *
+ * This approach works reliably across cmd, PowerShell, and Windows
+ * Terminal, unlike GetConsoleWindow which returns NULL in spawned
+ * child processes.
+ *
+ * Requires PowerShell (built-in on Windows 7+).
+ */
+
+import { execFile } from "child_process";
+import { writeFileSync, rmSync, mkdtempSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+// ---------------------------------------------------------------------------
+// PowerShell script (embedded)
+// ---------------------------------------------------------------------------
+
+const POWERCHECK_SCRIPT = `
+param($targetPid)
+Add-Type @'
+using System;
+using System.Runtime.InteropServices;
+public class WinAPI {
+    [DllImport("user32.dll", SetLastError = false)]
+    public static extern IntPtr GetForegroundWindow();
+    [DllImport("user32.dll", SetLastError = false)]
+    public static extern uint GetWindowThreadProcessId(IntPtr hWnd, out uint lpdwProcessId);
+}
+'@ | Out-Null
+$fgHwnd = [WinAPI]::GetForegroundWindow()
+[uint32]$fgPid = 0
+[void][WinAPI]::GetWindowThreadProcessId($fgHwnd, [ref]$fgPid)
+$curPid = $targetPid
+$maxDepth = 20
+while ($curPid -gt 0 -and $maxDepth-- -gt 0) {
+    if ($curPid -eq $fgPid) { Write-Host -NoNewline 'True'; exit }
+    $proc = Get-CimInstance -Class Win32_Process -Filter "ProcessId = $curPid" -ErrorAction SilentlyContinue | Select-Object -Property ParentProcessId
+    if (-not $proc) { break }
+    $curPid = $proc.ParentProcessId
+}
+Write-Host -NoNewline 'False'
+`;
+
+// ---------------------------------------------------------------------------
+// Cache — avoid spawning PowerShell on every check
+// ---------------------------------------------------------------------------
+
+let cached: { result: boolean; time: number } | null = null;
+const CACHE_TTL_MS = 500;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true when the terminal window that owns the current process is
+ * the foreground (active) window on Windows.
+ *
+ * Works by:
+ *   1. Calling Win32 GetForegroundWindow + GetWindowThreadProcessId to
+ *      obtain the foreground window's owning PID.
+ *   2. Walking the WMI Win32_Process parent chain upward from
+ *      process.pid.
+ *   3. If any ancestor PID matches the foreground PID the terminal is
+ *      considered focused.
+ *
+ * The result is cached for 500 ms to avoid spawning PowerShell on rapid
+ * consecutive checks (e.g. batch notifications).
+ */
+export async function isWindowFocusedOnWindows(): Promise<boolean> {
+  const now = Date.now();
+  if (cached && now - cached.time < CACHE_TTL_MS) {
+    return cached.result;
+  }
+
+  let tmpDir: string | null = null;
+  try {
+    tmpDir = mkdtempSync(join(tmpdir(), "pi-focus-"));
+    const scriptPath = join(tmpDir, "check.ps1");
+    writeFileSync(scriptPath, POWERCHECK_SCRIPT, "utf-8");
+
+    const stdout = await new Promise<string>((resolve, reject) => {
+      execFile(
+        "powershell.exe",
+        [
+          "-NoProfile",
+          "-NonInteractive",
+          "-ExecutionPolicy",
+          "Bypass",
+          "-File",
+          scriptPath,
+          String(process.pid),
+        ],
+        { timeout: 5000, encoding: "utf-8" },
+        (err, out) => {
+          if (err) reject(err);
+          else resolve(out);
+        }
+      );
+    });
+
+    cached = { result: stdout.trim() === "True", time: Date.now() };
+    return cached.result;
+  } catch {
+    // Detection failure → safe default: assume NOT focused (don't suppress)
+    cached = { result: false, time: Date.now() };
+    return false;
+  } finally {
+    if (tmpDir) {
+      try {
+        rmSync(tmpDir, { recursive: true });
+      } catch {
+        // Temp file cleanup is non-critical
+      }
+    }
+  }
+}

package/platforms/focus.ts

@@ -0,0 +1,33 @@
+/**
+ * @pi-unipi/notify — Focus detection abstraction
+ *
+ * Unified interface for checking whether the terminal window is the
+ * foreground (active) window. Platform-specific implementations are
+ * dispatched based on process.platform.
+ *
+ * Currently implemented:
+ *   - Windows (win32): calls focus-win.ts
+ *
+ * Unimplemented platforms always return false (no suppression).
+ */
+
+import { isWindowFocusedOnWindows } from "./focus-win.js";
+
+/**
+ * Check whether the current terminal/console window is the foreground
+ * (active) window. Used by sendNativeNotification to optionally
+ * suppress notifications when the user is already looking at the screen.
+ *
+ * @returns true if the terminal is the foreground window, false otherwise.
+ *          On unimplemented platforms, always returns false.
+ */
+export async function isWindowFocused(): Promise<boolean> {
+  switch (process.platform) {
+    case "win32":
+      return await isWindowFocusedOnWindows();
+    // TODO: macOS — use osascript to check frontmost application
+    // TODO: Linux — use xdotool (X11) or per-compositor tool (Wayland)
+    default:
+      return false;
+  }
+}

package/platforms/native.ts

@@ -8,22 +8,54 @@
  */
 
 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.
- * Resolves when notification is shown, rejects on error.
+ *
+ * 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(
       {

package/settings.ts

@@ -30,6 +30,7 @@ export const DEFAULT_CONFIG: NotifyConfig = {
   },
   native: {
     enabled: true,
+    suppressWhenFocused: false,
   },
   gotify: {
     enabled: false,

package/tui/settings-overlay.ts

@@ -85,7 +85,7 @@ export class NotifySettingsOverlay implements Component {
   }
 
   private get maxItems(): number {
-    if (this.section === "platforms") return 4; // native, gotify, telegram, ntfy
+    if (this.section === "platforms") return 5; // native, gotify, telegram, ntfy + suppress option
     if (this.section === "recap") return 1; // toggle
     return Object.keys(this.config.events).length;
   }
@@ -98,12 +98,17 @@ export class NotifySettingsOverlay implements Component {
         "telegram",
         "ntfy",
       ];
-      const key = platforms[this.selectedIndex];
-      if (key === "ntfy") {
-        // ntfy toggle updates the resolved ntfy config
-        this.ntfyConfig.enabled = !this.ntfyConfig.enabled;
-      } else if (key) {
-        this.config[key].enabled = !this.config[key].enabled;
+      if (this.selectedIndex < platforms.length) {
+        const key = platforms[this.selectedIndex];
+        if (key === "ntfy") {
+          // ntfy toggle updates the resolved ntfy config
+          this.ntfyConfig.enabled = !this.ntfyConfig.enabled;
+        } else if (key) {
+          this.config[key].enabled = !this.config[key].enabled;
+        }
+      } else {
+        // suppressWhenFocused toggle (index 4)
+        this.config.native.suppressWhenFocused = !this.config.native.suppressWhenFocused;
       }
     } else if (this.section === "recap") {
       this.config.recap.enabled = !this.config.recap.enabled;
@@ -273,6 +278,27 @@ export class NotifySettingsOverlay implements Component {
         )
       );
     }
+
+    // suppressWhenFocused toggle (index 4)
+    {
+      const i = platforms.length;
+      const isSelected = i === this.selectedIndex;
+      const isEnabled = this.config.native.suppressWhenFocused === true;
+      const toggleOn = this.fg("success", "●");
+      const toggleOff = this.fg("dim", "○");
+      const toggle = isEnabled ? toggleOn : toggleOff;
+      const label = isSelected
+        ? this.bold("Suppress when focused")
+        : this.fg("dim", "Suppress when focused");
+      const detail = this.fg("dim", isEnabled ? "Windows only — terminal in foreground → skip" : "Windows only");
+
+      lines.push(
+        this.frameLine(
+          `${isSelected ? this.fg("accent", "▸") : " "} ${toggle} ${label}  ${detail}`,
+          innerWidth
+        )
+      );
+    }
   }
 
   private renderEvents(lines: string[], innerWidth: number): void {

package/types.ts

@@ -19,6 +19,12 @@ export interface NativeConfig {
   enabled: boolean;
   /** 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 supported platforms
+   * (currently Windows). Default: false.
+   */
+  suppressWhenFocused?: boolean;
 }
 
 /** Gotify notification platform config */
@@ -101,6 +107,8 @@ export interface NotifyResult {
   platform: NotifyPlatform;
   /** Whether the send succeeded */
   success: boolean;
+  /** True when the notification was intentionally suppressed (e.g. window focused) */
+  suppressed?: boolean;
   /** Error message if failed */
   error?: string;
 }