feat(vscode): implement notification sound playback and preview

[IamCoder18]

Context

This is the first split-up and refined PR from #8278 based on feedback from @marius-kilocode

This PR adds audio notification playback to the Kilo Code VS Code extension, addressing user needs for auditory feedback when agent tasks complete, permissions are required, or errors occur. Previously, the notification settings (kilo-code.new.sounds.*) existed but were not wired to any actual sound playback.

Closes #7877
Closes #8127
Closes #10321

Implementation

1. Sound Utility (src/util/sound.ts): Cross-platform sound playback supporting:

   • 45+ bundled WAV audio files organized into categories (alert, bip-bop, nope, yup, staplebops)
   • System default sounds via platform-native commands (osascript beep, canberra-gtk-play, Windows SystemSounds)
   • Queued playback with max 3 concurrent limit to prevent audio overlap
   • Fallback chains for each platform (afplay → play for macOS, aplay → paplay → play for Linux, PowerShell SoundPlayer for Windows)

2. SoundNotificationService (src/util/sound-notification.ts): Centralized service that:

   • Tracks VS Code window focus state to only play sounds when extension is not focused
   • Manages busy/idle session state transitions
   • Implements 700ms cooldown per session/event to prevent spam
   • Integrates with connection service's deduplication via shouldNotify()

3. Settings Integration: UI in Notifications tab with:

   • "System" option as new default (uses OS-native sounds)
   • Test buttons next to each sound dropdown for instant preview
   • All 45+ sounds available as enum options
   • Multi-language i18n support (18 locales)

Screenshots

Walkthrough with Question, Permission, and Agent Completion as well as Test sound button (Please unmute the video)

2026-05-23.09-54-22.mp4

Multiple sounds in quick succession (700ms cooldown)

2026-05-23.10-26-57.mp4

Error sound plays

2026-05-23.10-33-09.mp4

Testing sound + sounds in quick succession on Windows

2026-05-23.10-48-23.mp4

How to Test

1. Open VS Code with Kilo Code extension
2. Go to Settings → Notifications tab
3. Select a sound for "Agent completion" (e.g., "alert-01")
4. Click "Test" button to preview the sound
5. Start an agent task, switch to another app
6. Wait for task completion - should hear selected sound

I've tested the thoroughly on Ubuntu 22.04 and partially on Windows 11, but not on macOS.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

All Previously Flagged Issues Resolved

• ✅ cooldowns Map unbounded growth — fixed with MAX_COOLDOWNS = 200, COOLDOWN_TTL_MS, and periodic cleanupTimer
• ✅ busySessions leak — fixed with pruneStaleBusySessions() called on interval and per-event
• ✅ shouldNotify / setTimeout after dispose() — fixed with disposed flag + clearTimeout on all timers in dispose()
• ✅ testNotification handler — properly wired via case "testNotification": this.soundService.handleTestNotification(message.settingType)
• ✅ as "agent" | "permissions" | "errors" cast — no longer needed; TestNotificationMessage types settingType correctly
• ✅ Windows PowerShell CRITICAL — powershell -File <wav-path> replaced with -Command [System.Media.SoundPlayer]::new(...) using proper single-quote escaping (replace(/'/g, "''"))
• ✅ Windows path injection WARNING — single-quote escaping + control-character filter (/^[^\x00-\x1F\x7F]+$/) applied to file path
• ✅ eslint.config.mjs max-lines cap — back to 3600 (same as main); no longer in PR diff
• ✅ .kilo/plans/1779932794331-swift-nebula.md — unrelated planning document removed from PR

Other Observations (not blocking)

• Module-level chain and queued in sound.ts: These are module singletons shared across all SoundNotificationService instances. If multiple KiloProviders import sound.ts, they share a single queue — no isolation between providers. Not a regression from this PR but worth noting for test hygiene.
• await chain in playSound (line 219): This awaits the entire queue including all previously queued sounds. Since callers use void playSound(...), the await only affects internal sequencing — not a bug.
• focused === undefined default: When setupFocusTracking() finds vscode.window.onDidChangeWindowState falsy, focused stays undefined. The guard if (this.focused === true && !playWhenFocused) return correctly falls through to play sounds — safe default behavior.

Files Reviewed (13 files)

• packages/kilo-vscode/src/util/sound-notification.ts — all issues resolved ✅
• packages/kilo-vscode/src/util/sound.ts — all issues resolved ✅
• packages/kilo-vscode/src/KiloProvider.ts — testNotification wired ✅, soundService lifecycle correct ✅
• packages/kilo-vscode/src/services/cli-backend/connection-service.ts — shouldNotify + dispose cleanup ✅
• packages/kilo-vscode/package.json — enum values expanded, playWhenFocused added, default changed to system ✅
• packages/kilo-vscode/.vscodeignore — audio-wav dir included ✅
• packages/kilo-vscode/webview-ui/src/components/settings/NotificationsTab.tsx — test buttons wired, playWhenFocused toggle added ✅
• packages/kilo-vscode/webview-ui/src/types/messages/extension-messages.ts — playWhenFocused field added ✅
• packages/kilo-vscode/webview-ui/src/types/messages/webview-messages.ts — TestNotificationMessage type added ✅
• packages/kilo-vscode/webview-ui/src/i18n/*.ts — i18n additions (all 20 locales) ✅
• .changeset/sound-notifications.md — changeset present ✅
• packages/kilo-vscode/audio-wav/ — 45 WAV assets bundled ✅
• .kilo/plans/1779932794331-swift-nebula.md — removed from PR ✅

---

_{Reviewed by claude-sonnet-4.6 · 1,376,103 tokens}

_{Review guidance: REVIEW.md from base branch main}

[IamCoder18]

Another video, showing no audio plays when VS Code is focused.

2026-05-25.21-24-57.mp4

[IamCoder18]

All CI pass, code review found no issues, and I've manually read over the changes.

[IamCoder18]

@marius-kilocode

I added a new "Play Sounds When Focused" setting (default false) that allows sound notifications to play even when the VS Code window is focused. This is for users whose workflows look more like sending off a request and going through code themselves. The setting appears in the Notifications settings tab with a toggle switch, and includes localized strings in all 18 languages.

2026-05-27.18-56-31.mp4

[marius-kilocode]

This feature was actually done upstream and is now on main with: #11031. Unfortunately this will make the current PR architecture obsolete. There are still many good parts we can reuse. Let's see what works here.

[johnnyeric]

Closing this PR based on the context from #8278. Please let me know if I this is incorrect and I I'll reopen.