@diegopetrucci/pi-extensions 0.1.7 → 0.1.9

package/README.md

@@ -10,6 +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 configurable terminal, desktop, bell, and sound notifications when pi finishes and is ready for input. |
 
 ## Install
 
@@ -24,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.7
+pi install git:github.com/diegopetrucci/pi-extensions@v0.1.9
 ```
 
 ### npm
@@ -63,6 +64,10 @@ pi install npm:@diegopetrucci/pi-permission-gate
 pi install npm:@diegopetrucci/pi-confirm-destructive
 ```
 
+```bash
+pi install npm:@diegopetrucci/pi-notify
+```
+
 ### Option 2: filter the repo package
 
 If you prefer the collection package, you can filter it in your pi settings.
@@ -119,9 +124,22 @@ Confirm destructive only:
 }
 ```
 
+Notify only:
+
+```json
+{
+  "packages": [
+    {
+      "source": "npm:@diegopetrucci/pi-extensions",
+      "extensions": ["extensions/notify/index.ts"]
+    }
+  ]
+}
+```
+
 ## npm publishing
 
 The repo is set up to support both:
 
 - the collection package: `@diegopetrucci/pi-extensions`
-- standalone extension packages like `@diegopetrucci/pi-minimal-footer`, `@diegopetrucci/pi-oracle`, `@diegopetrucci/pi-permission-gate`, and `@diegopetrucci/pi-confirm-destructive`
+- standalone extension packages like `@diegopetrucci/pi-minimal-footer`, `@diegopetrucci/pi-oracle`, `@diegopetrucci/pi-permission-gate`, `@diegopetrucci/pi-confirm-destructive`, and `@diegopetrucci/pi-notify`

package/extensions/notify/README.md

@@ -0,0 +1,125 @@
+# notify
+
+A pi extension that sends notifications when the agent finishes and is waiting for input.
+
+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 channels
+
+### Terminal notifications
+
+- OSC 777: Ghostty, iTerm2, WezTerm, rxvt-unicode
+- OSC 99: Kitty
+
+### 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
+
+### Standalone npm package
+
+```bash
+pi install npm:@diegopetrucci/pi-notify
+```
+
+### Collection package
+
+```bash
+pi install npm:@diegopetrucci/pi-extensions
+```
+
+### GitHub package
+
+```bash
+pi install git:github.com/diegopetrucci/pi-extensions
+```
+
+Then reload pi:
+
+```text
+/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.
+- Default message is `Pi` / `Ready for input`.
+- Terminal, desktop, bell, and sound channels can be enabled independently.

package/extensions/notify/index.ts

@@ -0,0 +1,274 @@
+/**
+ * Pi Notify Extension
+ *
+ * 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";
+	const mgr = `[${type}.ToastNotificationManager, ${type}, ContentType = WindowsRuntime]`;
+	const template = `[${type}.ToastTemplateType]::ToastText01`;
+	const toast = `[${type}.ToastNotification]::new($xml)`;
+	return [
+		`${mgr} > $null`,
+		`$xml = [${type}.ToastNotificationManager]::GetTemplateContent(${template})`,
+		`$xml.GetElementsByTagName('text')[0].AppendChild($xml.CreateTextNode(${powershellString(body)})) > $null`,
+		`[${type}.ToastNotificationManager]::CreateToastNotifier(${powershellString(title)}).Show(${toast})`,
+	].join("; ");
+}
+
+function notifyOSC777(title: string, body: string): void {
+	process.stdout.write(`\x1b]777;notify;${title};${body}\x07`);
+}
+
+function notifyOSC99(title: string, body: string): void {
+	process.stdout.write(`\x1b]99;i=1:d=0;${title}\x1b\\`);
+	process.stdout.write(`\x1b]99;i=1:p=body;${body}\x1b\\`);
+}
+
+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 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);
+		return;
+	}
+	if (backend === "osc777") {
+		notifyOSC777(title, body);
+	}
+}
+
+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

@@ -0,0 +1,28 @@
+{
+  "name": "@diegopetrucci/pi-notify",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/diegopetrucci/pi-extensions.git",
+    "directory": "extensions/notify"
+  },
+  "files": [
+    "index.ts",
+    "README.md",
+    "notify.example.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@diegopetrucci/pi-extensions",
-  "version": "0.1.7",
-  "description": "A collection of pi extensions, including a minimal custom footer, an Amp-style oracle, a permission gate for dangerous bash commands, and confirm-before-destructive session actions.",
+  "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",
   "repository": {
@@ -29,7 +29,8 @@
       "./extensions/minimal-footer/index.ts",
       "./extensions/oracle/index.ts",
       "./extensions/permission-gate/index.ts",
-      "./extensions/confirm-destructive/index.ts"
+      "./extensions/confirm-destructive/index.ts",
+      "./extensions/notify/index.ts"
     ],
     "image": "https://raw.githubusercontent.com/diegopetrucci/pi-extensions/main/assets/oracle-preview.svg"
   }