@diegopetrucci/pi-extensions 0.1.8 → 0.1.9

package/README.md

@@ -10,7 +10,7 @@ A collection of [pi](https://github.com/badlogic/pi-mono) agent extensions I mad
 | [`oracle`](./extensions/oracle) | Adds an Amp-style read-only oracle tool that auto-selects the strongest reasoning model on the current provider/subscription, covers pi’s built-in providers with hardcoded rankings, sets reasoning to xhigh by default, and shows live status while running. |
 | [`permission-gate`](./extensions/permission-gate) | Prompts for confirmation before dangerous bash commands like `rm -rf`, `sudo`, and `chmod 777`. |
 | [`confirm-destructive`](./extensions/confirm-destructive) | Confirms before destructive session actions like clear, switch, and fork. |
-| [`notify`](./extensions/notify) | Sends a terminal or desktop notification when pi finishes and is ready for input. |
+| [`notify`](./extensions/notify) | Sends configurable terminal, desktop, bell, and sound notifications when pi finishes and is ready for input. |
 
 ## Install
 
@@ -25,7 +25,7 @@ pi install git:github.com/diegopetrucci/pi-extensions
 Or pin to a tagged version:
 
 ```bash
-pi install git:github.com/diegopetrucci/pi-extensions@v0.1.8
+pi install git:github.com/diegopetrucci/pi-extensions@v0.1.9
 ```
 
 ### npm

package/extensions/notify/README.md

@@ -1,14 +1,37 @@
 # notify
 
-A small pi extension that sends a terminal or desktop notification when the agent finishes and is waiting for input.
+A pi extension that sends notifications when the agent finishes and is waiting for input.
 
-This is adapted from the original `notify.ts` example in [`badlogic/pi-mono`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/examples/extensions/notify.ts) and kept basically the same.
+This started from the original `notify.ts` example in [`badlogic/pi-mono`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/examples/extensions/notify.ts), but now supports multiple notification channels and JSON configuration.
 
-## Supported notification backends
+## Supported notification channels
+
+### Terminal notifications
 
 - OSC 777: Ghostty, iTerm2, WezTerm, rxvt-unicode
 - OSC 99: Kitty
-- Windows toast: Windows Terminal / WSL
+
+### Desktop notifications
+
+- macOS Notification Center via `osascript`
+- Linux desktop notifications via `notify-send`
+- Windows toast notifications via `powershell.exe` / Windows Terminal / WSL
+
+### Bells and sounds
+
+- terminal bell (`\a`)
+- macOS sound playback via `afplay`
+- Linux sound playback via `canberra-gtk-play` or `paplay`
+- Windows beep via `powershell.exe`
+
+By default, all channels are enabled:
+
+- terminal notification
+- desktop notification
+- bell
+- sound
+
+The extension automatically picks the appropriate backend for the current environment.
 
 ## Install
 
@@ -36,8 +59,67 @@ Then reload pi:
 /reload
 ```
 
+## Configuration
+
+Config files are merged, with project config overriding global config:
+
+- `~/.pi/agent/extensions/notify.json`
+- `<project>/.pi/notify.json`
+
+A ready-to-copy sample file is included at [`notify.example.json`](./notify.example.json).
+
+Example:
+
+```json
+{
+  "enabled": true,
+  "onlyWhenInteractive": true,
+  "title": "Pi",
+  "body": "Ready for input",
+  "channels": {
+    "terminal": true,
+    "desktop": true,
+    "bell": true,
+    "sound": true
+  },
+  "terminal": {
+    "backend": "auto"
+  },
+  "desktop": {
+    "backend": "auto"
+  },
+  "sound": {
+    "backend": "auto",
+    "name": "Glass",
+    "linuxSoundId": "complete",
+    "frequencyHz": 1000,
+    "durationMs": 250,
+    "command": ""
+  }
+}
+```
+
+### Config fields
+
+- `enabled`: master on/off switch
+- `onlyWhenInteractive`: skip notifications in print / non-UI mode
+- `title`: notification title
+- `body`: notification body
+- `channels.terminal`: enable terminal notification output
+- `channels.desktop`: enable OS desktop notifications
+- `channels.bell`: enable terminal bell
+- `channels.sound`: enable sound playback
+- `terminal.backend`: `auto`, `osc777`, `osc99`, `none`
+- `desktop.backend`: `auto`, `macos`, `linux`, `windows-toast`, `none`
+- `sound.backend`: `auto`, `macos`, `linux`, `windows-beep`, `command`, `none`
+- `sound.name`: macOS system sound name, like `Glass` or `Hero`
+- `sound.linuxSoundId`: freedesktop sound id, like `complete`
+- `sound.frequencyHz`: Windows beep frequency
+- `sound.durationMs`: Windows beep duration
+- `sound.command`: custom shell command when `sound.backend` is `command`
+
 ## Notes
 
 - Hooks the `agent_end` event.
-- Sends `Pi` / `Ready for input` when the agent finishes.
-- Chooses the notification backend from the current terminal environment.
+- Default message is `Pi` / `Ready for input`.
+- Terminal, desktop, bell, and sound channels can be enabled independently.

package/extensions/notify/index.ts

@@ -1,14 +1,125 @@
 /**
  * Pi Notify Extension
  *
- * Sends a native terminal notification when Pi agent is done and waiting for input.
- * Supports multiple terminal protocols:
- * - OSC 777: Ghostty, iTerm2, WezTerm, rxvt-unicode
- * - OSC 99: Kitty
- * - Windows toast: Windows Terminal (WSL)
+ * Sends notifications when Pi agent is done and waiting for input.
+ * Supports multiple channels:
+ * - terminal notifications: OSC 777 and OSC 99
+ * - desktop notifications: macOS Notification Center, Linux notify-send, Windows toast
+ * - terminal bell
+ * - sound playback
+ *
+ * Config files (project overrides global):
+ * - ~/.pi/agent/extensions/notify.json
+ * - <cwd>/.pi/notify.json
  */
 
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+
+type TerminalBackend = "auto" | "osc777" | "osc99" | "none";
+type DesktopBackend = "auto" | "macos" | "linux" | "windows-toast" | "none";
+type SoundBackend = "auto" | "macos" | "linux" | "windows-beep" | "command" | "none";
+
+interface NotifyConfig {
+	enabled: boolean;
+	onlyWhenInteractive: boolean;
+	title: string;
+	body: string;
+	channels: {
+		terminal: boolean;
+		desktop: boolean;
+		bell: boolean;
+		sound: boolean;
+	};
+	terminal: {
+		backend: TerminalBackend;
+	};
+	desktop: {
+		backend: DesktopBackend;
+	};
+	sound: {
+		backend: SoundBackend;
+		name: string;
+		linuxSoundId: string;
+		frequencyHz: number;
+		durationMs: number;
+		command: string;
+	};
+}
+
+const DEFAULT_CONFIG: NotifyConfig = {
+	enabled: true,
+	onlyWhenInteractive: true,
+	title: "Pi",
+	body: "Ready for input",
+	channels: {
+		terminal: true,
+		desktop: true,
+		bell: true,
+		sound: true,
+	},
+	terminal: {
+		backend: "auto",
+	},
+	desktop: {
+		backend: "auto",
+	},
+	sound: {
+		backend: "auto",
+		name: "Glass",
+		linuxSoundId: "complete",
+		frequencyHz: 1000,
+		durationMs: 250,
+		command: "",
+	},
+};
+
+function readConfigFile(path: string): Partial<NotifyConfig> {
+	if (!existsSync(path)) return {};
+
+	try {
+		return JSON.parse(readFileSync(path, "utf-8")) as Partial<NotifyConfig>;
+	} catch (error) {
+		console.error(`Warning: Could not parse ${path}: ${error}`);
+		return {};
+	}
+}
+
+function mergeConfig(base: NotifyConfig, overrides: Partial<NotifyConfig>): NotifyConfig {
+	return {
+		...base,
+		...overrides,
+		channels: {
+			...base.channels,
+			...overrides.channels,
+		},
+		terminal: {
+			...base.terminal,
+			...overrides.terminal,
+		},
+		desktop: {
+			...base.desktop,
+			...overrides.desktop,
+		},
+		sound: {
+			...base.sound,
+			...overrides.sound,
+		},
+	};
+}
+
+function loadConfig(cwd: string): NotifyConfig {
+	const globalConfig = readConfigFile(join(getAgentDir(), "extensions", "notify.json"));
+	const projectConfig = readConfigFile(join(cwd, ".pi", "notify.json"));
+	return mergeConfig(mergeConfig(DEFAULT_CONFIG, globalConfig), projectConfig);
+}
+
+function powershellString(value: string): string {
+	return `'${value.replace(/'/g, "''")}'`;
+}
 
 function windowsToastScript(title: string, body: string): string {
 	const type = "Windows.UI.Notifications";
@@ -18,8 +129,8 @@ function windowsToastScript(title: string, body: string): string {
 	return [
 		`${mgr} > $null`,
 		`$xml = [${type}.ToastNotificationManager]::GetTemplateContent(${template})`,
-		`$xml.GetElementsByTagName('text')[0].AppendChild($xml.CreateTextNode('${body}')) > $null`,
-		`[${type}.ToastNotificationManager]::CreateToastNotifier('${title}').Show(${toast})`,
+		`$xml.GetElementsByTagName('text')[0].AppendChild($xml.CreateTextNode(${powershellString(body)})) > $null`,
+		`[${type}.ToastNotificationManager]::CreateToastNotifier(${powershellString(title)}).Show(${toast})`,
 	].join("; ");
 }
 
@@ -28,28 +139,136 @@ function notifyOSC777(title: string, body: string): void {
 }
 
 function notifyOSC99(title: string, body: string): void {
-	// Kitty OSC 99: i=notification id, d=0 means not done yet, p=body for second part
 	process.stdout.write(`\x1b]99;i=1:d=0;${title}\x1b\\`);
 	process.stdout.write(`\x1b]99;i=1:p=body;${body}\x1b\\`);
 }
 
-function notifyWindows(title: string, body: string): void {
-	const { execFile } = require("child_process");
-	execFile("powershell.exe", ["-NoProfile", "-Command", windowsToastScript(title, body)]);
+function ringBell(): void {
+	process.stdout.write("\x07");
+}
+
+function runCommand(command: string, args: string[]): Promise<boolean> {
+	return new Promise((resolve) => {
+		execFile(command, args, (error) => resolve(!error));
+	});
+}
+
+function runShellCommand(command: string): Promise<boolean> {
+	if (process.platform === "win32") {
+		return runCommand("cmd.exe", ["/d", "/s", "/c", command]);
+	}
+
+	return runCommand(process.env.SHELL || "/bin/sh", ["-lc", command]);
+}
+
+function detectTerminalBackend(config: NotifyConfig): Exclude<TerminalBackend, "auto"> {
+	if (config.terminal.backend !== "auto") return config.terminal.backend;
+	if (process.env.KITTY_WINDOW_ID) return "osc99";
+	return "osc777";
+}
+
+function detectDesktopBackend(config: NotifyConfig): Exclude<DesktopBackend, "auto"> {
+	if (config.desktop.backend !== "auto") return config.desktop.backend;
+	if (process.env.WT_SESSION || process.env.WSL_DISTRO_NAME) return "windows-toast";
+	if (process.platform === "darwin") return "macos";
+	if (process.platform === "linux") return "linux";
+	if (process.platform === "win32") return "windows-toast";
+	return "none";
 }
 
-function notify(title: string, body: string): void {
-	if (process.env.WT_SESSION) {
-		notifyWindows(title, body);
-	} else if (process.env.KITTY_WINDOW_ID) {
+function detectSoundBackend(config: NotifyConfig): Exclude<SoundBackend, "auto"> {
+	if (config.sound.backend !== "auto") return config.sound.backend;
+	if (process.env.WT_SESSION || process.platform === "win32" || process.env.WSL_DISTRO_NAME) return "windows-beep";
+	if (process.platform === "darwin") return "macos";
+	if (process.platform === "linux") return "linux";
+	return "none";
+}
+
+function sendTerminalNotification(title: string, body: string, backend: Exclude<TerminalBackend, "auto">): void {
+	if (backend === "osc99") {
 		notifyOSC99(title, body);
-	} else {
+		return;
+	}
+	if (backend === "osc777") {
 		notifyOSC777(title, body);
 	}
 }
 
-export default function (pi: ExtensionAPI) {
-	pi.on("agent_end", async () => {
-		notify("Pi", "Ready for input");
+function appleScriptString(value: string): string {
+	return JSON.stringify(value);
+}
+
+function sendDesktopNotification(
+	title: string,
+	body: string,
+	backend: Exclude<DesktopBackend, "auto">,
+): Promise<boolean> {
+	if (backend === "windows-toast") {
+		return runCommand("powershell.exe", ["-NoProfile", "-Command", windowsToastScript(title, body)]);
+	}
+	if (backend === "macos") {
+		return runCommand("osascript", ["-e", `display notification ${appleScriptString(body)} with title ${appleScriptString(title)}`]);
+	}
+	if (backend === "linux") {
+		return runCommand("notify-send", [title, body]);
+	}
+	return Promise.resolve(false);
+}
+
+async function playSound(config: NotifyConfig, backend: Exclude<SoundBackend, "auto">): Promise<boolean> {
+	if (backend === "command") {
+		if (!config.sound.command.trim()) return false;
+		return runShellCommand(config.sound.command);
+	}
+
+	if (backend === "windows-beep") {
+		return runCommand("powershell.exe", [
+			"-NoProfile",
+			"-Command",
+			`[console]::beep(${config.sound.frequencyHz}, ${config.sound.durationMs})`,
+		]);
+	}
+
+	if (backend === "macos") {
+		return runCommand("afplay", [`/System/Library/Sounds/${config.sound.name}.aiff`]);
+	}
+
+	if (backend === "linux") {
+		const soundId = config.sound.linuxSoundId;
+		const viaCanberra = await runCommand("canberra-gtk-play", ["-i", soundId]);
+		if (viaCanberra) return true;
+		return runCommand("paplay", [`/usr/share/sounds/freedesktop/stereo/${soundId}.oga`]);
+	}
+
+	return false;
+}
+
+export default function notifyExtension(pi: ExtensionAPI) {
+	pi.on("agent_end", async (_event, ctx) => {
+		const config = loadConfig(ctx.cwd);
+		if (!config.enabled) return;
+		if (config.onlyWhenInteractive && !ctx.hasUI) return;
+
+		const tasks: Array<Promise<unknown>> = [];
+
+		if (config.channels.terminal) {
+			sendTerminalNotification(config.title, config.body, detectTerminalBackend(config));
+		}
+
+		if (config.channels.desktop) {
+			tasks.push(sendDesktopNotification(config.title, config.body, detectDesktopBackend(config)));
+		}
+
+		if (config.channels.bell) {
+			ringBell();
+		}
+
+		if (config.channels.sound) {
+			tasks.push(playSound(config, detectSoundBackend(config)));
+		}
+
+		if (tasks.length > 0) {
+			await Promise.allSettled(tasks);
+		}
 	});
 }

package/extensions/notify/notify.example.json

@@ -0,0 +1,26 @@
+{
+  "enabled": true,
+  "onlyWhenInteractive": true,
+  "title": "Pi",
+  "body": "Ready for input",
+  "channels": {
+    "terminal": true,
+    "desktop": true,
+    "bell": true,
+    "sound": true
+  },
+  "terminal": {
+    "backend": "auto"
+  },
+  "desktop": {
+    "backend": "auto"
+  },
+  "sound": {
+    "backend": "auto",
+    "name": "Glass",
+    "linuxSoundId": "complete",
+    "frequencyHz": 1000,
+    "durationMs": 250,
+    "command": ""
+  }
+}

package/extensions/notify/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegopetrucci/pi-notify",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A pi extension that sends a notification when the agent is ready for input.",
   "keywords": ["pi-package", "pi", "notification", "terminal"],
   "license": "MIT",
@@ -11,7 +11,8 @@
   },
   "files": [
     "index.ts",
-    "README.md"
+    "README.md",
+    "notify.example.json"
   ],
   "publishConfig": {
     "access": "public"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegopetrucci/pi-extensions",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "A collection of pi extensions, including a minimal custom footer, an Amp-style oracle, a permission gate for dangerous bash commands, confirm-before-destructive session actions, and terminal notifications when pi is ready for input.",
   "keywords": ["pi-package", "pi", "terminal", "agent"],
   "license": "MIT",