@firstpick/pi-package-webui 0.5.9 → 0.6.1

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,361 @@
1
+ import assert from "node:assert/strict";
2
+ import {
3
+ createVoiceConversationController,
4
+ voiceSilenceEventMessage,
5
+ VOICE_UI_STATES,
6
+ } from "../public/voice-conversation.mjs";
7
+
8
+ // Voice-loop unit tests: drive the dependency-injected controller with fake
9
+ // speech recognition, fake speech synthesis, and fake timers so the whole
10
+ // listen -> prompt -> speak -> listen contract runs deterministically in Node.
11
+
12
+ class FakeRecognition {
13
+ constructor(log) {
14
+ this.log = log;
15
+ this.started = false;
16
+ this.onresult = null;
17
+ this.onerror = null;
18
+ this.onend = null;
19
+ }
20
+ start() {
21
+ if (this.started) throw new Error("InvalidStateError: already started");
22
+ this.started = true;
23
+ this.log.push("recognition:start");
24
+ }
25
+ stop() {
26
+ this.started = false;
27
+ this.log.push("recognition:stop");
28
+ this.onend?.();
29
+ }
30
+ abort() {
31
+ this.started = false;
32
+ this.log.push("recognition:abort");
33
+ this.onend?.();
34
+ }
35
+ emitFinal(text) {
36
+ this.onresult?.({ resultIndex: 0, results: [Object.assign([{ transcript: text }], { isFinal: true })] });
37
+ }
38
+ emitInterim(text) {
39
+ this.onresult?.({ resultIndex: 0, results: [Object.assign([{ transcript: text }], { isFinal: false })] });
40
+ }
41
+ emitError(code) {
42
+ this.onerror?.({ error: code });
43
+ }
44
+ }
45
+
46
+ class FakeSynthesis {
47
+ constructor(log) {
48
+ this.log = log;
49
+ this.utterances = [];
50
+ this.cancelled = 0;
51
+ }
52
+ speak(utterance) {
53
+ this.utterances.push(utterance);
54
+ this.log.push(`synthesis:speak:${utterance.text}`);
55
+ }
56
+ cancel() {
57
+ this.cancelled += 1;
58
+ this.log.push("synthesis:cancel");
59
+ }
60
+ lastUtterance() {
61
+ return this.utterances[this.utterances.length - 1];
62
+ }
63
+ }
64
+
65
+ function createFakeTimers() {
66
+ let nextId = 1;
67
+ const timers = new Map();
68
+ return {
69
+ setTimeoutFn: (handler, delayMs) => {
70
+ const id = nextId++;
71
+ timers.set(id, { handler, delayMs });
72
+ return id;
73
+ },
74
+ clearTimeoutFn: (id) => timers.delete(id),
75
+ fireAll: () => {
76
+ for (const [id, timer] of [...timers]) {
77
+ timers.delete(id);
78
+ timer.handler();
79
+ }
80
+ },
81
+ count: () => timers.size,
82
+ };
83
+ }
84
+
85
+ async function tick(rounds = 4) {
86
+ for (let index = 0; index < rounds; index += 1) await Promise.resolve();
87
+ }
88
+
89
+ function createHarness({ bargeInEnabled = false, silenceTimeoutMs = 8000, tts = true, stt = true, failTranscript = false } = {}) {
90
+ const log = [];
91
+ const recognition = new FakeRecognition(log);
92
+ const synthesis = tts ? new FakeSynthesis(log) : null;
93
+ const transcripts = [];
94
+ const silenceEvents = [];
95
+ const partialTranscripts = [];
96
+ const states = [];
97
+ const events = [];
98
+ const timers = createFakeTimers();
99
+ const controller = createVoiceConversationController({
100
+ recognitionFactory: stt ? () => recognition : () => null,
101
+ synthesis,
102
+ utteranceFactory: tts ? (text) => ({ text, onend: null, onerror: null }) : null,
103
+ sendTranscript: async (text, { reason } = {}) => {
104
+ if (failTranscript) throw new Error("send failed");
105
+ transcripts.push({ text, reason });
106
+ },
107
+ sendSilenceEvent: async (info) => {
108
+ silenceEvents.push(info);
109
+ },
110
+ onPartialTranscript: (text) => partialTranscripts.push(text),
111
+ onStateChange: (uiState) => states.push(uiState),
112
+ onEvent: (message, level) => events.push({ message, level }),
113
+ bargeInEnabled,
114
+ silenceTimeoutMs,
115
+ setTimeoutFn: timers.setTimeoutFn,
116
+ clearTimeoutFn: timers.clearTimeoutFn,
117
+ });
118
+ return { controller, recognition, synthesis, transcripts, silenceEvents, partialTranscripts, states, events, timers, log };
119
+ }
120
+
121
+ // Exported state vocabulary matches the plan's visible states.
122
+ for (const expected of ["off", "listening", "transcribing", "answering", "speaking", "interrupting", "silence", "paused", "error"]) {
123
+ assert.ok(VOICE_UI_STATES.includes(expected), `VOICE_UI_STATES should include ${expected}`);
124
+ }
125
+ assert.match(voiceSilenceEventMessage(8), /stayed silent for 8s/, "silence event message should carry the silent duration");
126
+ assert.match(voiceSilenceEventMessage(8), /Do not invent intent/, "silence event message should instruct conservative interpretation");
127
+
128
+ // 1. start(): recognition begins and state is listening.
129
+ {
130
+ const h = createHarness();
131
+ h.controller.start();
132
+ assert.equal(h.controller.getState().uiState, "listening", "start should enter listening");
133
+ assert.equal(h.recognition.started, true, "start should start recognition");
134
+ assert.equal(h.controller.isActive(), true);
135
+ }
136
+
137
+ // 2. Final transcript while idle is sent as a normal prompt.
138
+ {
139
+ const h = createHarness();
140
+ h.controller.start();
141
+ h.recognition.emitInterim("what is");
142
+ assert.equal(h.controller.getState().uiState, "transcribing", "interim results should show transcribing");
143
+ assert.equal(h.controller.getState().partialTranscript, "what is", "interim results should be exposed as a partial transcript");
144
+ assert.deepEqual(h.partialTranscripts, ["what is"], "partial transcript listeners should receive interim text");
145
+ h.recognition.emitFinal("what is this repo about");
146
+ await tick();
147
+ assert.deepEqual(h.transcripts, [{ text: "what is this repo about", reason: "prompt" }]);
148
+ assert.equal(h.controller.getState().partialTranscript, "", "final transcripts should clear the partial preview");
149
+ assert.deepEqual(h.partialTranscripts, ["what is", ""], "partial transcript listeners should be cleared on final text");
150
+ assert.equal(h.controller.getState().uiState, "answering", "sent transcript should show answering");
151
+ }
152
+
153
+ // 3. Turn end speaks the final answer, pauses the mic, then resumes listening.
154
+ {
155
+ const h = createHarness();
156
+ h.controller.start();
157
+ h.controller.setAssistantActivity({ streaming: true });
158
+ h.controller.handleAssistantTurnEnd("The tests all pass.", { askedQuestion: false });
159
+ assert.equal(h.controller.getState().uiState, "speaking", "final text should be spoken");
160
+ assert.equal(h.synthesis.lastUtterance().text, "The tests all pass.");
161
+ assert.equal(h.recognition.started, false, "mic should be paused while speaking without barge-in");
162
+ h.synthesis.lastUtterance().onend();
163
+ assert.equal(h.controller.getState().uiState, "listening", "TTS end should resume listening");
164
+ assert.equal(h.recognition.started, true, "recognition should restart after speaking");
165
+ assert.equal(h.timers.count(), 0, "no silence timer without a question");
166
+ }
167
+
168
+ // 4. Barge-in enabled: speech during TTS cancels it and interrupts.
169
+ {
170
+ const h = createHarness({ bargeInEnabled: true });
171
+ h.controller.start();
172
+ h.controller.handleAssistantTurnEnd("Long answer being spoken aloud.", { askedQuestion: false });
173
+ assert.equal(h.controller.getState().uiState, "speaking");
174
+ assert.equal(h.recognition.started, true, "barge-in keeps the mic open while speaking");
175
+ const cancelledBefore = h.synthesis.cancelled;
176
+ h.recognition.emitFinal("stop and try something else");
177
+ await tick();
178
+ assert.ok(h.synthesis.cancelled > cancelledBefore, "barge-in should cancel active TTS");
179
+ assert.deepEqual(h.transcripts, [{ text: "stop and try something else", reason: "interrupt" }]);
180
+ assert.equal(h.controller.getState().uiState, "answering");
181
+ }
182
+
183
+ // 5. Speech during assistant final-output streaming is an interruption.
184
+ {
185
+ const h = createHarness();
186
+ h.controller.start();
187
+ h.controller.setAssistantActivity({ streaming: true });
188
+ h.recognition.emitFinal("actually use the other file");
189
+ await tick();
190
+ assert.deepEqual(h.transcripts, [{ text: "actually use the other file", reason: "interrupt" }]);
191
+ }
192
+
193
+ // 6. Speech during a tool phase is queued, then flushed after the tool ends.
194
+ {
195
+ const h = createHarness();
196
+ h.controller.start();
197
+ h.controller.setAssistantActivity({ streaming: true, toolRunning: true });
198
+ h.recognition.emitFinal("wait, stop reading files");
199
+ await tick();
200
+ assert.deepEqual(h.transcripts, [], "transcripts must not be injected during a tool phase");
201
+ assert.equal(h.controller.getState().uiState, "interrupting");
202
+ assert.equal(h.controller.getState().queuedInterrupt, "wait, stop reading files");
203
+ h.controller.setAssistantActivity({ toolRunning: false });
204
+ await tick();
205
+ assert.deepEqual(h.transcripts, [{ text: "wait, stop reading files", reason: "interrupt" }], "queued interrupt should flush after the tool phase");
206
+ }
207
+
208
+ // 7. A queued interrupt still pending at turn end becomes the next prompt and
209
+ // suppresses speaking the interrupted answer.
210
+ {
211
+ const h = createHarness();
212
+ h.controller.start();
213
+ h.controller.setAssistantActivity({ streaming: true, toolRunning: true });
214
+ h.recognition.emitFinal("never mind, different question");
215
+ await tick();
216
+ h.controller.handleAssistantTurnEnd("Here is the answer you interrupted.", { askedQuestion: false });
217
+ await tick();
218
+ assert.deepEqual(h.transcripts, [{ text: "never mind, different question", reason: "prompt" }], "queued interrupt should be delivered as the next turn");
219
+ assert.equal(h.synthesis.utterances.length, 0, "the interrupted answer must not be spoken");
220
+ }
221
+
222
+ // 8. Questions arm the silence timer; timeout emits one structured event.
223
+ {
224
+ const h = createHarness();
225
+ h.controller.start();
226
+ h.controller.handleAssistantTurnEnd("Should I continue with the refactor?", { askedQuestion: true });
227
+ h.synthesis.lastUtterance().onend();
228
+ assert.equal(h.timers.count(), 1, "a question should arm the silence timer");
229
+ h.timers.fireAll();
230
+ await tick();
231
+ assert.equal(h.silenceEvents.length, 1, "silence timeout should emit one event");
232
+ assert.equal(h.silenceEvents[0].silentSeconds, 8);
233
+ assert.equal(h.controller.getState().uiState, "answering", "silence event hands the turn back to the assistant");
234
+ }
235
+
236
+ // 9. User speech cancels a pending silence timer.
237
+ {
238
+ const h = createHarness();
239
+ h.controller.start();
240
+ h.controller.handleAssistantTurnEnd("Which branch should I use?", { askedQuestion: true });
241
+ h.synthesis.lastUtterance().onend();
242
+ assert.equal(h.timers.count(), 1);
243
+ h.recognition.emitFinal("use the main branch");
244
+ await tick();
245
+ assert.equal(h.timers.count(), 0, "answering the question should cancel the silence timer");
246
+ assert.deepEqual(h.transcripts, [{ text: "use the main branch", reason: "prompt" }]);
247
+ assert.equal(h.silenceEvents.length, 0);
248
+ }
249
+
250
+ // 10. Manual composer activity cancels the silence timer too.
251
+ {
252
+ const h = createHarness();
253
+ h.controller.start();
254
+ h.controller.handleAssistantTurnEnd("Anything else?", { askedQuestion: true });
255
+ h.synthesis.lastUtterance().onend();
256
+ assert.equal(h.timers.count(), 1);
257
+ h.controller.handleUserActivity();
258
+ assert.equal(h.timers.count(), 0, "typed prompts should cancel the silence timer");
259
+ }
260
+
261
+ // 11. STT unavailable: paused state, but answers are still spoken.
262
+ {
263
+ const h = createHarness({ stt: false });
264
+ h.controller.start();
265
+ assert.equal(h.controller.getState().uiState, "paused", "missing STT should pause listening, not error");
266
+ h.controller.handleAssistantTurnEnd("Spoken without a microphone.", { askedQuestion: false });
267
+ assert.equal(h.synthesis.lastUtterance().text, "Spoken without a microphone.");
268
+ h.synthesis.lastUtterance().onend();
269
+ assert.equal(h.controller.getState().uiState, "paused", "loop stays paused when STT is unavailable");
270
+ }
271
+
272
+ // 12. Neither STT nor TTS: explicit error state.
273
+ {
274
+ const h = createHarness({ stt: false, tts: false });
275
+ h.controller.start();
276
+ assert.equal(h.controller.getState().uiState, "error");
277
+ }
278
+
279
+ // 13. Microphone permission denial surfaces as an error and stops listening.
280
+ {
281
+ const h = createHarness();
282
+ h.controller.start();
283
+ h.recognition.emitError("not-allowed");
284
+ assert.equal(h.controller.getState().uiState, "error");
285
+ assert.equal(h.recognition.started, false, "denied permission should stop recognition");
286
+ assert.ok(h.events.some((event) => event.level === "error" && /Microphone access was denied/.test(event.message)));
287
+ }
288
+
289
+ // 14. Benign recognition end restarts listening automatically.
290
+ {
291
+ const h = createHarness();
292
+ h.controller.start();
293
+ h.recognition.started = false;
294
+ h.recognition.onend();
295
+ assert.equal(h.recognition.started, true, "spontaneous recognition end should restart the mic");
296
+ }
297
+
298
+ // 15. Manual pause stops listening without disabling the safe conversation mode;
299
+ // resume restarts the microphone and accepts transcripts again.
300
+ {
301
+ const h = createHarness();
302
+ h.controller.start();
303
+ h.controller.pause();
304
+ assert.equal(h.controller.isActive(), true, "pause must keep the controller active");
305
+ assert.equal(h.controller.getState().uiState, "paused");
306
+ assert.equal(h.controller.getState().userPaused, true);
307
+ assert.equal(h.recognition.started, false, "pause should stop recognition");
308
+ h.recognition.onend();
309
+ assert.equal(h.recognition.started, false, "paused recognition must not auto-restart on onend");
310
+ h.recognition.emitFinal("ignored while paused");
311
+ await tick();
312
+ assert.deepEqual(h.transcripts, [], "paused transcripts should be dropped");
313
+ h.controller.resume();
314
+ assert.equal(h.controller.getState().userPaused, false);
315
+ assert.equal(h.controller.getState().uiState, "listening");
316
+ assert.equal(h.recognition.started, true, "resume should restart recognition");
317
+ h.recognition.emitFinal("resume listening");
318
+ await tick();
319
+ assert.deepEqual(h.transcripts, [{ text: "resume listening", reason: "prompt" }]);
320
+ }
321
+
322
+ // 16. Pause clears pending silence timers and suppresses speaking the completed turn.
323
+ {
324
+ const h = createHarness();
325
+ h.controller.start();
326
+ h.controller.handleAssistantTurnEnd("Should I wait?", { askedQuestion: true });
327
+ h.synthesis.lastUtterance().onend();
328
+ assert.equal(h.timers.count(), 1, "question should arm silence timer before pause");
329
+ h.controller.pause();
330
+ assert.equal(h.timers.count(), 0, "pause should clear pending silence timers");
331
+ h.controller.setAssistantActivity({ streaming: true });
332
+ h.controller.handleAssistantTurnEnd("This should not be spoken while paused.", { askedQuestion: false });
333
+ assert.equal(h.synthesis.utterances.length, 1, "paused turn end should not enqueue new TTS");
334
+ }
335
+
336
+ // 17. stop() tears everything down.
337
+ {
338
+ const h = createHarness();
339
+ h.controller.start();
340
+ h.controller.handleAssistantTurnEnd("Do you want more detail?", { askedQuestion: true });
341
+ h.controller.stop();
342
+ assert.equal(h.controller.getState().uiState, "off");
343
+ assert.equal(h.controller.isActive(), false);
344
+ assert.equal(h.recognition.started, false, "stop should stop recognition");
345
+ assert.equal(h.timers.count(), 0, "stop should clear pending silence timers");
346
+ h.recognition.emitFinal("this should be ignored");
347
+ await tick();
348
+ assert.deepEqual(h.transcripts, [], "transcripts after stop are dropped");
349
+ }
350
+
351
+ // 18. Failed transcript delivery returns the loop to listening.
352
+ {
353
+ const h = createHarness({ failTranscript: true });
354
+ h.controller.start();
355
+ h.recognition.emitFinal("this will fail to send");
356
+ await tick();
357
+ assert.equal(h.controller.getState().uiState, "listening", "send failures should fall back to listening");
358
+ assert.ok(h.events.some((event) => event.level === "error" && /Failed to send voice transcript/.test(event.message)));
359
+ }
360
+
361
+ console.log("voice-conversation controller checks passed");