@madeinoz67/voice-server 0.1.9 → 0.1.10

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.
@@ -0,0 +1,320 @@
1
+ # Implementation Plan: FIFO Notification Queue
2
+
3
+ **Branch**: `002-fifo-notify-queue` | **Date**: 2026-02-09 | **Spec**: [spec.md](./spec.md)
4
+ **Input**: Feature specification from `/specs/002-fifo-notify-queue/spec.md`
5
+
6
+ **Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
7
+
8
+ ## Summary
9
+
10
+ Implement a FIFO (first-in-first-out) queue for the voice server's `/notify` endpoint to prevent audio overlap when multiple agents send notifications simultaneously. The queue accepts requests immediately with a 201 Accepted response, then processes notifications sequentially in the background. Includes a `/queue/status` monitoring endpoint and graceful shutdown with queue draining.
11
+
12
+ **Key Requirements**:
13
+ - FIFO ordering for all notifications
14
+ - 201 Accepted response within 100ms
15
+ - Max 100 item queue depth with 429 on overflow
16
+ - Invalid requests rejected immediately (400 Bad Request)
17
+ - Graceful shutdown drains queue before exit
18
+
19
+ ## Technical Context
20
+
21
+ **Language/Version**: TypeScript 5.x (Bun runtime)
22
+ **Primary Dependencies**: Bun native APIs, MLX-audio CLI (existing)
23
+ **Storage**: In-memory array (no persistence per spec)
24
+ **Testing**: Bun test runner (built-in)
25
+ **Target Platform**: macOS only (Constitution Principle IV)
26
+ **Project Type**: Single (monorepo with server code in `src/ts/`)
27
+ **Performance Goals**:
28
+ - 201 Accepted response < 100ms
29
+ - Queue status response < 50ms
30
+ - Max 100 queued items
31
+ - Sequential audio playback (no overlap)
32
+ **Constraints**:
33
+ - In-memory queue only (no persistence)
34
+ - Single worker for FIFO ordering
35
+ - Queue depth ≤ 100 items
36
+ - Shutdown drain timeout ≤ 30 seconds
37
+ **Scale/Scope**:
38
+ - Local voice server (single instance)
39
+ - 2-7 rapid notifications per PAI Algorithm operation
40
+ - Average 3-10 second TTS processing time per notification
41
+
42
+ ## Constitution Check
43
+
44
+ *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
45
+
46
+ ### Principle I: Drop-in Compatibility
47
+ ✅ **PASS** - `/notify` endpoint maintains exact contract. 201 Accepted is compatible with existing PAI system expectations. No breaking changes to request/response formats.
48
+
49
+ ### Principle II: Local-First Architecture
50
+ ✅ **PASS** - Queue is in-memory, no external API dependencies. MLX-audio remains primary TTS backend.
51
+
52
+ ### Principle III: Graceful Degradation
53
+ ✅ **PASS** - Queue skip-on-failure pattern continues processing even when individual items fail. Existing fallback to macOS `say` preserved.
54
+
55
+ ### Principle IV: Platform Honesty
56
+ ✅ **PASS** - No cross-platform abstractions. Uses macOS-native commands (`afplay`, `osascript`) directly.
57
+
58
+ ### Principle V: Test-First Validation
59
+ ✅ **PASS** - Unit and integration tests planned for all queue operations, API endpoints, and error conditions. TDD approach followed.
60
+
61
+ ### Principle VI: Codanna Workflow
62
+ ✅ **PASS** - All new TypeScript files in `src/ts/services/` and `src/ts/models/` will be indexed. Codanna used for symbol lookup and impact analysis.
63
+
64
+ ### Principle VII: Documentation Standards
65
+ ✅ **PASS** - This plan follows Markdown formatting requirements. API documentation in OpenAPI format. Code will have JSDoc comments.
66
+
67
+ **Overall Gate Status**: ✅ **PASS** - All constitutional principles satisfied.
68
+
69
+ ## Project Structure
70
+
71
+ ### Documentation (this feature)
72
+
73
+ ```text
74
+ specs/002-fifo-notify-queue/
75
+ ├── plan.md # This file (/speckit.plan command output)
76
+ ├── research.md # Phase 0 output (/speckit.plan command)
77
+ ├── data-model.md # Phase 1 output (/speckit.plan command)
78
+ ├── quickstart.md # Phase 1 output (/speckit.plan command)
79
+ ├── contracts/ # Phase 1 output (/speckit.plan command)
80
+ │ └── api.yaml # OpenAPI specification
81
+ └── tasks.md # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
82
+ ```
83
+
84
+ ### Source Code (repository root)
85
+
86
+ ```text
87
+ src/ts/
88
+ ├── services/
89
+ │ ├── notification-queue.ts # NEW: Queue implementation
90
+ │ ├── mlx-tts-client.ts # EXISTING: No changes needed
91
+ │ ├── pronunciation.ts # EXISTING: No changes needed
92
+ │ ├── prosody-translator.ts # EXISTING: No changes needed
93
+ │ └── voice-loader.ts # EXISTING: No changes needed
94
+ ├── models/
95
+ │ ├── queue.ts # NEW: Queue types
96
+ │ ├── notification.ts # EXISTING: No changes needed
97
+ │ ├── health.ts # EXISTING: Extended with queue fields
98
+ │ ├── tts.ts # EXISTING: No changes needed
99
+ │ └── voice-config.ts # EXISTING: No changes needed
100
+ ├── middleware/
101
+ │ ├── cors.ts # EXISTING: No changes needed
102
+ │ └── rate-limiter.ts # EXISTING: No changes needed
103
+ ├── utils/
104
+ │ ├── logger.ts # EXISTING: No changes needed
105
+ │ └── text-sanitizer.ts # EXISTING: No changes needed
106
+ └── server.ts # MODIFY: Add queue integration, /queue/status endpoint
107
+
108
+ tests/
109
+ ├── unit/
110
+ │ └── services/
111
+ │ └── notification-queue.test.ts # NEW: Queue unit tests
112
+ └── integration/
113
+ └── queue-api.test.ts # NEW: Queue API integration tests
114
+ ```
115
+
116
+ **Structure Decision**: Single project structure (Option 1). This is a backend service with HTTP API, no frontend component. All code resides in `src/ts/` following existing patterns.
117
+
118
+ ---
119
+
120
+ ## Phase 0: Research ✓ Complete
121
+
122
+ **Status**: Complete
123
+
124
+ **Research Output**: [research.md](./research.md)
125
+
126
+ **Key Decisions**:
127
+ 1. **Queue Implementation**: Array-based in-memory queue with async/await processing
128
+ 2. **Concurrency**: Single async worker with Promise-based processing
129
+ 3. **Graceful Shutdown**: Await queue drain with 30-second timeout
130
+ 4. **Error Handling**: Skip failed items, continue processing
131
+ 5. **Health Monitoring**: Extend existing HealthStatus model with queue fields
132
+ 6. **Rate Limiting**: Apply before queue admission, separate 429 for queue full
133
+
134
+ **Open Questions Resolved**:
135
+ - ✅ Shutdown behavior: Drain queue before exit (30s timeout)
136
+ - ✅ Queue status returns: 200 OK with health indicator
137
+ - ✅ Invalid requests: Reject immediately (400) before queuing
138
+
139
+ ---
140
+
141
+ ## Phase 1: Design & Contracts ✓ Complete
142
+
143
+ **Status**: Complete
144
+
145
+ ### Data Model
146
+
147
+ **Output**: [data-model.md](./data-model.md)
148
+
149
+ **Entities Defined**:
150
+ - `QueuedNotification` - Queued item with message, voice settings, status
151
+ - `QueueState` - Current queue depth, processing status, health indicator
152
+ - `QueueConfig` - Configuration for max depth, drain timeout, degraded threshold
153
+
154
+ **Type Dependencies**:
155
+ - Uses existing `NotificationRequest`, `ProsodySettings` from `models/notification.ts` and `models/voice-config.ts`
156
+ - Extends `HealthStatus` from `models/health.ts` with queue fields
157
+
158
+ ### API Contracts
159
+
160
+ **Output**: [contracts/api.yaml](./contracts/api.yaml)
161
+
162
+ **Endpoints Specified**:
163
+ 1. `POST /notify` - Queue notification (201/400/429/500)
164
+ 2. `GET /queue/status` - Get queue state (200 always)
165
+
166
+ **Request/Response Schemas**:
167
+ - `NotificationRequest` - Queue request body
168
+ - `SuccessResponse` - Success response
169
+ - `ErrorResponse` - Error response
170
+ - `QueueStateResponse` - Queue status response
171
+
172
+ ### Quickstart Guide
173
+
174
+ **Output**: [quickstart.md](./quickstart.md)
175
+
176
+ **Covers**:
177
+ - Development setup
178
+ - API usage examples
179
+ - Testing queue behavior
180
+ - Troubleshooting
181
+ - Configuration options
182
+
183
+ ---
184
+
185
+ ## Phase 2: Tasks (NOT CREATED YET)
186
+
187
+ **Status**: Pending `/speckit.tasks` command
188
+
189
+ **Note**: Run `/speckit.tasks` to generate `tasks.md` with dependency-ordered implementation tasks.
190
+
191
+ ---
192
+
193
+ ## Testing Strategy (Per Constitution Principle V)
194
+
195
+ ### Unit Tests
196
+
197
+ **File**: `tests/unit/services/notification-queue.test.ts`
198
+
199
+ Coverage:
200
+ - Queue enqueue/dequeue operations
201
+ - FIFO ordering verification
202
+ - Max depth enforcement
203
+ - Processing state management
204
+ - Error handling (skip failed items)
205
+ - Graceful shutdown with drain
206
+
207
+ ### Integration Tests
208
+
209
+ **File**: `tests/integration/queue-api.test.ts`
210
+
211
+ Coverage:
212
+ - `POST /notify` returns 201 Accepted
213
+ - Multiple requests process sequentially (no audio overlap)
214
+ - Queue overflow returns 429
215
+ - Invalid requests return 400
216
+ - `GET /queue/status` returns correct state
217
+ - Health indicator reflects TTS availability
218
+
219
+ ### Test Doubles
220
+
221
+ - Mock `processTTS()` function for unit tests
222
+ - Mock MLX TTS client for integration tests
223
+ - Fake timers for timing-sensitive tests
224
+
225
+ ---
226
+
227
+ ## Constitution Re-Check (Post-Design)
228
+
229
+ *Re-evaluated after Phase 1 design*
230
+
231
+ ✅ **All Principles Pass** - No violations, no complexity tracking required.
232
+
233
+ Design decisions uphold all constitutional principles:
234
+ - Drop-in compatibility maintained (201 Accepted is standard HTTP pattern)
235
+ - Local-first architecture (in-memory queue)
236
+ - Graceful degradation (skip-on-failure)
237
+ - Platform honesty (macOS-only)
238
+ - Test-first validation (comprehensive tests planned)
239
+ - Codanna workflow (new files will be indexed)
240
+ - Documentation standards (OpenAPI, JSDoc, Markdown)
241
+
242
+ ---
243
+
244
+ ## Implementation Notes
245
+
246
+ ### Queue Processing Flow
247
+
248
+ ```
249
+ HTTP Request → Validate → Enqueue → Return 201
250
+ ↓
251
+ Background Worker
252
+ ↓
253
+ Process TTS → Play Audio
254
+ ↓
255
+ Next Item (if any)
256
+ ```
257
+
258
+ ### Graceful Shutdown Flow
259
+
260
+ ```
261
+ SIGTERM/SIGINT → Set draining flag → Stop accepting requests
262
+ ↓
263
+ Wait for queue empty (30s timeout)
264
+ ↓
265
+ Exit process
266
+ ```
267
+
268
+ ### Error Handling Flow
269
+
270
+ ```
271
+ TTS Failure → Log error → Skip to next item → Continue processing
272
+ Queue Full → Return 429 → Client may retry
273
+ Invalid Request → Return 400 → Never queued
274
+ ```
275
+
276
+ ---
277
+
278
+ ## Dependencies
279
+
280
+ ### Internal Dependencies
281
+
282
+ - `src/ts/models/notification.ts` - Request/response types
283
+ - `src/ts/models/voice-config.ts` - ProsodySettings type
284
+ - `src/ts/models/health.ts` - HealthStatus extension
285
+ - `src/ts/services/mlx-tts-client.ts` - TTS synthesis
286
+ - `src/ts/utils/logger.ts` - Logging
287
+ - `src/ts/utils/text-sanitizer.ts` - Input validation
288
+ - `src/ts/services/voice-loader.ts` - Voice ID validation
289
+
290
+ ### External Dependencies
291
+
292
+ - Bun runtime (native Promise, Array, crypto APIs)
293
+ - MLX-audio CLI (existing TTS backend)
294
+
295
+ ---
296
+
297
+ ## Success Criteria Verification
298
+
299
+ **From Spec**:
300
+
301
+ | Criterion | Verification |
302
+ |-----------|--------------|
303
+ | SC-001: Sequential playback | Integration test sends 10 concurrent requests, verifies no audio overlap |
304
+ | SC-002: 201 in < 100ms | Unit test measures response time for enqueue operation |
305
+ | SC-003: Status < 50ms | Unit test measures `/queue/status` response time |
306
+ | SC-004: 429 on overflow | Integration test fills queue to 100, verifies 429 on 101st request |
307
+ | SC-005: 400 on invalid | Unit tests for each validation failure scenario |
308
+
309
+ ---
310
+
311
+ ## Next Steps
312
+
313
+ 1. **Run `/speckit.tasks`** - Generate implementation task list
314
+ 2. **Update agent context** - Run `.specify/scripts/bash/update-agent-context.sh claude`
315
+ 3. **Begin implementation** - Follow tasks in dependency order
316
+ 4. **Update Codanna index** - After adding new TypeScript files
317
+
318
+ ---
319
+
320
+ **Plan Status**: ✅ Phase 0 & 1 Complete | Phase 2 Pending `/speckit.tasks`
@@ -0,0 +1,273 @@
1
+ # FIFO Notification Queue - Quickstart
2
+
3
+ **Feature**: FIFO Notification Queue
4
+ **Branch**: `001-fifo-notify-queue`
5
+ **Last Updated**: 2026-02-09
6
+
7
+ ## Overview
8
+
9
+ This quickstart guide helps you set up and work with the FIFO notification queue feature locally.
10
+
11
+ ---
12
+
13
+ ## Prerequisites
14
+
15
+ - Bun runtime installed
16
+ - macOS (platform requirement per Constitution)
17
+ - MLX-audio CLI installed and configured
18
+ - Kokoro-82M voice model available
19
+
20
+ ---
21
+
22
+ ## Development Setup
23
+
24
+ ### 1. Start the Voice Server
25
+
26
+ ```bash
27
+ # From repository root
28
+ bun run dev
29
+ ```
30
+
31
+ Server starts on `http://127.0.0.1:8888`
32
+
33
+ ### 2. Verify Queue Status
34
+
35
+ ```bash
36
+ curl http://127.0.0.1:8888/queue/status
37
+ ```
38
+
39
+ Expected response (empty queue):
40
+ ```json
41
+ {
42
+ "depth": 0,
43
+ "processing_status": "idle",
44
+ "health": "healthy"
45
+ }
46
+ ```
47
+
48
+ ---
49
+
50
+ ## API Usage
51
+
52
+ ### Queue a Notification
53
+
54
+ ```bash
55
+ curl -X POST http://127.0.0.1:8888/notify \
56
+ -H "Content-Type: application/json" \
57
+ -d '{
58
+ "message": "This is a test notification"
59
+ }'
60
+ ```
61
+
62
+ Expected response:
63
+ ```json
64
+ {
65
+ "status": "success",
66
+ "message": "Notification queued"
67
+ }
68
+ ```
69
+
70
+ **HTTP Status**: `201 Created`
71
+
72
+ ### Queue Multiple Notifications (Test FIFO)
73
+
74
+ ```bash
75
+ # Send 3 rapid requests
76
+ for i in 1 2 3; do
77
+ curl -X POST http://127.0.0.1:8888/notify \
78
+ -H "Content-Type: application/json" \
79
+ -d "{\"message\": \"Notification $i\"}"
80
+ done
81
+ ```
82
+
83
+ All three return `201 Created` immediately, audio plays sequentially.
84
+
85
+ ### Check Queue Status During Processing
86
+
87
+ ```bash
88
+ curl http://127.0.0.1:8888/queue/status
89
+ ```
90
+
91
+ Example response:
92
+ ```json
93
+ {
94
+ "depth": 2,
95
+ "processing_status": "active",
96
+ "health": "healthy",
97
+ "metrics": {
98
+ "average_wait_time_ms": 5000,
99
+ "items_processed": 5,
100
+ "items_failed": 0
101
+ }
102
+ }
103
+ ```
104
+
105
+ ---
106
+
107
+ ## Testing Queue Behavior
108
+
109
+ ### Test Sequential Playback
110
+
111
+ 1. Start server: `bun run dev`
112
+ 2. In another terminal, send multiple requests:
113
+ ```bash
114
+ for i in {1..5}; do
115
+ curl -X POST http://127.0.0.1:8888/notify \
116
+ -H "Content-Type: application/json" \
117
+ -d "{\"message\": \"Test notification $i\"}"
118
+ sleep 0.5
119
+ done
120
+ ```
121
+ 3. **Expected**: Audio plays 1, 2, 3, 4, 5 in order with no overlap
122
+
123
+ ### Test Queue Overflow
124
+
125
+ ```bash
126
+ # Fill queue to capacity (100 items)
127
+ for i in {1..100}; do
128
+ curl -X POST http://127.0.0.1:8888/notify \
129
+ -H "Content-Type: application/json" \
130
+ -d "{\"message\": \"Fill queue $i\"}" &
131
+ done
132
+ wait
133
+
134
+ # Next request should fail
135
+ curl -X POST http://127.0.0.1:8888/notify \
136
+ -H "Content-Type: application/json" \
137
+ -d '{"message": "This should fail"}'
138
+ ```
139
+
140
+ Expected response:
141
+ ```json
142
+ {
143
+ "status": "error",
144
+ "message": "Queue is full (100 items)"
145
+ }
146
+ ```
147
+
148
+ **HTTP Status**: `429 Too Many Requests`
149
+
150
+ ### Test Invalid Request Rejection
151
+
152
+ ```bash
153
+ # Missing message field
154
+ curl -X POST http://127.0.0.1:8888/notify \
155
+ -H "Content-Type: application/json" \
156
+ -d '{"title": "No message"}'
157
+ ```
158
+
159
+ Expected response:
160
+ ```json
161
+ {
162
+ "status": "error",
163
+ "message": "Missing required field: message"
164
+ }
165
+ ```
166
+
167
+ **HTTP Status**: `400 Bad Request`
168
+
169
+ ### Test Graceful Shutdown
170
+
171
+ 1. Queue several notifications
172
+ 2. Send SIGTERM: `kill -TERM <pid>`
173
+ 3. **Expected**: All queued notifications play before server exits
174
+
175
+ ---
176
+
177
+ ## Running Tests
178
+
179
+ ### Unit Tests
180
+
181
+ ```bash
182
+ bun test tests/unit/services/notification-queue.test.ts
183
+ ```
184
+
185
+ ### Integration Tests
186
+
187
+ ```bash
188
+ bun test tests/integration/queue-api.test.ts
189
+ ```
190
+
191
+ ### All Tests
192
+
193
+ ```bash
194
+ bun test
195
+ ```
196
+
197
+ ---
198
+
199
+ ## Development Workflow
200
+
201
+ ### Code Structure
202
+
203
+ ```
204
+ src/ts/
205
+ ├── services/
206
+ │ └── notification-queue.ts # Queue implementation
207
+ ├── models/
208
+ │ └── queue.ts # Queue types
209
+ └── server.ts # Updated with queue handlers
210
+
211
+ tests/
212
+ ├── unit/
213
+ │ └── services/
214
+ │ └── notification-queue.test.ts
215
+ └── integration/
216
+ └── queue-api.test.ts
217
+ ```
218
+
219
+ ### Implementation Checklist
220
+
221
+ - [ ] Create `NotificationQueue` class
222
+ - [ ] Add `/queue/status` endpoint handler
223
+ - [ ] Update `/notify` to use queue
224
+ - [ ] Implement graceful shutdown with queue drain
225
+ - [ ] Add queue event logging
226
+ - [ ] Write unit tests for queue operations
227
+ - [ ] Write integration tests for API endpoints
228
+ - [ ] Update Codanna index
229
+
230
+ ---
231
+
232
+ ## Troubleshooting
233
+
234
+ ### Audio Not Playing
235
+
236
+ 1. Check queue status: `curl http://127.0.0.1:8888/queue/status`
237
+ 2. Check health: `curl http://127.0.0.1:8888/health`
238
+ 3. Verify TTS system: Ensure MLX-audio CLI is working
239
+ 4. Check logs: Server logs show queue events
240
+
241
+ ### Requests Immediately Return 429
242
+
243
+ - Cause: Queue is at capacity (100 items)
244
+ - Solution: Wait for queue to drain, or increase `maxDepth` in config
245
+
246
+ ### Invalid voice_id Errors
247
+
248
+ - Check available voices: `curl http://127.0.0.1:8888/health | jq '.available_voices'`
249
+ - Use valid voice_id from list
250
+ - Or omit voice_id to use default
251
+
252
+ ---
253
+
254
+ ## Configuration
255
+
256
+ Queue behavior is configured via environment variables and code defaults:
257
+
258
+ | Setting | Default | Description |
259
+ |---------|---------|-------------|
260
+ | `QUEUE_MAX_DEPTH` | 100 | Maximum queue depth |
261
+ | `QUEUE_DRAIN_TIMEOUT_MS` | 30000 | Shutdown drain timeout |
262
+ | `QUEUE_DEGRADED_THRESHOLD` | 0.8 | Health degraded threshold |
263
+
264
+ ---
265
+
266
+ ## Next Steps
267
+
268
+ After implementing:
269
+
270
+ 1. Run tests: `bun test`
271
+ 2. Type check: `bun run typecheck`
272
+ 3. Lint: `bun run lint`
273
+ 4. Create PR for review