osdy-pi 0.1.5 → 0.1.7

package/README.md

@@ -15,6 +15,7 @@ Visit the Osdy landing page: [landing-osdy.vercel.app](https://landing-osdy.verc
 - **Custom editor:** full-width framed input area with model, thinking, token, cost, and context status.
 - **Custom working indicator:** a dedicated working widget/spinner appears above the text box, outside the editor frame.
 - **Clean layout:** the built-in working row is hidden while Osdy Pi is enabled to avoid duplicated UI.
+- **Optional audio notifications:** configurable `.mp3`/`.wav` files for `completion`, `error`, `permission`, and `question` events on macOS and Windows.
 
 <img width="1280" height="433" alt="image" src="https://github.com/user-attachments/assets/20c7624d-9ad8-4494-97fb-6b6d81aaf328" />
 
@@ -74,6 +75,7 @@ Osdy Pi includes a small command group:
 /osdy-pi enable
 /osdy-pi disable
 /osdy-pi status
+/osdy-pi sound setup
 /osdy-pi osdy-theme
 /osdy-pi classic
 /osdy-pi-osdy-theme
@@ -83,12 +85,79 @@ Osdy Pi includes a small command group:
 - `enable` applies the dark Osdy theme, custom header, custom editor, and clean layout.
 - `disable` restores Pi's built-in header, editor, footer, and working visibility, then switches back to the previous theme or `dark`.
 - `status` shows whether the Osdy Pi UI is currently enabled, including the active style.
+- `sound setup` opens the guided global sound-setup wizard for audio notifications.
 - `osdy-theme` is the default OsdyTheme header with pink, cyan, and purple styling, plus the mascot glow on the right edge.
 - `classic` keeps the previous classic header shape with the shared mascot.
 - `/osdy-pi-osdy-theme` and `/osdy-pi-classic` are direct aliases.
 
 After changing a local extension, run `/reload` or restart Pi so the updated commands are registered.
 
+## Audio notifications
+
+Osdy Pi can play your own sound files for these product-level events:
+
+- `completion`: the full orchestrator flow finishes and Pi returns control to input.
+- `error`: a real tool execution failure occurs during the flow.
+- `permission`: reserved for future explicit Pi approval hooks, dormant by default today.
+- `question`: reserved for future explicit Pi question hooks, dormant by default today.
+
+Initial audio playback support is implemented for:
+
+- macOS
+- Windows
+
+Unsupported platforms fall back safely without crashing Osdy Pi.
+
+### Supported files
+
+Only readable `.mp3` and `.wav` files are accepted.
+
+### Configure sounds
+
+The preferred setup path is the guided Osdy Pi wizard:
+
+```text
+/osdy-pi sound setup
+```
+
+The wizard:
+
+- walks through `completion`, `error`, `permission`, and `question`;
+- lets you keep, replace, clear, or skip each event;
+- validates every selected path before save;
+- blocks save if any selected file is missing, unreadable, not a regular file, or not `.mp3`/`.wav`;
+- stores accepted settings globally at `~/.pi/agent/extensions/osdy-pi/audio-notifications.json` (or `$PI_CODING_AGENT_DIR/extensions/osdy-pi/audio-notifications.json` when that env var is set).
+
+Saved global sound paths apply across restarts and projects that use Osdy Pi.
+
+### Startup flags still work
+
+You can still pass sound paths as Pi flags when starting the session:
+
+```bash
+pi \
+  --osdy-pi-sound-completion /absolute/path/completion.wav \
+  --osdy-pi-sound-error /absolute/path/error.mp3 \
+  --osdy-pi-sound-permission /absolute/path/permission.wav \
+  --osdy-pi-sound-question /absolute/path/question.wav
+```
+
+Precedence is per event:
+
+1. startup flag
+2. saved global Osdy Pi setting
+3. unconfigured
+
+Notes:
+
+- Empty or omitted flags mean that event does not override the saved global setting.
+- Relative startup-flag paths resolve from the current working directory.
+- The setup wizard saves normalized absolute paths for global settings.
+- `~` expands to your home directory.
+- Invalid, unreadable, or unsupported files are skipped at playback time without changing existing UI behavior.
+- If a file was valid when saved but later disappears or becomes unreadable, Osdy Pi fails safely and skips playback for that event.
+- Audio notifications and sound setup are additive only, they do not change the current header, editor, footer, working indicator, theme, or commands.
+
 ## Local install
 
 If you cloned this repository and want to test it locally:

package/extensions/osdy-pi/audio-event-router.ts

@@ -0,0 +1,44 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AudioNotificationService } from "./audio-notification-service.js";
+
+export type AudioEventRouter = {
+	onAgentStart(): void;
+	onAgentEnd(ctx: ExtensionContext): void;
+	onToolExecutionEnd(isError: boolean, ctx: ExtensionContext): void;
+	onPermissionRequested(ctx: ExtensionContext): void;
+	onQuestionRequested(ctx: ExtensionContext): void;
+};
+
+class DefaultAudioEventRouter implements AudioEventRouter {
+	private errorNotified = false;
+
+	constructor(private readonly notificationService: AudioNotificationService) {}
+
+	onAgentStart(): void {
+		this.errorNotified = false;
+	}
+
+	onAgentEnd(ctx: ExtensionContext): void {
+		this.notificationService.notify("completion", ctx);
+	}
+
+	onToolExecutionEnd(isError: boolean, ctx: ExtensionContext): void {
+		if (!isError || this.errorNotified) return;
+		this.errorNotified = true;
+		this.notificationService.notify("error", ctx);
+	}
+
+	onPermissionRequested(ctx: ExtensionContext): void {
+		this.notificationService.notify("permission", ctx);
+	}
+
+	onQuestionRequested(ctx: ExtensionContext): void {
+		this.notificationService.notify("question", ctx);
+	}
+}
+
+export function createAudioEventRouter(
+	notificationService: AudioNotificationService,
+): AudioEventRouter {
+	return new DefaultAudioEventRouter(notificationService);
+}

package/extensions/osdy-pi/audio-notification-config.ts

@@ -0,0 +1,194 @@
+import { access, constants, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { AudioSoundSettingsStore } from "./audio-sound-settings.js";
+import {
+	AUDIO_NOTIFICATION_EVENTS,
+	AUDIO_NOTIFICATION_FLAG_NAMES,
+	type AudioNotificationConfig,
+	type AudioNotificationEvent,
+	type AudioPathValidationResult,
+	type EffectiveAudioNotificationPath,
+	type GlobalAudioNotificationSettings,
+	type ResolvedSoundFile,
+} from "./audio-notification-types.js";
+
+const SUPPORTED_AUDIO_EXTENSIONS = new Set([".mp3", ".wav"]);
+
+type ValidationMode = "startup-flag" | "global-save" | "global-runtime";
+
+function normalizeConfiguredValue(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function expandHomeDir(inputPath: string): string {
+	if (inputPath === "~") return os.homedir();
+	if (inputPath.startsWith("~/") || inputPath.startsWith("~\\")) {
+		return path.join(os.homedir(), inputPath.slice(2));
+	}
+	return inputPath;
+}
+
+function hasSupportedExtension(filePath: string): boolean {
+	return SUPPORTED_AUDIO_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+}
+
+function resolvePathForMode(
+	inputPath: string,
+	cwd: string,
+	mode: ValidationMode,
+): string | undefined {
+	const expandedPath = expandHomeDir(inputPath);
+	if (path.isAbsolute(expandedPath)) {
+		return path.normalize(expandedPath);
+	}
+	if (mode === "global-runtime") {
+		return undefined;
+	}
+	return path.resolve(cwd, expandedPath);
+}
+
+async function checkReadableFile(
+	resolvedPath: string,
+): Promise<AudioPathValidationResult> {
+	if (!hasSupportedExtension(resolvedPath)) {
+		return { ok: false, reason: "unsupported-extension" };
+	}
+	try {
+		const fileInfo = await stat(resolvedPath);
+		if (!fileInfo.isFile()) {
+			return { ok: false, reason: "not-file" };
+		}
+	} catch {
+		return { ok: false, reason: "missing" };
+	}
+	try {
+		await access(resolvedPath, constants.R_OK);
+	} catch {
+		return { ok: false, reason: "unreadable" };
+	}
+	return {
+		ok: true,
+		inputPath: resolvedPath,
+		resolvedPath,
+		persistedPath: resolvedPath,
+	};
+}
+
+export async function validateAudioNotificationPath(
+	inputPath: string | undefined,
+	options: { cwd: string; mode: ValidationMode },
+): Promise<AudioPathValidationResult> {
+	const normalizedPath = normalizeConfiguredValue(inputPath);
+	if (normalizedPath === undefined) {
+		return { ok: false, reason: "unconfigured" };
+	}
+	const resolvedPath = resolvePathForMode(
+		normalizedPath,
+		options.cwd,
+		options.mode,
+	);
+	if (resolvedPath === undefined) {
+		return { ok: false, reason: "relative-global-path" };
+	}
+	const fileCheck = await checkReadableFile(resolvedPath);
+	if (!fileCheck.ok) {
+		return fileCheck;
+	}
+	return {
+		ok: true,
+		inputPath: normalizedPath,
+		resolvedPath,
+		persistedPath:
+			options.mode === "startup-flag" ? normalizedPath : resolvedPath,
+	};
+}
+
+function getStartupFlagConfig(pi: ExtensionAPI): AudioNotificationConfig {
+	const config: AudioNotificationConfig = {};
+	for (const event of AUDIO_NOTIFICATION_EVENTS) {
+		const value = normalizeConfiguredValue(
+			pi.getFlag(AUDIO_NOTIFICATION_FLAG_NAMES[event]),
+		);
+		if (value !== undefined) {
+			config[event] = value;
+		}
+	}
+	return config;
+}
+
+export function registerAudioNotificationFlags(pi: ExtensionAPI): void {
+	for (const event of AUDIO_NOTIFICATION_EVENTS) {
+		pi.registerFlag(AUDIO_NOTIFICATION_FLAG_NAMES[event], {
+			description: `Path to the ${event} notification sound (.mp3 or .wav)`,
+			type: "string",
+			default: "",
+		});
+	}
+}
+
+export function getEffectiveAudioNotificationPath(
+	pi: ExtensionAPI,
+	globalSettings: GlobalAudioNotificationSettings,
+	event: AudioNotificationEvent,
+): EffectiveAudioNotificationPath {
+	const startupFlags = getStartupFlagConfig(pi);
+	const startupPath = startupFlags[event];
+	if (startupPath !== undefined) {
+		return { source: "startup-flag", path: startupPath };
+	}
+	const globalPath = normalizeConfiguredValue(globalSettings.sounds[event]);
+	if (globalPath !== undefined) {
+		return { source: "global", path: globalPath };
+	}
+	return { source: "unconfigured" };
+}
+
+export async function resolveAudioNotificationSound(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	event: AudioNotificationEvent,
+	settingsStore: AudioSoundSettingsStore,
+): Promise<ResolvedSoundFile> {
+	const globalSettings = await settingsStore.load();
+	const effectivePath = getEffectiveAudioNotificationPath(
+		pi,
+		globalSettings,
+		event,
+	);
+	if (effectivePath.source === "unconfigured") {
+		return { ok: false, event, reason: "unconfigured", source: "unconfigured" };
+	}
+	const validationMode: ValidationMode =
+		effectivePath.source === "startup-flag" ? "startup-flag" : "global-runtime";
+	const validatedPath = await validateAudioNotificationPath(
+		effectivePath.path,
+		{
+			cwd: ctx.cwd,
+			mode: validationMode,
+		},
+	);
+	if (!validatedPath.ok) {
+		return {
+			ok: false,
+			event,
+			reason:
+				validatedPath.reason === "unsupported-extension"
+					? "unsupported-extension"
+					: "missing-or-unreadable",
+			source: effectivePath.source,
+		};
+	}
+	return {
+		ok: true,
+		event,
+		path: validatedPath.resolvedPath,
+		source: effectivePath.source,
+	};
+}

package/extensions/osdy-pi/audio-notification-service.ts

@@ -0,0 +1,58 @@
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { AudioSoundSettingsStore } from "./audio-sound-settings.js";
+import { resolveAudioNotificationSound } from "./audio-notification-config.js";
+import type { AudioNotificationEvent } from "./audio-notification-types.js";
+import type { AudioPlaybackAdapter } from "./audio-playback.js";
+
+export type AudioNotificationService = {
+	notify(event: AudioNotificationEvent, ctx: ExtensionContext): void;
+};
+
+class DefaultAudioNotificationService implements AudioNotificationService {
+	private readonly inFlightEvents = new Set<AudioNotificationEvent>();
+
+	constructor(
+		private readonly pi: ExtensionAPI,
+		private readonly playbackAdapter: AudioPlaybackAdapter,
+		private readonly settingsStore: AudioSoundSettingsStore,
+	) {}
+
+	notify(event: AudioNotificationEvent, ctx: ExtensionContext): void {
+		if (this.inFlightEvents.has(event)) return;
+		this.inFlightEvents.add(event);
+		void this.play(event, ctx)
+			.catch(() => undefined)
+			.finally(() => {
+				this.inFlightEvents.delete(event);
+			});
+	}
+
+	private async play(
+		event: AudioNotificationEvent,
+		ctx: ExtensionContext,
+	): Promise<void> {
+		const resolvedSound = await resolveAudioNotificationSound(
+			this.pi,
+			ctx,
+			event,
+			this.settingsStore,
+		);
+		if (!resolvedSound.ok) return;
+		await this.playbackAdapter.play(resolvedSound.path);
+	}
+}
+
+export function createAudioNotificationService(
+	pi: ExtensionAPI,
+	playbackAdapter: AudioPlaybackAdapter,
+	settingsStore: AudioSoundSettingsStore,
+): AudioNotificationService {
+	return new DefaultAudioNotificationService(
+		pi,
+		playbackAdapter,
+		settingsStore,
+	);
+}

package/extensions/osdy-pi/audio-notification-types.ts

@@ -0,0 +1,76 @@
+export const AUDIO_NOTIFICATION_EVENTS = [
+	"completion",
+	"error",
+	"permission",
+	"question",
+] as const;
+
+export type AudioNotificationEvent = (typeof AUDIO_NOTIFICATION_EVENTS)[number];
+
+export const AUDIO_NOTIFICATION_FLAG_NAMES: Record<
+	AudioNotificationEvent,
+	string
+> = {
+	completion: "osdy-pi-sound-completion",
+	error: "osdy-pi-sound-error",
+	permission: "osdy-pi-sound-permission",
+	question: "osdy-pi-sound-question",
+};
+
+export type AudioNotificationConfig = Partial<
+	Record<AudioNotificationEvent, string>
+>;
+
+export type GlobalAudioNotificationSettings = {
+	version: 1;
+	sounds: AudioNotificationConfig;
+};
+
+export type AudioConfigSource = "startup-flag" | "global" | "unconfigured";
+
+export type ResolvedSoundFile =
+	| {
+			ok: true;
+			event: AudioNotificationEvent;
+			path: string;
+			source: Exclude<AudioConfigSource, "unconfigured">;
+	  }
+	| {
+			ok: false;
+			event: AudioNotificationEvent;
+			reason:
+				| "unconfigured"
+				| "unsupported-extension"
+				| "missing-or-unreadable";
+			source: AudioConfigSource;
+	  };
+
+export type AudioPathValidationReason =
+	| "unconfigured"
+	| "unsupported-extension"
+	| "missing"
+	| "unreadable"
+	| "not-file"
+	| "relative-global-path";
+
+export type AudioPathValidationResult =
+	| {
+			ok: true;
+			inputPath: string;
+			resolvedPath: string;
+			persistedPath: string;
+	  }
+	| {
+			ok: false;
+			reason: AudioPathValidationReason;
+	  };
+
+export type EffectiveAudioNotificationPath =
+	| {
+			source: Exclude<AudioConfigSource, "unconfigured">;
+			path: string;
+	  }
+	| {
+			source: "unconfigured";
+			path?: undefined;
+	  };

package/extensions/osdy-pi/audio-playback-macos.ts

@@ -0,0 +1,36 @@
+import { spawn } from "node:child_process";
+import type { AudioPlaybackAdapter } from "./audio-playback.js";
+
+function runProcess(command: string, args: string[]): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			stdio: ["ignore", "ignore", "pipe"],
+		});
+
+		let stderr = "";
+		child.stderr.on("data", (chunk: Buffer | string) => {
+			stderr += chunk.toString();
+		});
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			reject(
+				new Error(
+					stderr.trim() || `${command} exited with code ${code ?? "unknown"}`,
+				),
+			);
+		});
+	});
+}
+
+export function createMacOsAudioPlaybackAdapter(): AudioPlaybackAdapter {
+	return {
+		platform: "darwin",
+		play(soundPath: string): Promise<void> {
+			return runProcess("afplay", [soundPath]);
+		},
+	};
+}

package/extensions/osdy-pi/audio-playback-unsupported.ts

@@ -0,0 +1,8 @@
+import type { AudioPlaybackAdapter } from "./audio-playback.js";
+
+export function createUnsupportedAudioPlaybackAdapter(): AudioPlaybackAdapter {
+	return {
+		platform: "unsupported",
+		play: () => Promise.resolve(),
+	};
+}

package/extensions/osdy-pi/audio-playback-windows.ts

@@ -0,0 +1,86 @@
+import { spawn } from "node:child_process";
+import type { AudioPlaybackAdapter } from "./audio-playback.js";
+
+const WINDOWS_AUDIO_TIMEOUT_MS = 15_000;
+
+const WINDOWS_AUDIO_SCRIPT = [
+	"$path = $env:OSDY_PI_SOUND_PATH",
+	'if ([string]::IsNullOrWhiteSpace($path)) { throw "Missing sound path" }',
+	"$player = New-Object -ComObject WMPlayer.OCX",
+	"$player.settings.volume = 100",
+	"$player.URL = $path",
+	"$player.controls.play()",
+	"while ($true) {",
+	"  $state = $player.playState",
+	"  if ($state -eq 1 -or $state -eq 8 -or $state -eq 10) { break }",
+	"  Start-Sleep -Milliseconds 100",
+	"}",
+].join("\n");
+
+function encodePowerShellScript(script: string): string {
+	return Buffer.from(script, "utf16le").toString("base64");
+}
+
+function runPowerShell(script: string, soundPath: string): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const child = spawn(
+			"powershell.exe",
+			[
+				"-NoProfile",
+				"-NonInteractive",
+				"-ExecutionPolicy",
+				"Bypass",
+				"-EncodedCommand",
+				encodePowerShellScript(script),
+			],
+			{
+				stdio: ["ignore", "ignore", "pipe"],
+				env: { ...process.env, OSDY_PI_SOUND_PATH: soundPath },
+			},
+		);
+
+		let stderr = "";
+		let settled = false;
+		const timeout = setTimeout(() => {
+			if (settled) return;
+			settled = true;
+			child.kill();
+			reject(new Error("powershell audio playback timed out"));
+		}, WINDOWS_AUDIO_TIMEOUT_MS);
+		const finish = (callback: () => void) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			callback();
+		};
+
+		child.stderr.on("data", (chunk: Buffer | string) => {
+			stderr += chunk.toString();
+		});
+		child.on("error", (error) => {
+			finish(() => reject(error));
+		});
+		child.on("close", (code) => {
+			finish(() => {
+				if (code === 0) {
+					resolve();
+					return;
+				}
+				reject(
+					new Error(
+						stderr.trim() || `powershell exited with code ${code ?? "unknown"}`,
+					),
+				);
+			});
+		});
+	});
+}
+
+export function createWindowsAudioPlaybackAdapter(): AudioPlaybackAdapter {
+	return {
+		platform: "win32",
+		play(soundPath: string): Promise<void> {
+			return runPowerShell(WINDOWS_AUDIO_SCRIPT, soundPath);
+		},
+	};
+}

package/extensions/osdy-pi/audio-playback.ts

@@ -0,0 +1,18 @@
+import { createMacOsAudioPlaybackAdapter } from "./audio-playback-macos.js";
+import { createUnsupportedAudioPlaybackAdapter } from "./audio-playback-unsupported.js";
+import { createWindowsAudioPlaybackAdapter } from "./audio-playback-windows.js";
+
+export type AudioPlaybackAdapter = {
+	readonly platform: "darwin" | "win32" | "unsupported";
+	play(path: string): Promise<void>;
+};
+
+export function createAudioPlaybackAdapter(): AudioPlaybackAdapter {
+	if (process.platform === "darwin") {
+		return createMacOsAudioPlaybackAdapter();
+	}
+	if (process.platform === "win32") {
+		return createWindowsAudioPlaybackAdapter();
+	}
+	return createUnsupportedAudioPlaybackAdapter();
+}