npm - pi-smart-voice-notify - Versions diffs - 0.1.0 → 0.1.2 - Mend

pi-smart-voice-notify 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,16 @@
 # Changelog
+## [0.1.2] - 2026-03-04
+### Fixed
+- Use absolute GitHub raw URL for README image to fix npm display
+## [0.1.1] - 2026-03-04
+### Changed
+- Rewrote README.md with professional documentation standards
+- Added comprehensive feature documentation, configuration reference, and usage examples
 ## 0.1.0
 - Standardized repository structure to `index.ts` shim + `src/` implementation.

package/README.md CHANGED Viewed

@@ -1,187 +1,243 @@
-# pi-smart-voice-notify
+# 🔔 pi-smart-voice-notify
 Windows-optimized smart notification extension for the Pi coding agent.
-`pi-smart-voice-notify` watches Pi session/tool events and can alert you via **Windows SAPI TTS**, **sound playback**, and/or **desktop toast notifications** when the agent:
+**pi-smart-voice-notify** monitors Pi session and tool events to alert you via **Windows SAPI TTS**, **sound playback**, and **desktop toast notifications** when the agent requires your attention.
-- finishes a turn (idle)
-- hits a permission block
-- needs your input (question)
-- encounters an error
-![alt text](assets/pi-smart-voice-notify.png)
+![pi-smart-voice-notify configuration modal](https://raw.githubusercontent.com/MasuRii/pi-smart-voice-notify/main/assets/pi-smart-voice-notify.png)
 ## Features
-- Multi-channel notifications:
-  - **Sound** (Windows via `powershell.exe` playback; falls back to simple beeps if playback fails)
-  - **Voice** (Windows SAPI text-to-speech)
-  - **Desktop notifications** via `node-notifier` (win32/darwin/linux best-effort)
-- Reminder + follow-up scheduling when attention is still needed
-- Throttling to avoid notification spam (`minNotificationIntervalMs`)
-- Interactive settings UI:
-  - `/voice-notify` opens a configuration modal in interactive mode
-  - hides question-related settings automatically when no custom `question` tool is available
-- Optional debug logging to `debug/` for diagnosing platform / PowerShell / notifier issues
+- **Multi-channel notifications**
+  - **Sound** – Windows audio playback via PowerShell (with beep fallback)
+  - **Voice** – Windows SAPI text-to-speech with configurable voice and rate
+  - **Desktop toasts** – Cross-platform notifications via `node-notifier` (Windows/macOS/Linux)
-## Installation
+- **Intelligent event detection**
+  - Task completion (idle)
+  - Permission blocks
+  - Questions requiring input (when custom `question` tool is loaded)
+  - Errors
+- **Reminder system**
+  - Configurable reminder delays with follow-up scheduling
+  - Exponential backoff multiplier for follow-ups
+  - Auto-cancel reminders on user activity
-### Local extension folder
+- **Wake monitor support**
+  - Wakes display from sleep before notifications
+  - Cross-platform: Windows (SendKeys), macOS (caffeinate), Linux (xset/GNOME)
-Place this folder in either:
+- **Interactive settings UI**
+  - `/voice-notify` command opens a modal for live configuration
+  - Settings persist to disk automatically
+- **Debug logging**
+  - Optional JSONL debug output for troubleshooting
+## Installation
-- Global: `~/.pi/agent/extensions/pi-smart-voice-notify`
-- Project: `.pi/extensions/pi-smart-voice-notify`
+### Local Extension Folder
-Pi auto-discovers these locations.
+Place this folder in either location (Pi auto-discovers both):
-### As an npm package
+- **Global:** `~/.pi/agent/extensions/pi-smart-voice-notify`
+- **Project:** `.pi/extensions/pi-smart-voice-notify`
+### As an npm Package
 ```bash
 pi install npm:pi-smart-voice-notify
 ```
-Or from git:
+### From Git
 ```bash
 pi install git:github.com/MasuRii/pi-smart-voice-notify
 ```
-## Configuration
+## Usage
-Runtime config is stored at:
+### Commands
-```text
-~/.pi/agent/extensions/pi-smart-voice-notify/config.json
-```
+| Command | Description |
+|---------|-------------|
+| `/voice-notify` | Opens the settings modal (interactive mode) or prints config summary |
+| `/voice-notify status` | Displays current configuration and question tool availability |
+| `/voice-notify reload` | Reloads config from disk and resets reminder state |
+| `/voice-notify on` | Enables the extension |
+| `/voice-notify off` | Disables the extension |
+| `/voice-notify test [type]` | Triggers a test notification (bypasses throttling) |
-A starter template is included as:
+**Test types:** `idle`, `permission`, `question`, `error`
+### Example
 ```text
-config/config.example.json
+/voice-notify test idle
+/voice-notify test permission
 ```
-On startup the extension:
+## Configuration
+Configuration is stored at:
-- creates `config.json` with defaults if missing
-- normalizes/clamps values on load **and writes the normalized config back to disk**
+```
+~/.pi/agent/extensions/pi-smart-voice-notify/config.json
+```
-### Common settings
+A starter template is provided in `config/config.example.json`. On startup, the extension creates `config.json` with defaults if missing.
-- `enabled` (boolean): master on/off switch
-- `windowsOptimized` (boolean): when `true`, shows a one-time warning on non-Windows platforms that audio behavior is best-effort
-- `notificationMode`:
-  - `sound-first` (default)
-  - `tts-first`
-  - `both`
-  - `sound-only`
-- Channel toggles:
-  - `enableSound` (Windows)
-  - `enableTts` (Windows)
-  - `enableDesktopNotification` (toast via `node-notifier`)
-- Per-event toggles:
-  - `enableIdleNotification`
-  - `enablePermissionNotification`
-  - `enableQuestionNotification` (only effective when a custom tool named `question` is loaded)
-  - `enableErrorNotification`
-- Reminder / follow-ups:
-  - `reminderEnabled`, `reminderDelaySeconds`
-  - `followUpEnabled`, `maxFollowUps`, `followUpBackoffMultiplier`
-- Debug:
-  - `debugLog` (boolean): writes JSONL debug events to the debug log file
+### Configuration Options
-### Sound file paths
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `true` | Master on/off switch |
+| `windowsOptimized` | boolean | `true` | Show warning on non-Windows platforms |
+| `notificationMode` | string | `"sound-first"` | Mode: `sound-first`, `tts-first`, `both`, `sound-only` |
+| `enableSound` | boolean | `true` | Enable sound playback (Windows) |
+| `enableTts` | boolean | `true` | Enable text-to-speech (Windows) |
+| `enableDesktopNotification` | boolean | `true` | Enable desktop toast notifications |
+| `desktopNotificationTimeout` | number | `8` | Toast display duration in seconds (1–60) |
+| `wakeMonitor` | boolean | `true` | Wake display from sleep before notifying |
+| `idleThresholdSeconds` | number | `30` | System idle threshold before waking monitor (5–600) |
-Sound fields (`idleSoundFile`, `permissionSoundFile`, `questionSoundFile`, `errorSoundFile`) may be:
+### Event Toggles
-- **absolute paths**, or
-- **paths relative to the extension directory** (`~/.pi/agent/extensions/pi-smart-voice-notify/`)
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enableIdleNotification` | boolean | `true` | Notify when agent finishes a task |
+| `enablePermissionNotification` | boolean | `true` | Notify on permission blocks |
+| `enableQuestionNotification` | boolean | `true` | Notify when agent asks a question* |
+| `enableErrorNotification` | boolean | `true` | Notify on errors |
+| `suppressIdleAfterError` | boolean | `true` | Skip idle notification if turn had errors |
-The default template uses paths under `assets/`.
+*Question notifications only work when a custom `question` tool is loaded.
-## Usage / Commands
+### Reminder Settings
-Command name:
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `reminderEnabled` | boolean | `true` | Enable reminder notifications |
+| `reminderDelaySeconds` | number | `30` | Initial delay before first reminder (5–300) |
+| `followUpEnabled` | boolean | `true` | Enable follow-up reminders |
+| `maxFollowUps` | number | `3` | Maximum follow-up count (1–10) |
+| `followUpBackoffMultiplier` | number | `1.5` | Delay multiplier for each follow-up |
-```text
-/voice-notify
-```
+### TTS Settings (Windows)
-- With **no arguments**:
-  - in interactive mode: opens the settings modal
-  - in non-interactive mode: prints a config summary (the UI is required for the modal)
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `ttsVoice` | string | `"Microsoft Zira Desktop"` | SAPI voice name |
+| `ttsRate` | number | `-1` | Speech rate (-10 to 10) |
-Subcommands:
+### Sound File Paths
-```text
-/voice-notify status
-/voice-notify reload
-/voice-notify on
-/voice-notify off
-/voice-notify test [idle|permission|question|error]
-```
+| Option | Type | Default |
+|--------|------|---------|
+| `idleSoundFile` | string | `"assets/Soft-high-tech-notification-sound-effect.mp3"` |
+| `permissionSoundFile` | string | `"assets/Machine-alert-beep-sound-effect.mp3"` |
+| `questionSoundFile` | string | `"assets/Machine-alert-beep-sound-effect.mp3"` |
+| `errorSoundFile` | string | `"assets/Machine-alert-beep-sound-effect.mp3"` |
-Behavior notes:
+Paths can be absolute or relative to the extension directory.
-- `/voice-notify reload` re-reads `config.json` and resets reminder state.
-- `/voice-notify test ...` bypasses throttling so you can validate your setup quickly.
-- If no custom `question` tool is loaded, question notifications are skipped and `/voice-notify test question` warns.
+### Advanced Settings
-## Notes (assets & debug)
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `minNotificationIntervalMs` | number | `1500` | Throttle interval between same-type notifications |
+| `debugLog` | boolean | `false` | Enable debug logging to file |
-- Notification sound assets live in: `assets/`
-- When `debugLog: true`, debug logs are written under:
-  - directory: `~/.pi/agent/extensions/pi-smart-voice-notify/debug/`
-  - file: `~/.pi/agent/extensions/pi-smart-voice-notify/debug/pi-smart-voice-notify.log`
+## Notification Modes
+| Mode | Behavior |
+|------|----------|
+| `sound-first` | Play sound first; fall back to TTS on failure |
+| `tts-first` | Speak TTS first; fall back to sound on failure |
+| `both` | Play sound and speak TTS simultaneously |
+| `sound-only` | Play sound only, no TTS or reminders |
 ## Troubleshooting
-### I ran `/voice-notify` but no modal appeared
+### Settings modal doesn't appear
-- The settings modal requires **interactive UI mode** (`ctx.hasUI`).
-- In non-interactive contexts, `/voice-notify` prints a summary instead.
+The modal requires **interactive UI mode** (`ctx.hasUI`). In non-interactive contexts, `/voice-notify` prints a config summary instead.
-### Desktop notifications are not showing
+### Desktop notifications not showing
-- Ensure `enableDesktopNotification` is `true`.
-- This extension uses `node-notifier`. If the underlying platform backend is unavailable, notifications may fail.
-- Turn on `debugLog` and inspect `debug/pi-smart-voice-notify.log` for `desktop.notify.failed` events.
+1. Ensure `enableDesktopNotification` is `true`
+2. Check that `node-notifier` is installed
+3. Enable `debugLog` and check `debug/pi-smart-voice-notify.log` for `desktop.notify.failed` events
-### No sound / no voice on Windows
+### No sound or voice on Windows
-- Sound + SAPI TTS are Windows-only features (`process.platform === "win32"`).
-- The extension invokes `powershell.exe` for sound playback and TTS. If PowerShell is restricted/unavailable, audio will fail.
-- Turn on `debugLog` and search the log for `powershell.exec` entries.
+1. Sound and TTS are Windows-only (`process.platform === "win32"`)
+2. The extension uses PowerShell for audio playback and SAPI—ensure PowerShell is available
+3. Enable `debugLog` and search for `powershell.exec` entries
 ### Question notifications never trigger
-- Question notifications are only enabled when Pi has a custom tool named `question` loaded.
-- Run `/voice-notify status` and check `questionToolAvailable=true/false`.
+Question notifications require a custom `question` tool to be loaded. Run `/voice-notify status` to verify `questionToolAvailable=true`.
-## Development
+### Wake monitor not working
+- **Windows:** Uses SendKeys (F15) via PowerShell
+- **macOS:** Uses `caffeinate -u -t 1`
+- **Linux:** Uses `xset dpms force on` or GNOME D-Bus
+Ensure system idle time exceeds `idleThresholdSeconds` for wake to trigger.
+## Technical Details
+### Architecture
+```
+index.ts                    → Extension entrypoint (re-exports src/index.ts)
+src/
+├── index.ts                → Main extension logic, event handlers, command registration
+├── config-store.ts         → Config paths, normalization, load/save utilities
+├── types.ts                → TypeScript interfaces and types
+├── notify-audio.ts         → Windows sound + SAPI TTS + monitor wake service
+├── desktop-notify.ts       → Desktop toast notifications via node-notifier
+├── logging.ts              → Debug logger with JSONL output
+└── zellij-modal.ts         → Settings modal UI components
+```
+### Event Hooks
+| Event | Behavior |
+|-------|----------|
+| `session_start` | Load config, reset state, update status bar |
+| `session_switch` | Reset state, refresh question tool availability |
+| `session_shutdown` | Cancel reminders, clear status |
+| `input` | Track user activity, cancel pending reminders |
+| `agent_start` | Reset error tracking |
+| `tool_call` | Detect permission blocks |
+| `tool_result` | Classify results (question/permission/error) |
+| `agent_end` | Trigger idle notification (if enabled) |
+### Debug Logging
+When `debugLog: true`, JSONL events are written to:
-```bash
-npm install
-npm run build
-npm run lint
-npm run test
-npm run check
+```
+~/.pi/agent/extensions/pi-smart-voice-notify/debug/pi-smart-voice-notify.log
 ```
-Project requirements:
+Events include: config changes, notifications triggered, audio dispatch, reminders, and errors.
-- Node.js `>= 20` (see `package.json`)
+## Development
-## Project Layout
+```bash
+npm install
+npm run build      # TypeScript compilation
+npm run lint       # Run linter
+npm run test       # Run tests
+npm run check      # lint + test
+```
-- `index.ts` - root extension entrypoint (kept for Pi auto-discovery)
-- `src/index.ts` - extension bootstrap, event hooks, `/voice-notify` command
-- `src/config-store.ts` - config paths, normalization, load/save, debug log path constants
-- `src/notify-audio.ts` - Windows sound + SAPI TTS + monitor wake best-effort helpers
-- `src/desktop-notify.ts` - toast notifications via `node-notifier`
-- `config/config.example.json` - starter config template
-- `assets/` - bundled sound assets referenced by default config
-- `debug/` - created at runtime when debug logging is enabled
+**Requirements:** Node.js ≥ 20
 ## License

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "pi-smart-voice-notify",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Windows-optimized smart voice, sound, and desktop notifications for Pi coding agent.",
   "type": "module",
   "main": "./index.ts",