pi-reply-reader 0.0.0-stage → 0.2.0

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,1278 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import { readFileSync } from "node:fs";
3
+ import { homedir, hostname as osHostname } from "node:os";
4
+ import { basename, resolve } from "node:path";
5
+ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
6
+ import { type Component, type KeyId, SelectList } from "@earendil-works/pi-tui";
7
+ import { createAutoQueue, type StartResult } from "../src/auto-queue.ts";
8
+ import { configFile, loadOutputs, type Output } from "../src/outputs.ts";
9
+ import { createMusic, describeMusic, loadMusic, MUSIC_MODES, type MusicSettings, parseMusicArgs, saveMusic } from "../src/music.ts";
10
+ import { keyName, loadPauseKey } from "../src/pause-key.ts";
11
+ import { startOutputReading } from "../src/listener.ts";
12
+ import type { Reading, SherpaTts } from "../src/playback.ts";
13
+ import { playerTimeoutMs, reapOrphans } from "../src/player.ts";
14
+ import { questionsSection } from "../src/questions.ts";
15
+ import { projectChanged, projectOf } from "../src/project.ts";
16
+ import { askedQuestions, commandMarkdown, commandProgram, dialogTitle, QUESTION_TOOLS, questionsMarkdown, writtenCalls } from "../src/prompts.ts";
17
+ import { isPing, parseReadRequest, READER_EVENTS, READER_EVENTS_VERSION } from "../src/reader-events.ts";
18
+ import { type Claim, openReadingLock, type WaitingItem } from "../src/reading-lock.ts";
19
+ import { findReply, latestReply, listReplies } from "../src/replies.ts";
20
+ import { sectionFrom } from "../src/sections.ts";
21
+ import { formatSpeed, loadSaved, loadSpeed, parseSpeed, SPEED_CHOICES, SPEED_HINT, saveSettings, saveSpeed } from "../src/settings.ts";
22
+ import {
23
+ announcement,
24
+ detectLanguage,
25
+ type Fragment,
26
+ type Language,
27
+ languageOfWords,
28
+ projectAnnouncement,
29
+ speechNarration,
30
+ speechNarrationOfParts,
31
+ } from "../src/speech-text.ts";
32
+ import { downloadVoice, findVoice, SPEAKERS, type SpeakerName, type Voice } from "../src/voice.ts";
33
+
34
+ const STATUS = "reply-reader";
35
+ const ASK_OUTPUT = "Where should readings sound?";
36
+ const ASK_SPEAKER = "Which voice should read?";
37
+ const ASK_SPEED = "Which speed should readings use?";
38
+ const SPEAKER_NAMES = Object.keys(SPEAKERS) as SpeakerName[];
39
+ /** An argument naming a Markdown file rather than a reply (S6). */
40
+ const MARKDOWN_FILE = /\.(md|markdown)$/i;
41
+ /**
42
+ * How often a reading checks whether a newer one, or /read-stop, in another session took over (T21), and how often
43
+ * a waiting auto-read checks whether the machine is free (T32).
44
+ */
45
+ const WATCH_MS = 250;
46
+ /** What auto-read reads at the end of each agent turn (S8). */
47
+ type AutoMode = "off" | "full" | "questions";
48
+ const AUTO_CHOICES = [
49
+ { value: "on", description: "read each new reply in full" },
50
+ { value: "questions", description: 'read only its closing "Needs your decision" section' },
51
+ { value: "off", description: "read nothing by itself" },
52
+ ];
53
+ const AUTO_MESSAGES: Record<AutoMode, string> = {
54
+ full: "Auto-read on: full replies.",
55
+ questions: "Auto-read on: questions only.",
56
+ off: "Auto-read off.",
57
+ };
58
+ /** Asked when a manual /read or a read request comes while something plays (S8 Ask before cutting, T33). */
59
+ const ASK_CUT = "Something is being read.";
60
+ const CUT_NOW = "Stop it and read now";
61
+ const CUT_AFTER = "Read after it";
62
+ const CUT_CHOICES = [CUT_NOW, CUT_AFTER];
63
+ /** Just the question, centred over whatever is open (pi-reply-thread's Alt+R view is a capturing overlay too). */
64
+ const CUT_OVERLAY = { anchor: "center", width: 48 } as const;
65
+ /**
66
+ * Play order (S16, L135): a session's next waiting reading yields to an earlier one of another session while that
67
+ * session's line was published (its heartbeat, every WATCH_MS while it has readings waiting) within FRESH_MS, so a
68
+ * frozen or dead session stops holding the line about FRESH_MS after its last beat; 2 s leaves room for a loaded
69
+ * machine's late timers. YIELD_CAP_MS bounds the wait for one reading even for a session that beats but never starts;
70
+ * it counts only time the machine is free and the session yields, never time another reading plays (L138). A session
71
+ * waiting on a human (the output question, a voice download confirm) publishes it and is never yielded to.
72
+ */
73
+ const FRESH_MS = 2000;
74
+ const YIELD_CAP_MS = 10_000;
75
+ /** Seconds of silence before a reading that waited in the line, which then says which it is (S14). */
76
+ const GAP_SECONDS = 1.5;
77
+ /** What /read-pause, /read-stop and /read-next say (S1, S15, S16). */
78
+ const NOTHING_READ = "Nothing is being read.";
79
+ const PAUSED = "Reading paused.";
80
+ const RESUMED = "Reading resumed.";
81
+ const PROMPT_STOPPED = "Reading stopped: a prompt is not paused.";
82
+ const CANNOT_PAUSE = "The reading playing cannot be paused (it is not in a Pi session); /read-stop ends it.";
83
+ const NOTHING_WAITS = "Nothing waits to be read.";
84
+ const SKIPPED = "Skipped to the next reading.";
85
+ const NOTHING_NEXT = "Reading stopped; nothing else waits.";
86
+ /** What /read-music offers (S22). */
87
+ const MUSIC_CHOICES: Record<string, string> = {
88
+ off: "leave the music as it is",
89
+ pause: "pause gentle-stream while reading, play it again after",
90
+ duck: "lower gentle-stream's volume while reading (duck 20: to 20 %)",
91
+ };
92
+
93
+ /** The part of Pi's theme the question uses. */
94
+ interface QuestionTheme {
95
+ fg(color: "accent" | "border" | "dim" | "muted", text: string): string;
96
+ bold(text: string): string;
97
+ }
98
+
99
+ /**
100
+ * The "Something is being read." question as a small overlay of its own: a plain `ctx.ui.select` is drawn in the
101
+ * editor area, under any overlay open at the time (Alt+R), where it takes the keys unseen. Enter picks, Esc (or
102
+ * Ctrl+C) dismisses with undefined.
103
+ */
104
+ function cutQuestion(theme: QuestionTheme, done: (choice: string | undefined) => void): Component {
105
+ const list = new SelectList(
106
+ CUT_CHOICES.map((value) => ({ value, label: value })),
107
+ CUT_CHOICES.length,
108
+ {
109
+ selectedPrefix: (text) => theme.fg("accent", text),
110
+ selectedText: (text) => theme.fg("accent", text),
111
+ description: (text) => theme.fg("muted", text),
112
+ scrollInfo: (text) => theme.fg("dim", text),
113
+ noMatch: (text) => theme.fg("dim", text),
114
+ },
115
+ );
116
+ list.onSelect = (item) => done(item.value);
117
+ list.onCancel = () => done(undefined);
118
+ return {
119
+ render: (width) => {
120
+ const border = theme.fg("border", "─".repeat(Math.max(1, width)));
121
+ const inner = Math.max(1, width - 1);
122
+ return [
123
+ border,
124
+ ` ${theme.fg("accent", theme.bold(ASK_CUT))}`,
125
+ "",
126
+ ...list.render(inner).map((line) => ` ${line}`),
127
+ "",
128
+ ` ${theme.fg("dim", "↑↓ navigate enter select esc cancel")}`,
129
+ border,
130
+ ];
131
+ },
132
+ handleInput: (data) => list.handleInput(data),
133
+ invalidate: () => list.invalidate(),
134
+ };
135
+ }
136
+
137
+ /** Why a Markdown file could not be read, in the user's words. */
138
+ function readProblem(error: NodeJS.ErrnoException): string {
139
+ if (error.code === "ENOENT") return "file not found";
140
+ if (error.code === "EISDIR") return "it is a folder";
141
+ if (error.code === "EACCES" || error.code === "EPERM") return "permission denied";
142
+ return error.message;
143
+ }
144
+
145
+ /**
146
+ * Reads replies aloud on request only (S1): `/read` speaks the latest reply or one by ID, a new reading or
147
+ * `/read-stop` ends the one playing or paused; the pause key (Alt+M, or settings.json `pauseKey`) or `/read-pause`
148
+ * pauses it and resumes it from the start of the fragment it was in (S15; a blocking prompt's reading is ended
149
+ * instead); Esc is Pi's, never the reader's (L145, L147); `/read-queue` lists what waits on the
150
+ * machine and `/read-next` ends the current reading so the next one waiting starts (S16); `/read-output` picks where it sounds (S4) and `/read-voice` picks the male
151
+ * or female voice (S3), `/read-speed` the voice speed, saved in settings.json (S3). `/read <file.md>` reads a Markdown file the same way (S6). Nothing plays by itself.
152
+ * One reading per machine (S1, T21): through `$XDG_RUNTIME_DIR/pi-reply-reader/`, a new reading in any session
153
+ * stops the one playing in another, `/read-stop` stops it too, and the session stopped that way just clears its footer.
154
+ * `/read <target>#<section>` reads only the section under a matching heading, or on to the end with `rest` (S9). `/read-auto` (S8) reads each new reply, or only its
155
+ * "Needs your decision" section, as soon as it is stored, each once and in order (T42); its last choice, and the output's, are saved in settings.json
156
+ * for new sessions (S24; none saved: off, the output asked), and the footer shows it while on (S23). Auto-read never
157
+ * interrupts (S8 Queue, T32): a reply due while a reading plays here or in another session waits, in order, and is read
158
+ * once the machine is free; an explicit /read (or read request) or /read-stop drops every reply waiting on the
159
+ * machine (the pause key pauses instead, S15), and /read-auto off or the session's end drops this session's. A reading that waited in this line starts after
160
+ * 1.5 s of silence by saying which reply or file it is, and the footer counts what waits (S14, T38). A reading whose
161
+ * project (its Git root's folder name, src/project.ts) differs from the last reading's on the machine says it first (S19).
162
+ * Ask before cutting (S8, T33): a manual /read or read request while a reading plays anywhere asks "Something is being
163
+ * read.": "Stop it and read now" (the above), "Read after it" (it waits like an auto-read, after this session's waiting
164
+ * replies, and explicit actions drop it), or dismissed (nothing changes). Without a UI, or with nothing playing, it reads.
165
+ * An answer given after the session ended or restarted is dropped.
166
+ * Blocking prompts (S18, T43): with auto-read on (in full or questions only), an ask_user_question / ask_user_choice
167
+ * call reads its questions with their option labels, a confirm raised while a bash call is pending reads "Confirmación
168
+ * de comando: <program>", and any other dialog its title; each joins the line, and is dropped (stopped if playing)
169
+ * once answered (ui_prompt_end, or the tool's end). The reader's own questions are never read.
170
+ * Other extensions (pi-reply-thread's Alt+R view) reach it over `pi.events` (S10, src/reader-events.ts): a ping is
171
+ * answered with ready, ready is also sent at each session start, and a read request reads its text like `/read`.
172
+ * Music steps aside while the machine reads (S22, src/music.ts): `/read-music off|pause|duck [level]`, saved in
173
+ * settings.json; once per machine, restored when nothing reads or waits, on a pause, and at a session start after a
174
+ * reader died. A listener output's music is the listener's `--serve`'s to step aside.
175
+ */
176
+ export function createReplyReader(
177
+ deps: {
178
+ env?: NodeJS.ProcessEnv;
179
+ hostname?: string;
180
+ loadSherpa?: (voice: Voice) => Promise<SherpaTts>;
181
+ /** Test seam: while it returns true, this session's line starts nothing, as a session slow to claim (S16). */
182
+ holdLine?: () => boolean;
183
+ /** Test seam: replaces YIELD_CAP_MS (S16). */
184
+ yieldCapMs?: number;
185
+ /** Test seam: the project this process remembers at first, without XDG_RUNTIME_DIR (S19), as after a reading of it. */
186
+ lastProject?: string;
187
+ } = {},
188
+ ) {
189
+ const yieldCapMs = deps.yieldCapMs ?? YIELD_CAP_MS;
190
+ const env = deps.env ?? process.env;
191
+ const hostname = deps.hostname ?? osHostname();
192
+ /** The last reading's project when there is no usable XDG_RUNTIME_DIR to share it through: this process's (S19). */
193
+ const lastProject: { last?: string } = { last: deps.lastProject };
194
+
195
+ return (pi: ExtensionAPI): void => {
196
+ /** This session's reading, playing or paused (S15). */
197
+ interface Current {
198
+ /** Its player and synthesis; undefined while paused. */
199
+ reading?: Reading;
200
+ ctx: ExtensionContext;
201
+ claim?: Claim;
202
+ watch?: ReturnType<typeof setInterval>;
203
+ /** What the footer names, and where it sounds. */
204
+ name: string;
205
+ output: string;
206
+ /** It sounds through this machine (local or PULSE_SERVER), so the music steps aside here (S22); a listener's steps aside there. */
207
+ here: boolean;
208
+ /** A blocking prompt's reading (S18): its answer stops it, and a pause ends it instead (S15). */
209
+ prompt?: string;
210
+ /** The fragment `reading` started from; paused, the one it resumes from (S15). */
211
+ from: number;
212
+ /** Starts playing again from fragment `from`, with the same voice, speed and output (S15). */
213
+ play: (from: number) => void;
214
+ }
215
+ let current: Current | undefined;
216
+ /** The output chosen in this session, by name: the saved one (S24), else asked on the first reading. */
217
+ let chosen: string | undefined;
218
+ /** The voice for the next reading in this session (S3: male unless changed). */
219
+ let speaker: SpeakerName = "male";
220
+ /** Whether this session's first reading already reported problems in outputs.json. */
221
+ let warned = false;
222
+ /** A speed set with /read-speed in this session; otherwise each reading uses the saved one. */
223
+ let sessionSpeed: number | undefined;
224
+ /** Whether this session already reported a problem in settings.json. */
225
+ let speedWarned = false;
226
+ /** Whether this session already warned that a listener output read through its fallback (S20: once per session). */
227
+ let fallbackWarned = false;
228
+ /** A music mode (and level) set with /read-music in this session; otherwise each reading uses the saved one (S22). */
229
+ let sessionMusic: Pick<MusicSettings, "mode"> & Partial<Pick<MusicSettings, "level">> | undefined;
230
+ /** Whether this session already said that music settings were ignored, or that a music command failed (S22). */
231
+ let musicProblemWarned = false;
232
+ let musicWarned = false;
233
+ /** The pause key (S15, L147): settings.json `pauseKey`, else Alt+M; read once, as Pi registers shortcuts at load. */
234
+ const pauseKey = loadPauseKey(env);
235
+ const pauseName = keyName(pauseKey.key);
236
+ /** Whether the problem with `pauseKey` was told (once, at the first session start with a UI). */
237
+ let pauseKeyWarned = false;
238
+ /** This session's auto-read mode (S8: off at session start unless settings.json saved one, S24). */
239
+ let auto: AutoMode = "off";
240
+ /** The footer last shown (S14, S23): shown again only when it changed. */
241
+ let shownFooter: string | undefined;
242
+ /**
243
+ * The entry IDs of the replies auto-read already queued or must never read (S8 Timing, T42): those on the branch
244
+ * when auto-read was turned on or the branch changed under it. Every other final reply is queued once.
245
+ */
246
+ let seen = new Set<string>();
247
+ /** The context of the latest session_start or command; bus events carry none (S10). Unset outside a session. */
248
+ let latest: ExtensionContext | undefined;
249
+ /** Ends this session's subscriptions on `pi.events`. */
250
+ let unsubscribeEvents: (() => void) | undefined;
251
+
252
+ /** Counts session starts and ends: an answer given after the session it was asked in ended or restarted is dropped. */
253
+ let generation = 0;
254
+ /** How many of the reader's own prompts (output, voice, speed, download confirm, the cut question) are open (S18). */
255
+ let ownPrompts = 0;
256
+ /** Tool calls started and not yet ended, in start order (S18): an ask_user_* call, or the bash a confirm is about. */
257
+ const pending = new Map<string, { toolName: string; args: unknown }>();
258
+ /** The prompt readings the open ui_prompt span answers when it ends (S18). */
259
+ let spanPrompts: string[] = [];
260
+ /** The text the latest assistant message wrote, by the IDs of the tool calls it made (S18 Context, T48). */
261
+ let writtenBefore = new Map<string, string>();
262
+ /** The keys of the prompt readings queued and not yet answered (S18). */
263
+ const prompts = new Set<string>();
264
+ /** Numbers dialogs, so each gets its own prompt key. */
265
+ let dialogs = 0;
266
+ /** Names this session's published line on the machine (S16). */
267
+ const lineToken = randomUUID();
268
+ /**
269
+ * When the latest reading joined the line; each later one joins strictly after it. Sub-millisecond wall-clock time,
270
+ * so readings two sessions queue within the same millisecond still list in the order they came (S16).
271
+ */
272
+ let lastJoined = 0;
273
+ const joined = (): number => (lastJoined = Math.max(performance.timeOrigin + performance.now(), lastJoined + 0.001));
274
+
275
+ /**
276
+ * A reply due for auto-read, or a manual request answered "Read after it" (T33), with the machine's waiting mark
277
+ * when it was queued (S8 Queue). `name` and `label` are as for readAloud.
278
+ */
279
+ interface Waiting {
280
+ ctx: ExtensionContext;
281
+ name: string;
282
+ label: string;
283
+ /** One document, or parts cleaned apart and read in order (a prompt's text, then its questions: T48). */
284
+ markdown: string | readonly string[];
285
+ language: Language | undefined;
286
+ mark: string | undefined;
287
+ manual?: true;
288
+ /** A Markdown file rather than a reply: announced by its name (S14). */
289
+ file?: true;
290
+ /** A blocking prompt (S18): the key its answer drops it by. It says what it is, so it gets no announcement. */
291
+ prompt?: string;
292
+ /** When it joined the line (S16: the machine's list is in this order). */
293
+ at: number;
294
+ }
295
+ /** Whether a reading plays (or is starting) in this session or anywhere on the machine. */
296
+ const playing = (): boolean => current !== undefined || (openReadingLock(env)?.busy() ?? false);
297
+ /**
298
+ * The first reading of this line while it yields to an earlier one elsewhere (S16): the free time spent yielding
299
+ * so far, and the check that last counted (unset while another reading plays, so that time is not counted, L138).
300
+ */
301
+ let yielding: { at: number; spent: number; last?: number } | undefined;
302
+ /**
303
+ * Whether this line's first reading lets an earlier one of another session go first, so readings play in
304
+ * /read-queue's order (S16, L135): while that session still beats (FRESH_MS) and is not waiting on a human, and
305
+ * for at most the yield cap of free time per reading (L138).
306
+ */
307
+ const yields = (): boolean => {
308
+ const head = queue.items[0];
309
+ const lock = head ? openReadingLock(env) : undefined;
310
+ const now = Date.now();
311
+ const earlier =
312
+ head !== undefined &&
313
+ (lock?.waitingList() ?? []).some(
314
+ (item) => item.token !== lineToken && item.at < head.at && !item.asking && item.beat !== undefined && now - item.beat < FRESH_MS,
315
+ );
316
+ if (!head || !earlier) {
317
+ yielding = undefined;
318
+ return false;
319
+ }
320
+ if (yielding?.at !== head.at) yielding = { at: head.at, spent: 0 };
321
+ if (yielding.last !== undefined) yielding.spent += now - yielding.last;
322
+ yielding.last = now;
323
+ return yielding.spent < yieldCapMs;
324
+ };
325
+ /** Whether this line must wait: a reading plays (its time does not count toward the yield cap), or it yields. */
326
+ const lineBusy = (): boolean => {
327
+ if (playing()) {
328
+ if (yielding) yielding.last = undefined;
329
+ return true;
330
+ }
331
+ return (deps.holdLine?.() ?? false) || yields();
332
+ };
333
+ /** How many of this session's questions to a human (output, voice download) are open before a reading (S16, L138). */
334
+ let humanWait = 0;
335
+ const human = async <T>(prompt: () => Promise<T>): Promise<T> => {
336
+ humanWait++;
337
+ publish();
338
+ try {
339
+ return await prompt();
340
+ } finally {
341
+ humanWait--;
342
+ publish();
343
+ }
344
+ };
345
+ /** Republishes this session's line every WATCH_MS while it has readings waiting: its heartbeat (S16). */
346
+ let beating: ReturnType<typeof setInterval> | undefined;
347
+ const heartbeat = (): void => {
348
+ if (queue.size === 0 && !queue.starting) {
349
+ clearInterval(beating);
350
+ beating = undefined;
351
+ return;
352
+ }
353
+ if (beating) return;
354
+ // Each beat also checks whether the line emptied meanwhile (a start dropped while it waited on a human, L138).
355
+ beating = setInterval(() => {
356
+ publish();
357
+ heartbeat();
358
+ }, WATCH_MS);
359
+ beating.unref?.();
360
+ };
361
+ /** This session's waiting auto-reads; without a usable XDG_RUNTIME_DIR it only waits for this session's readings. */
362
+ const queue = createAutoQueue<Waiting>({
363
+ busy: lineBusy,
364
+ start: (item, still, waited) =>
365
+ readAloud(item.ctx, item.name, item.label, item.markdown, item.language, {
366
+ mark: item.mark,
367
+ still,
368
+ announce: waited ? (item.prompt ? "prompt" : item.file ? "file" : "reply") : undefined,
369
+ prompt: item.prompt,
370
+ }).catch((error: Error) => {
371
+ item.ctx.ui.notify(error.message, "error");
372
+ return "done" as const;
373
+ }),
374
+ retryMs: WATCH_MS,
375
+ // The footer follows at each place that changes the line, as before, and other sessions' lines on its checks.
376
+ onChange: () => {
377
+ publish();
378
+ heartbeat();
379
+ },
380
+ });
381
+
382
+ /** The music settings for the next step aside (S22): this session's /read-music, over the saved ones. */
383
+ const musicSettings = (): MusicSettings => {
384
+ const { music } = loadMusic(env);
385
+ return sessionMusic ? { ...music, ...sessionMusic } : music;
386
+ };
387
+ /**
388
+ * Music steps aside while the machine reads (S22): when this session takes the machine's reading turn, and back
389
+ * once nothing reads or waits on the machine (any session's end of the line, a pause, a session start after a
390
+ * reader died). Commands run in the background; a failure is said once per session.
391
+ */
392
+ const music = createMusic({
393
+ env,
394
+ settings: musicSettings,
395
+ idle: () => current === undefined && queue.starting === undefined && !(openReadingLock(env)?.busy() ?? false) && waitingCount() === 0,
396
+ warn: (message) => {
397
+ const ctx = current?.ctx ?? latest;
398
+ if (musicWarned || !ctx) return;
399
+ musicWarned = true;
400
+ ctx.ui.notify(message, "warning");
401
+ },
402
+ });
403
+ /** Steps the music aside for a reading that sounds here, telling once per session about ignored settings. */
404
+ const stepAside = (ctx: ExtensionContext): void => {
405
+ const { problem } = loadMusic(env);
406
+ if (problem && !sessionMusic && !musicProblemWarned) {
407
+ musicProblemWarned = true;
408
+ ctx.ui.notify(problem, "warning");
409
+ }
410
+ music.stepAside();
411
+ };
412
+
413
+ /** This session as /read-queue names it: its name (Pi's /name), else its working folder. */
414
+ const sessionLabel = (): string => {
415
+ const ctx = latest;
416
+ if (!ctx) return "a Pi session";
417
+ const named = (ctx.sessionManager as Partial<ExtensionContext["sessionManager"]>).getSessionName?.();
418
+ return named || basename(ctx.cwd) || ctx.cwd;
419
+ };
420
+ /**
421
+ * What tells this session apart from another with the same label in /read-queue (S16): the last four characters of
422
+ * Pi's session id (its random part), else of this line's token.
423
+ */
424
+ const sessionTag = (): string | undefined => {
425
+ const id = (latest?.sessionManager as Partial<ExtensionContext["sessionManager"]> | undefined)?.getSessionId?.();
426
+ return typeof id === "string" && id ? id.replace(/-/g, "").slice(-4) : undefined;
427
+ };
428
+ /** Publishes this session's line next to the reading lock, so every session sees the machine's (S16). */
429
+ const publish = (): void => {
430
+ // The one being started stays listed until it claims the machine, so no other session takes its turn meanwhile.
431
+ const line = queue.starting && !current ? [queue.starting, ...queue.items] : queue.items;
432
+ const items: WaitingItem[] = line.map((item) => ({ name: item.name, at: item.at, mark: item.mark }));
433
+ openReadingLock(env)?.publishLine(lineToken, sessionLabel(), items, sessionTag(), humanWait > 0);
434
+ // The line emptied with nothing read (dropped, /read-auto off): music left aside comes back (S22).
435
+ if (items.length === 0) music.settle();
436
+ };
437
+ /** How many readings wait: on the machine, or in this session's line without a usable XDG_RUNTIME_DIR (S16). */
438
+ const waitingCount = (): number => {
439
+ const lock = openReadingLock(env);
440
+ return lock ? lock.waitingList().length : queue.size;
441
+ };
442
+
443
+ /** Runs one of the reader's own prompts; a ui_prompt_start meanwhile is the reader's and is not read (S18). */
444
+ const own = async <T>(prompt: () => Promise<T>): Promise<T> => {
445
+ ownPrompts++;
446
+ try {
447
+ return await prompt();
448
+ } finally {
449
+ ownPrompts--;
450
+ }
451
+ };
452
+
453
+ /** Registers a command whose context becomes the one bus events read with. */
454
+ const command = (name: string, options: Parameters<ExtensionAPI["registerCommand"]>[1]): void =>
455
+ pi.registerCommand(name, {
456
+ ...options,
457
+ handler: (args, ctx) => {
458
+ latest = ctx;
459
+ return options.handler(args, ctx);
460
+ },
461
+ });
462
+
463
+ /**
464
+ * Shows this session's reading in the footer, with how many readings wait on the machine (S14, S16):
465
+ * `Reading P12.R2 on local · 2 waiting · Alt+M pauses`, or paused (S15) `Paused P12.R2 · Alt+M resumes · /read-stop ends`.
466
+ * While auto-read is on (S23) it always shows it, with the chosen output while nothing is read here
467
+ * (`Auto-read on · desktop`, `Auto-read questions`) and before the reading's status while one is
468
+ * (`Auto-read on · Reading P12.R2 on desktop · Alt+M pauses`). Shown again only when it changed.
469
+ */
470
+ const footer = (ctx: ExtensionContext | undefined = current?.ctx ?? latest): void => {
471
+ let reading: string | undefined;
472
+ if (current) {
473
+ const waiting = waitingCount();
474
+ const count = waiting > 0 ? `${waiting} waiting · ` : "";
475
+ reading = current.reading
476
+ ? `Reading ${current.name} on ${current.output} · ${count}${pauseName} pauses`
477
+ : `Paused ${current.name} · ${count}${pauseName} resumes · /read-stop ends`;
478
+ }
479
+ const mode = auto === "off" ? undefined : `Auto-read ${auto === "full" ? "on" : "questions"}`;
480
+ const text = mode ? [mode, reading ?? chosen].filter(Boolean).join(" · ") : reading;
481
+ if (text === shownFooter || !ctx) return;
482
+ shownFooter = text;
483
+ ctx.ui.setStatus(STATUS, text);
484
+ };
485
+
486
+ /** Saves `values` in settings.json for new sessions (S24); the reason it could not, else undefined. */
487
+ const save = (values: Record<string, unknown>): string | undefined => {
488
+ try {
489
+ saveSettings(env, values);
490
+ return undefined;
491
+ } catch (error) {
492
+ return (error as Error).message;
493
+ }
494
+ };
495
+
496
+ /**
497
+ * Ends this session's reading, playing or paused, and clears its footer; another session's reading is left alone.
498
+ * `replacing`: a new reading of this session takes its place at once, so the music stays aside (S22: not idle).
499
+ */
500
+ const stop = (replacing = false): void => {
501
+ if (!current) return;
502
+ const { reading, ctx, claim, watch } = current;
503
+ current = undefined;
504
+ clearInterval(watch);
505
+ reading?.stop();
506
+ claim?.release();
507
+ // Nothing reads or waits on the machine any more: the music comes back (S22); between queued readings it stays aside.
508
+ if (!replacing) music.settle();
509
+ footer(ctx);
510
+ // A reply waiting for this reading may start now.
511
+ queue.kick();
512
+ };
513
+
514
+ /**
515
+ * Pauses this session's reading (S15): its player ends, and it keeps its turn on the machine with no player, so
516
+ * nothing waiting starts and the S13 watchdog has nothing to watch. It resumes from the start of the fragment
517
+ * being heard. A prompt's reading (S18) is ended instead: the prompt is still on screen, and what waits goes on.
518
+ */
519
+ const pause = (): void => {
520
+ const state = current;
521
+ if (!state?.reading) return;
522
+ if (state.prompt) return stop();
523
+ const { reading } = state;
524
+ state.from += reading.position();
525
+ state.reading = undefined;
526
+ state.claim?.setPaused(true);
527
+ reading.stop();
528
+ // Paused, the music comes back; resuming steps it aside again (S22).
529
+ music.settle({ force: true });
530
+ footer();
531
+ };
532
+
533
+ /** Resumes this session's paused reading from the fragment it was in (S15). */
534
+ const resume = (): void => {
535
+ const state = current;
536
+ if (!state || state.reading) return;
537
+ state.claim?.setPaused(false);
538
+ // A listener reading that went to its fallback sounds here: it steps the music here aside again too (S20, S22).
539
+ state.play(state.from);
540
+ if (state.here) stepAside(state.ctx);
541
+ footer();
542
+ };
543
+
544
+ /** All outputs, telling the user about any entry of outputs.json that was skipped. */
545
+ const outputs = (ctx: ExtensionContext): Output[] => {
546
+ const loaded = loadOutputs(env, hostname);
547
+ for (const problem of loaded.problems) ctx.ui.notify(problem, "warning");
548
+ return loaded.outputs;
549
+ };
550
+
551
+ const askOutput = async (ctx: ExtensionContext, list: Output[]): Promise<Output | undefined> => {
552
+ if (!ctx.hasUI) return undefined;
553
+ const label = await own(() => ctx.ui.select(ASK_OUTPUT, list.map((output) => output.label)));
554
+ const output = list.find((candidate) => candidate.label === label);
555
+ if (!output) return undefined;
556
+ chosen = output.name;
557
+ footer(ctx);
558
+ // The pick is remembered for new sessions (S24).
559
+ const unsaved = save({ output: output.name });
560
+ if (unsaved) ctx.ui.notify(`Readings will sound on ${output.label} in this session, but ${unsaved}.`, "warning");
561
+ return output;
562
+ };
563
+
564
+ const outputForReading = async (ctx: ExtensionContext): Promise<Output | undefined> => {
565
+ // A typo in outputs.json must not silently send the reading to local; say so once per session.
566
+ const list = warned ? loadOutputs(env, hostname).outputs : outputs(ctx);
567
+ warned = true;
568
+ const remembered = list.find((output) => output.name === chosen);
569
+ if (remembered) return remembered;
570
+ if (list.length === 1) return list[0];
571
+ return askOutput(ctx, list);
572
+ };
573
+
574
+ /** The speed for a new reading: this session's choice, else the saved one, warning once about a bad file. */
575
+ const speedForReading = (ctx: ExtensionContext): number => {
576
+ if (sessionSpeed !== undefined) return sessionSpeed;
577
+ const { speed, problem } = loadSpeed(env);
578
+ if (problem && !speedWarned) ctx.ui.notify(problem, "warning");
579
+ if (problem) speedWarned = true;
580
+ return speed;
581
+ };
582
+
583
+ /**
584
+ * Reads Markdown aloud: the voice (download confirm), the output (asked on first use), the speed and voice of this
585
+ * session, the footer, the pause key, /read-stop and one reading per machine. Used by /read, read requests and auto-read.
586
+ * `name` is what the footer names, `label` what the "nothing to read" message names.
587
+ * Explicit (no `auto`): stops the reading playing and drops every waiting auto-read on the machine. Auto: starts
588
+ * only when nothing plays and its reply was not dropped (`still`, the waiting mark), else answers "busy" or "done".
589
+ * `announce` (a reading that waited in the line, S14): it starts after GAP_SECONDS of silence by saying which it is;
590
+ * a blocking prompt (S18) already says what it is, so it gets the silence only. `prompt` is its key.
591
+ */
592
+ const readAloud = async (
593
+ ctx: ExtensionContext,
594
+ name: string,
595
+ label: string,
596
+ markdown: string | readonly string[],
597
+ language?: Language,
598
+ auto?: { mark: string | undefined; still: () => boolean; announce?: "reply" | "file" | "prompt"; prompt?: string },
599
+ ): Promise<StartResult> => {
600
+ const narration = typeof markdown === "string" ? speechNarration(markdown, language) : speechNarrationOfParts(markdown, language ?? detectLanguage(markdown.join("\n\n")));
601
+ if (!narration.text) {
602
+ ctx.ui.notify(`${label} has nothing to read.`, "info");
603
+ return "done";
604
+ }
605
+
606
+ let voice = findVoice(env);
607
+ if (!voice) {
608
+ try {
609
+ voice = await downloadVoice({
610
+ env,
611
+ confirm: async (message) => ctx.hasUI && human(() => own(() => ctx.ui.confirm("Reply reader voice", message))),
612
+ });
613
+ } catch (error) {
614
+ ctx.ui.notify((error as Error).message, "error");
615
+ return "done";
616
+ }
617
+ if (!voice) {
618
+ ctx.ui.notify("Reading cancelled: the voice was not downloaded.", "info");
619
+ return "done";
620
+ }
621
+ }
622
+
623
+ const output = await human(() => outputForReading(ctx));
624
+ if (!output) {
625
+ ctx.ui.notify("Reading cancelled: no output chosen.", "info");
626
+ return "done";
627
+ }
628
+
629
+ // Without a usable XDG_RUNTIME_DIR there is no claim: readings and the queue only see this session's.
630
+ const lock = openReadingLock(env);
631
+ let claim: Claim | undefined;
632
+ if (auto) {
633
+ // Dropped while asking (an explicit action, /read-auto off, the session's end): nothing plays.
634
+ if (!auto.still()) return "done";
635
+ if (current) return "busy";
636
+ const taken = lock?.claimIfFree(auto.mark, { pausable: true, prompt: auto.prompt !== undefined });
637
+ if (taken === "dropped") return "done";
638
+ if (taken === "busy") return "busy";
639
+ claim = taken;
640
+ } else {
641
+ queue.clear();
642
+ // Replaced, not idle: the music stays aside for the new reading (S22).
643
+ stop(true);
644
+ claim = lock?.claim({ dropWaiting: true, pausable: true });
645
+ }
646
+ const speed = speedForReading(ctx);
647
+ // An invalid REPLY_READER_PLAYER_TIMEOUT is reported once per process and the default used (S13 f).
648
+ const timeoutMs = playerTimeoutMs(env, (message) => ctx.ui.notify(message, "warning"));
649
+ // Resuming (S15) uses the voice, speed and output the reading started with.
650
+ const voiceOf = SPEAKERS[speaker];
651
+ // Started: a project other than the last reading's on the machine is said first (S19), then which it is (S14).
652
+ const project = projectOf(ctx.cwd);
653
+ const said = projectChanged(env, project, lastProject) ? projectAnnouncement(project, narration.language) : [];
654
+ const fragments: readonly Fragment[] = [
655
+ ...said,
656
+ ...(auto?.announce && auto.announce !== "prompt" ? announcement(auto.announce, name, narration.language) : []),
657
+ ...narration.fragments,
658
+ ];
659
+ const state: Current = { ctx, claim, name, output: output.name, here: !output.ssh, prompt: auto?.prompt, from: 0, play: () => {} };
660
+ /** Stopped by another session: no message, just the footer. */
661
+ const stoppedElsewhere = (): void => {
662
+ if (current === state) stop();
663
+ };
664
+ /** Plays from fragment `from`; the gap before a reading that waited only comes before its very start (S14). */
665
+ const play = (from: number, leadSilence?: number): void => {
666
+ const reading = startOutputReading({
667
+ voice,
668
+ speaker: voiceOf,
669
+ fragments: fragments.slice(from),
670
+ leadSilence,
671
+ output,
672
+ env,
673
+ loadSherpa: deps.loadSherpa,
674
+ speed,
675
+ timeoutMs,
676
+ onPlayer: (pid) => {
677
+ // A player of a reading paused meanwhile is already being ended; it must not stand for this one.
678
+ if (state.reading !== reading) return;
679
+ if (claim && !claim.setPlayer(pid)) stoppedElsewhere();
680
+ },
681
+ // A listener output that cannot read goes on through its fallback (S20), said once per session.
682
+ onFallback: (message) => {
683
+ // It sounds here after all: the music here steps aside (S22), and again at each resume (S15).
684
+ state.here = true;
685
+ if (current === state) stepAside(ctx);
686
+ if (fallbackWarned) return;
687
+ fallbackWarned = true;
688
+ ctx.ui.notify(message, "warning");
689
+ },
690
+ lost: () => current !== state || state.reading !== reading || (claim?.lost() ?? false),
691
+ });
692
+ state.reading = reading;
693
+ state.from = from;
694
+ reading.done
695
+ .catch((error: Error) => {
696
+ // A player killed by a newer reading or /read-stop elsewhere fails; that is not an error here.
697
+ if (current === state && state.reading === reading && !claim?.lost()) ctx.ui.notify(error.message, "error");
698
+ })
699
+ .finally(() => {
700
+ // Paused (S15): this reading ended on purpose and the state waits to resume.
701
+ if (current !== state || state.reading !== reading) return;
702
+ stop();
703
+ });
704
+ };
705
+ // Resuming never says the project again, even when paused while it was being said (S19).
706
+ state.play = (from) => play(Math.max(from, said.length));
707
+ play(0, auto?.announce ? GAP_SECONDS : undefined);
708
+ // Another session's /read-stop, newer reading, /read-next or /read-pause (S1, S15, S16) reach this reading through
709
+ // its entry; the footer also follows what waits on the machine.
710
+ state.watch = claim
711
+ ? setInterval(() => {
712
+ if (current !== state) return;
713
+ if (claim.lost()) return stoppedElsewhere();
714
+ const wanted = claim.paused();
715
+ if (wanted === true && state.reading) pause();
716
+ else if (wanted === false && !state.reading) resume();
717
+ footer();
718
+ }, WATCH_MS)
719
+ : undefined;
720
+ state.watch?.unref();
721
+ current = state;
722
+ // The machine's line went idle → reading: the music where it sounds steps aside, never delaying speech (S22).
723
+ // A reading on a listener restores music left aside here (by the one it replaced, S22); a fallback steps it aside again.
724
+ if (state.here) stepAside(ctx);
725
+ else music.settle({ force: true });
726
+ // Started: it no longer waits in the machine's list (S16).
727
+ publish();
728
+ footer();
729
+ return "done";
730
+ };
731
+
732
+ /**
733
+ * Asks "Something is being read." (T33): as an overlay of its own in Pi's TUI, so it shows above another overlay
734
+ * (Alt+R); elsewhere (RPC, a host without overlays) through ctx.ui.select. Undefined when dismissed.
735
+ */
736
+ const askCut = async (ctx: ExtensionContext): Promise<"now" | "after" | undefined> => {
737
+ ownPrompts++;
738
+ try {
739
+ const choice =
740
+ ctx.mode === "tui" && typeof ctx.ui.custom === "function"
741
+ ? await ctx.ui.custom<string | undefined>((_tui, theme, _keybindings, done) => cutQuestion(theme, done), {
742
+ overlay: true,
743
+ overlayOptions: CUT_OVERLAY,
744
+ })
745
+ : await ctx.ui.select(ASK_CUT, CUT_CHOICES);
746
+ return choice === CUT_NOW ? "now" : choice === CUT_AFTER ? "after" : undefined;
747
+ } finally {
748
+ ownPrompts--;
749
+ }
750
+ };
751
+
752
+ /**
753
+ * A manual /read or a read request (S8 Ask before cutting): with a UI and a reading playing anywhere, asks first.
754
+ * The answer is acted on as things are then: "Read after it" joins the line, which starts it at once if the
755
+ * reading ended meanwhile; "Stop it and read now" stops whatever plays by then.
756
+ */
757
+ const readRequested = async (
758
+ ctx: ExtensionContext,
759
+ name: string,
760
+ label: string,
761
+ markdown: string,
762
+ language?: Language,
763
+ file?: true,
764
+ ): Promise<void> => {
765
+ if (ctx.hasUI && playing() && speechNarration(markdown, language).text) {
766
+ const asked = generation;
767
+ const answer = await askCut(ctx);
768
+ // The session ended or restarted while the question was open: nothing plays in it, no message.
769
+ if (!answer || generation !== asked) return;
770
+ if (answer === "after") {
771
+ queue.push({ ctx, name, label, markdown, language, mark: openReadingLock(env)?.waitingMark(), manual: true, file, at: joined() });
772
+ footer();
773
+ return;
774
+ }
775
+ }
776
+ await readAloud(ctx, name, label, markdown, language);
777
+ };
778
+
779
+ command("read", {
780
+ description:
781
+ "Read a reply aloud: the latest, or one by ID (P12.R1); or a Markdown file (notes.md); add #section for one section (notes.md#install, #usage), then rest to read on to the end",
782
+ handler: async (args, ctx) => {
783
+ let wanted = args.trim();
784
+ /** The section to read (S9); a whole argument that is a Markdown path keeps any `#` in its name. */
785
+ let section: string | undefined;
786
+ /** `#section rest` reads from that heading to the end instead of that section only. */
787
+ let rest = false;
788
+ const hash = wanted.indexOf("#");
789
+ if (hash !== -1 && !MARKDOWN_FILE.test(wanted)) {
790
+ section = wanted.slice(hash + 1).trim();
791
+ wanted = wanted.slice(0, hash).trim();
792
+ const words = /^(.*\S)\s+rest$/.exec(section);
793
+ if (words) {
794
+ section = words[1];
795
+ rest = true;
796
+ }
797
+ }
798
+ /** What the status line names: the reply ID or the file name. */
799
+ let name: string;
800
+ /** What the "nothing to read" message names: the reply ID or the path as given. */
801
+ let label: string;
802
+ let markdown: string;
803
+ const file = MARKDOWN_FILE.test(wanted) ? (true as const) : undefined;
804
+ if (file) {
805
+ const path = wanted.startsWith("~/") ? resolve(env.HOME || homedir(), wanted.slice(2)) : resolve(ctx.cwd, wanted);
806
+ try {
807
+ markdown = readFileSync(path, "utf8");
808
+ } catch (error) {
809
+ ctx.ui.notify(`Cannot read "${wanted}": ${readProblem(error as NodeJS.ErrnoException)}.`, "warning");
810
+ return;
811
+ }
812
+ name = basename(path);
813
+ label = wanted;
814
+ } else {
815
+ const replies = listReplies(ctx.sessionManager.getBranch());
816
+ const reply = wanted ? findReply(replies, wanted) : latestReply(replies);
817
+ if (!reply) {
818
+ ctx.ui.notify(wanted ? `No reply matches "${wanted}".` : "There is no reply to read yet.", "warning");
819
+ return;
820
+ }
821
+ name = reply.id;
822
+ label = reply.id;
823
+ markdown = reply.text;
824
+ }
825
+ let language: Language | undefined;
826
+ if (section) {
827
+ // The section reads in the language of the whole file or reply (S7), not its own few words.
828
+ language = detectLanguage(markdown);
829
+ const from = sectionFrom(markdown, section, { rest });
830
+ if (from === undefined) {
831
+ ctx.ui.notify(`No section "${section}" in ${label}.`, "warning");
832
+ return;
833
+ }
834
+ markdown = from;
835
+ }
836
+ await readRequested(ctx, name, label, markdown, language, file);
837
+ },
838
+ });
839
+
840
+ command("read-stop", {
841
+ description: "End the reading, playing or paused, in this or another Pi session, and drop the ones waiting (a new /read ends it too)",
842
+ handler: async (_args, ctx) => {
843
+ const here = current !== undefined;
844
+ queue.clear();
845
+ stop();
846
+ // Also drops every auto-read waiting on the machine (S8).
847
+ const elsewhere = openReadingLock(env)?.stopOthers() ?? false;
848
+ ctx.ui.notify(here || elsewhere ? "Reading stopped." : NOTHING_READ, "info");
849
+ },
850
+ });
851
+
852
+ /** /read-pause and the pause key (S15, L147): pauses or resumes this session's reading, else another session's. */
853
+ const togglePause = (ctx: ExtensionContext): void => {
854
+ if (current) {
855
+ if (current.prompt) {
856
+ stop();
857
+ ctx.ui.notify(PROMPT_STOPPED, "info");
858
+ } else if (current.reading) {
859
+ pause();
860
+ ctx.ui.notify(PAUSED, "info");
861
+ } else {
862
+ resume();
863
+ ctx.ui.notify(RESUMED, "info");
864
+ }
865
+ return;
866
+ }
867
+ // Another session's reading (S1): its own session pauses or resumes it on its next check.
868
+ const result = openReadingLock(env)?.togglePause();
869
+ const messages = { paused: PAUSED, resumed: RESUMED, stopped: PROMPT_STOPPED, unsupported: CANNOT_PAUSE };
870
+ ctx.ui.notify(result ? messages[result] : NOTHING_READ, "info");
871
+ };
872
+
873
+ command("read-pause", {
874
+ description: `Pause the reading playing, in this or another Pi session, or resume it from the sentence it was in (${pauseName} too)`,
875
+ handler: async (_args, ctx) => togglePause(ctx),
876
+ });
877
+
878
+ // Esc is Pi's (it interrupts the agent, closes dialogs): the reader never takes it (L145, L147).
879
+ pi.registerShortcut(pauseKey.key as KeyId, {
880
+ description: "Pause the reading playing, in this or another Pi session, or resume it (as /read-pause)",
881
+ handler: async (ctx) => {
882
+ latest = ctx;
883
+ togglePause(ctx);
884
+ },
885
+ });
886
+
887
+ command("read-queue", {
888
+ description: "List the readings waiting on this machine, in order, with their sessions",
889
+ handler: async (_args, ctx) => {
890
+ const lock = openReadingLock(env);
891
+ if (!lock) {
892
+ // No XDG_RUNTIME_DIR: no session can see another's line, so this one lists its own and says so.
893
+ const items = queue.items;
894
+ ctx.ui.notify(
895
+ items.length === 0
896
+ ? NOTHING_WAITS
897
+ : ["Waiting in this session (other sessions are not visible without XDG_RUNTIME_DIR):", ...items.map((item, at) => `${at + 1}. ${item.name}`)].join("\n"),
898
+ "info",
899
+ );
900
+ return;
901
+ }
902
+ const list = lock.waitingList();
903
+ ctx.ui.notify(
904
+ list.length === 0
905
+ ? NOTHING_WAITS
906
+ : [
907
+ "Waiting on this machine:",
908
+ ...list.map((item, at) => `${at + 1}. ${item.name} · ${item.session}${item.token === lineToken ? " (this session)" : ""}`),
909
+ ].join("\n"),
910
+ "info",
911
+ );
912
+ },
913
+ });
914
+
915
+ command("read-next", {
916
+ description: "End the reading, playing or paused, in this or another Pi session, and go on with the next one waiting",
917
+ handler: async (_args, ctx) => {
918
+ const waiting = waitingCount() > 0;
919
+ // Unlike /read-stop, what waits is kept: the next one starts once the machine is free, announced (S14).
920
+ if (current) stop();
921
+ else if (!(openReadingLock(env)?.skipOthers() ?? false)) {
922
+ ctx.ui.notify(NOTHING_READ, "info");
923
+ return;
924
+ }
925
+ ctx.ui.notify(waiting ? SKIPPED : NOTHING_NEXT, "info");
926
+ },
927
+ });
928
+
929
+ command("read-output", {
930
+ description: "Choose where readings sound: local or an output from outputs.json; saved for later sessions",
931
+ getArgumentCompletions: (prefix) =>
932
+ loadOutputs(env, hostname)
933
+ .outputs.filter((output) => output.name.startsWith(prefix.trim()))
934
+ .map((output) => ({
935
+ value: output.name,
936
+ label: output.name,
937
+ description: output.ssh ? `listener ${output.ssh}` : (output.pulseServer ?? `this machine (${hostname})`),
938
+ })),
939
+ handler: async (args, ctx) => {
940
+ const list = outputs(ctx);
941
+ const name = args.trim();
942
+ let output: Output | undefined;
943
+ if (name) {
944
+ output = list.find((candidate) => candidate.name === name);
945
+ if (!output) {
946
+ ctx.ui.notify(`No output named "${name}". Outputs: ${list.map((o) => o.name).join(", ")}.`, "warning");
947
+ return;
948
+ }
949
+ chosen = output.name;
950
+ footer(ctx);
951
+ const unsaved = save({ output: output.name });
952
+ if (unsaved) {
953
+ ctx.ui.notify(`Readings will sound on ${output.label} in this session, but ${unsaved}.`, "warning");
954
+ return;
955
+ }
956
+ } else {
957
+ output = await askOutput(ctx, list);
958
+ if (!output) return;
959
+ }
960
+ ctx.ui.notify(`Readings will sound on ${output.label}.`, "info");
961
+ },
962
+ });
963
+
964
+ command("read-voice", {
965
+ description: "Choose the voice for the next readings: male (default) or female",
966
+ getArgumentCompletions: (prefix) =>
967
+ SPEAKER_NAMES.filter((name) => name.startsWith(prefix.trim())).map((name) => ({
968
+ value: name,
969
+ label: name,
970
+ description: `Supertonic 3, speaker ${SPEAKERS[name].sid}`,
971
+ })),
972
+ handler: async (args, ctx) => {
973
+ const name = args.trim();
974
+ let picked: string | undefined = name;
975
+ if (!name) {
976
+ if (!ctx.hasUI) return;
977
+ picked = await own(() => ctx.ui.select(ASK_SPEAKER, SPEAKER_NAMES));
978
+ if (!picked) return;
979
+ }
980
+ if (!SPEAKER_NAMES.includes(picked as SpeakerName)) {
981
+ ctx.ui.notify(`No voice named "${name}". Voices: ${SPEAKER_NAMES.join(", ")}.`, "warning");
982
+ return;
983
+ }
984
+ speaker = picked as SpeakerName;
985
+ ctx.ui.notify(`Readings will use the ${speaker} voice.`, "info");
986
+ },
987
+ });
988
+
989
+ command("read-speed", {
990
+ description: "Choose the voice speed for the next readings, 0.5 to 2.0 (default 1.1); saved for later sessions",
991
+ getArgumentCompletions: (prefix) =>
992
+ SPEED_CHOICES.filter((choice) => choice.startsWith(prefix.trim())).map((choice) => ({ value: choice, label: choice })),
993
+ handler: async (args, ctx) => {
994
+ let text = args.trim();
995
+ if (!text) {
996
+ if (!ctx.hasUI) return;
997
+ const picked = await own(() => ctx.ui.select(ASK_SPEED, SPEED_CHOICES));
998
+ if (!picked) return;
999
+ text = picked;
1000
+ }
1001
+ const speed = parseSpeed(text);
1002
+ if (speed === undefined) {
1003
+ ctx.ui.notify(SPEED_HINT, "warning");
1004
+ return;
1005
+ }
1006
+ sessionSpeed = speed;
1007
+ try {
1008
+ saveSpeed(env, speed);
1009
+ } catch (error) {
1010
+ ctx.ui.notify(`Readings will use speed ${formatSpeed(speed)} in this session, but ${(error as Error).message}.`, "warning");
1011
+ return;
1012
+ }
1013
+ ctx.ui.notify(`Readings will use speed ${formatSpeed(speed)}.`, "info");
1014
+ },
1015
+ });
1016
+
1017
+ command("read-music", {
1018
+ description:
1019
+ "What music does while the reader speaks: off, pause, or duck [level] (lower gentle-stream to level %, default duck 20); no argument shows it; saved for later sessions",
1020
+ getArgumentCompletions: (prefix) =>
1021
+ MUSIC_MODES.filter((mode) => mode.startsWith(prefix.trim())).map((mode) => ({ value: mode, label: mode, description: MUSIC_CHOICES[mode] })),
1022
+ handler: async (args, ctx) => {
1023
+ const parsed = parseMusicArgs(args);
1024
+ if (parsed === "show") {
1025
+ const current = musicSettings();
1026
+ const hooks = [current.before && `before "${current.before}"`, current.after && `after "${current.after}"`].filter(Boolean);
1027
+ ctx.ui.notify(`${describeMusic(current)}${hooks.length > 0 ? ` Hooks: ${hooks.join("; ")}.` : ""}`, "info");
1028
+ return;
1029
+ }
1030
+ if ("problem" in parsed) {
1031
+ ctx.ui.notify(parsed.problem, "warning");
1032
+ return;
1033
+ }
1034
+ const level = parsed.level ?? musicSettings().level;
1035
+ sessionMusic = parsed.level === undefined ? { ...sessionMusic, mode: parsed.mode } : { mode: parsed.mode, level };
1036
+ const said = describeMusic({ mode: parsed.mode, level }, true);
1037
+ try {
1038
+ saveMusic(env, parsed);
1039
+ } catch (error) {
1040
+ ctx.ui.notify(`${said.slice(0, -1)} in this session, but ${(error as Error).message}.`, "warning");
1041
+ return;
1042
+ }
1043
+ ctx.ui.notify(said, "info");
1044
+ },
1045
+ });
1046
+
1047
+ command("read-auto", {
1048
+ description:
1049
+ 'Read each new reply aloud as soon as it is written, and each prompt that waits for you: on (in full), questions (only "Needs your decision"), off; no argument toggles; saved for later sessions',
1050
+ getArgumentCompletions: (prefix) =>
1051
+ AUTO_CHOICES.filter((choice) => choice.value.startsWith(prefix.trim())).map((choice) => ({ ...choice, label: choice.value })),
1052
+ handler: async (args, ctx) => {
1053
+ const wanted = args.trim();
1054
+ const modes: Record<string, AutoMode> = { on: "full", questions: "questions", off: "off", "": auto === "off" ? "full" : "off" };
1055
+ if (!Object.hasOwn(modes, wanted)) {
1056
+ ctx.ui.notify("Use /read-auto on, questions or off.", "warning");
1057
+ return;
1058
+ }
1059
+ // Turned on: what is already on the branch is never read (S8: no reply of earlier turns).
1060
+ if (auto === "off" && modes[wanted] !== "off") seen = replyIds(ctx);
1061
+ auto = modes[wanted];
1062
+ // Off drops this session's waiting replies (S8); other sessions' are theirs. A request the user chose to read
1063
+ // after the current one is not an auto-read and stays (T33).
1064
+ if (auto === "off") queue.clear((item) => item.manual === true);
1065
+ footer(ctx);
1066
+ // The choice is remembered for new sessions (S24).
1067
+ const unsaved = save({ autoRead: auto === "full" ? "on" : auto });
1068
+ if (unsaved) ctx.ui.notify(`${AUTO_MESSAGES[auto].slice(0, -1)} in this session, but ${unsaved}.`, "warning");
1069
+ else ctx.ui.notify(AUTO_MESSAGES[auto], "info");
1070
+ },
1071
+ });
1072
+
1073
+ const replyIds = (ctx: ExtensionContext): Set<string> => new Set(listReplies(ctx.sessionManager.getBranch()).map((reply) => reply.entryId));
1074
+
1075
+ /** Queues, in order and once each, every final reply on the branch auto-read has not seen (S8 Timing, T42). */
1076
+ const queueNewReplies = (ctx: ExtensionContext): void => {
1077
+ if (auto === "off") return;
1078
+ const added = listReplies(ctx.sessionManager.getBranch()).filter((reply) => !seen.has(reply.entryId));
1079
+ const mark = added.length > 0 ? openReadingLock(env)?.waitingMark() : undefined;
1080
+ for (const reply of added) {
1081
+ seen.add(reply.entryId);
1082
+ const markdown = auto === "questions" ? questionsSection(reply.text) : reply.text;
1083
+ if (markdown === undefined) continue;
1084
+ // Queued, never awaited: it waits for any reading playing here or on the machine (S8 Queue), and a download
1085
+ // confirm or the output question must not hold the agent.
1086
+ queue.push({ ctx, name: reply.id, label: reply.id, markdown, language: detectLanguage(reply.text), mark, at: joined() });
1087
+ footer();
1088
+ }
1089
+ };
1090
+
1091
+ // Each final reply joins the line as soon as it is stored (S8 Timing, T42), even while the agent keeps working
1092
+ // (an injected user-role message can chain another turn into the same run). Pi stores the entry only after the
1093
+ // message_end handlers return, so the branch is read on the next turn of the event loop, as pi-reply-thread does.
1094
+ pi.on("message_end", (event, ctx) => {
1095
+ // What an assistant message wrote, kept for the calls it makes (S18 Context, T48): Pi runs a message's tool calls
1096
+ // after its message_end, so their tool_execution_start finds it here, from the event itself, not the branch.
1097
+ const written = writtenCalls(event.message);
1098
+ if (written) writtenBefore = new Map(written.calls.map((id) => [id, written.text]));
1099
+ if (auto === "off") return;
1100
+ const asked = generation;
1101
+ setTimeout(() => {
1102
+ if (generation === asked) queueNewReplies(ctx);
1103
+ }, 0);
1104
+ });
1105
+
1106
+ /**
1107
+ * The language a prompt reads in (S18): its own words when they tell, else the latest reply's (the conversation's),
1108
+ * else Spanish, as for any text that does not tell (S7).
1109
+ */
1110
+ const promptLanguage = (ctx: ExtensionContext, text: string): Language => {
1111
+ const told = text ? languageOfWords(text) : undefined;
1112
+ if (told) return told;
1113
+ const reply = latestReply(listReplies(ctx.sessionManager.getBranch()));
1114
+ return reply ? detectLanguage(reply.text) : "es";
1115
+ };
1116
+
1117
+ /** Queues a blocking prompt's reading (S18), when auto-read is on and it has something to say. */
1118
+ const queuePrompt = (ctx: ExtensionContext, key: string, name: string, markdown: string | readonly string[], language: Language): void => {
1119
+ if (!(typeof markdown === "string" ? speechNarration(markdown, language) : speechNarrationOfParts(markdown, language)).text) return;
1120
+ prompts.add(key);
1121
+ queue.push({ ctx, name, label: name, markdown, language, mark: openReadingLock(env)?.waitingMark(), prompt: key, at: joined() });
1122
+ footer();
1123
+ };
1124
+
1125
+ /** An answered prompt (S18): its reading still waiting is dropped, one playing is stopped; other readings stay. */
1126
+ const dropPrompt = (key: string): void => {
1127
+ if (!prompts.delete(key)) return;
1128
+ queue.clear((item) => item.prompt !== key);
1129
+ if (current?.prompt === key) stop();
1130
+ footer();
1131
+ };
1132
+
1133
+ pi.on("tool_execution_start", (event, ctx) => {
1134
+ pending.set(event.toolCallId, { toolName: event.toolName, args: event.args });
1135
+ if (auto === "off" || !QUESTION_TOOLS.has(event.toolName)) return;
1136
+ const questions = askedQuestions(event.toolName, event.args);
1137
+ if (!questions) return;
1138
+ // The text written before the call, in the same message, is read first, in its own language when it tells (T48);
1139
+ // questions mode reads only the questions. Each is cleaned apart, so no Markdown block of the text swallows them.
1140
+ const context = auto === "questions" ? "" : (writtenBefore.get(event.toolCallId) ?? "");
1141
+ const language =
1142
+ (context ? languageOfWords(context) : undefined) ??
1143
+ promptLanguage(ctx, questions.map(({ question, labels }) => [question, ...labels].join("\n")).join("\n"));
1144
+ const markdown = questionsMarkdown(questions, language);
1145
+ queuePrompt(ctx, `tool:${event.toolCallId}`, "question", context ? [context, markdown] : markdown, language);
1146
+ });
1147
+
1148
+ pi.on("tool_execution_end", (event) => {
1149
+ pending.delete(event.toolCallId);
1150
+ dropPrompt(`tool:${event.toolCallId}`);
1151
+ });
1152
+
1153
+ pi.on("ui_prompt_start", (event, ctx) => {
1154
+ spanPrompts = [];
1155
+ if (auto === "off" || ownPrompts > 0) return;
1156
+ const calls = [...pending];
1157
+ // An ask_user_* call shows its own dialog: it is already read from its call, so this span only answers it.
1158
+ const asks = calls.filter(([, call]) => QUESTION_TOOLS.has(call.toolName)).map(([id]) => `tool:${id}`);
1159
+ if (asks.length > 0) {
1160
+ spanPrompts = asks;
1161
+ return;
1162
+ }
1163
+ // A confirm while a bash call waits to run is that command's confirmation: the latest started is the one asked.
1164
+ const bash = calls.filter(([, call]) => call.toolName === "bash").at(-1);
1165
+ if (event.kind === "confirm" && bash) {
1166
+ const [id, call] = bash;
1167
+ const command = (call.args as { command?: unknown } | undefined)?.command;
1168
+ const language = promptLanguage(ctx, "");
1169
+ const key = `tool:${id}`;
1170
+ spanPrompts = [key];
1171
+ queuePrompt(ctx, key, "command confirmation", commandMarkdown(typeof command === "string" ? commandProgram(command) : undefined, language), language);
1172
+ return;
1173
+ }
1174
+ const title = dialogTitle(event.title);
1175
+ if (!title) return;
1176
+ const key = `dialog:${++dialogs}`;
1177
+ spanPrompts = [key];
1178
+ const language = promptLanguage(ctx, title);
1179
+ queuePrompt(ctx, key, "dialog", title, language);
1180
+ });
1181
+
1182
+ pi.on("ui_prompt_end", () => {
1183
+ const answered = spanPrompts;
1184
+ spanPrompts = [];
1185
+ for (const key of answered) dropPrompt(key);
1186
+ });
1187
+
1188
+ // Moving to another branch (/tree) is no new reply: what that branch already holds is never read.
1189
+ pi.on("session_tree", (_event, ctx) => {
1190
+ for (const id of replyIds(ctx)) seen.add(id);
1191
+ });
1192
+
1193
+ /** Subscribes this session to the reader's channels (S10), replacing any earlier subscription, and says it is ready. */
1194
+ const listen = (): void => {
1195
+ unsubscribeEvents?.();
1196
+ unsubscribeEvents = undefined;
1197
+ // A host without an event bus (a bare test double) just has no integration; every command works as before.
1198
+ const bus = pi.events as ExtensionAPI["events"] | undefined;
1199
+ if (!bus) return;
1200
+ const presence = { v: READER_EVENTS_VERSION };
1201
+ const offPing = bus.on(READER_EVENTS.ping, (data) => {
1202
+ // Synchronous, before any await: the view reads its flag right after its own emit returns.
1203
+ if (latest && isPing(data)) bus.emit(READER_EVENTS.ready, { ...presence });
1204
+ });
1205
+ const offRead = bus.on(READER_EVENTS.read, (data) => {
1206
+ const request = parseReadRequest(data);
1207
+ const ctx = latest;
1208
+ if (!request || !ctx) return;
1209
+ // Not awaited: the sender gets no answer; the "Something is being read." question, a download confirm or the
1210
+ // output question are the reader's.
1211
+ readRequested(ctx, request.id, request.id, request.text, detectLanguage(request.text)).catch((error: Error) =>
1212
+ ctx.ui.notify(error.message, "error"),
1213
+ );
1214
+ });
1215
+ unsubscribeEvents = () => {
1216
+ offPing();
1217
+ offRead();
1218
+ };
1219
+ bus.emit(READER_EVENTS.ready, { ...presence });
1220
+ };
1221
+
1222
+ pi.on("session_start", (_event, ctx) => {
1223
+ generation++;
1224
+ latest = ctx;
1225
+ // Players left by a Pi that died (S13 h): a hung paplay spins at about a core until it is ended.
1226
+ reapOrphans();
1227
+ musicWarned = false;
1228
+ musicProblemWarned = false;
1229
+ sessionMusic = undefined;
1230
+ // Music a reader that died left aside comes back, when nothing reads or waits on the machine (S22).
1231
+ music.settle();
1232
+ // The last choices of /read-auto and /read-output, as saved (S24); none saved: off, the output asked.
1233
+ const saved = loadSaved(env);
1234
+ auto = saved.autoRead === "on" ? "full" : saved.autoRead === "questions" ? "questions" : "off";
1235
+ queue.clear();
1236
+ // Saved on: what is already on the branch is never read (S8: no reply of earlier turns).
1237
+ seen = auto === "off" ? new Set() : replyIds(ctx);
1238
+ pending.clear();
1239
+ writtenBefore = new Map();
1240
+ prompts.clear();
1241
+ spanPrompts = [];
1242
+ chosen = undefined;
1243
+ if (saved.output) {
1244
+ // A saved output gone from outputs.json is not used: the first reading asks, as with none saved (S24).
1245
+ if (loadOutputs(env, hostname).outputs.some((output) => output.name === saved.output)) chosen = saved.output;
1246
+ else ctx.ui.notify(`Saved output "${saved.output}" is not in ${configFile(env, "outputs.json") ?? "outputs.json"}; choose one.`, "warning");
1247
+ }
1248
+ speaker = "male";
1249
+ warned = false;
1250
+ sessionSpeed = undefined;
1251
+ speedWarned = false;
1252
+ fallbackWarned = false;
1253
+ if (pauseKey.problem && ctx.hasUI && !pauseKeyWarned) {
1254
+ pauseKeyWarned = true;
1255
+ ctx.ui.notify(pauseKey.problem, "warning");
1256
+ }
1257
+ // The saved auto-read shows from the session's start (S23).
1258
+ footer(ctx);
1259
+ listen();
1260
+ });
1261
+
1262
+ pi.on("session_shutdown", () => {
1263
+ generation++;
1264
+ // The session's end drops its waiting replies (S8), before its reading ends and would start one; its footer goes.
1265
+ auto = "off";
1266
+ queue.clear();
1267
+ stop();
1268
+ footer();
1269
+ openReadingLock(env)?.publishLine(lineToken, sessionLabel(), []);
1270
+ music.settle();
1271
+ unsubscribeEvents?.();
1272
+ unsubscribeEvents = undefined;
1273
+ latest = undefined;
1274
+ });
1275
+ };
1276
+ }
1277
+
1278
+ export default createReplyReader();