osdy-pi 0.1.4 → 0.1.6

package/README.md

@@ -10,15 +10,24 @@ Visit the Osdy landing page: [landing-osdy.vercel.app](https://landing-osdy.verc
 
 - **Dark theme:** `osdy-pi-dark`, enabled by default when the package starts.
 - **Light theme:** `osdy-pi-light`, with the same Osdy palette adapted for light terminals.
-- **Custom header:** centered Osdy-Pi ASCII branding with responsive status metadata.
+- **Simple theme:** `osdy-pi-simple`, a blue/red/slate console theme for the full Pi interface.
+- **Custom header:** two selectable header styles with responsive status metadata: `osdy-theme` (default) and `classic`.
 - **Custom editor:** full-width framed input area with model, thinking, token, cost, and context status.
-- **Clean layout:** the built-in footer/working row is hidden while Osdy Pi is enabled to avoid duplicated UI.
+- **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" />
 
 ## Install in Pi
 
-Install the package directly from GitHub:
+Install the published package from npm:
+
+```bash
+pi install npm:osdy-pi
+```
+
+You can also install it directly from GitHub:
 
 ```bash
 pi install git:github.com/OsdyOrtiz/Osdy-Pi
@@ -45,6 +54,7 @@ Then select one of these theme names:
 ```text
 osdy-pi-dark
 osdy-pi-light
+osdy-pi-simple
 ```
 
 You can also set it in your Pi `settings.json`:
@@ -55,7 +65,7 @@ You can also set it in your Pi `settings.json`:
 }
 ```
 
-Use `osdy-pi-light` instead if you prefer the light version.
+Use `osdy-pi-light` if you prefer the light version, or `osdy-pi-simple` if you want the blue/red/slate palette across the whole console.
 
 ## Commands
 
@@ -65,11 +75,88 @@ 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
+/osdy-pi-classic
 ```
 
 - `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.
+- `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
 
@@ -92,11 +179,24 @@ pi install /absolute/path/to/Osdy-Pi
 ```text
 themes/osdy-pi-dark.json
 themes/osdy-pi-light.json
+themes/osdy-pi-simple.json
 extensions/osdy-pi.ts
+extensions/osdy-pi/
 ```
 
+`extensions/osdy-pi.ts` is the package entrypoint. The implementation lives in the modular `extensions/osdy-pi/` folder (runtime, UI, metrics, working controller, animation, border, and formatting helpers).
+
 The Pi manifest is declared in `package.json` through `pi.themes` and `pi.extensions`, so Pi can discover the themes and extension after installation.
 
+## Development
+
+If you are working on the package locally, you can run:
+
+```bash
+npm run typecheck
+npm run lint
+```
+
 ## Uninstall or turn off
 
 To temporarily turn off the custom UI inside Pi:

package/extensions/osdy-pi/animation.ts

@@ -1,5 +1,6 @@
 import { ANIMATION_ENABLED } from "./constants.js";
 import type { AnimationMode, SimpleTheme } from "./types.js";
+import type { MascotTonePalette } from "./constants.js";
 import { positiveModulo } from "./utils.js";
 
 export type AsciiAnimationStyle = "static" | "animated";
@@ -57,3 +58,42 @@ export function animateAsciiLine(
 		})
 		.join("");
 }
+
+export function animateAsciiLineWithToneMap(
+	line: string,
+	toneMap: string,
+	lineIndex: number,
+	frame: number,
+	theme: SimpleTheme,
+	palette: MascotTonePalette,
+	style: AsciiAnimationStyle,
+): string {
+	return Array.from(line)
+		.map((char, charIndex) => {
+			if (char === " ") return char;
+			const tone = toneMap[charIndex];
+			if (
+				tone !== "b" &&
+				tone !== "h" &&
+				tone !== "l" &&
+				tone !== "m" &&
+				tone !== "d" &&
+				tone !== "p" &&
+				tone !== "c" &&
+				tone !== "v"
+			) {
+				return char;
+			}
+			const baseColor = palette[tone];
+			if (style === "static") return theme.fg(baseColor, char);
+			const wave = positiveModulo(charIndex + lineIndex * 2 - frame * 5, 44);
+			const highlightColor =
+				tone === "b" || tone === "h" || tone === "p" ? palette.h : palette.l;
+			const trailColor = tone === "d" ? palette.m : palette.b;
+			return theme.fg(
+				getAnimatedAsciiColor(wave, baseColor, highlightColor, trailColor),
+				char,
+			);
+		})
+		.join("");
+}

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(),
+	};
+}