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.
package/CHANGELOG.md ADDED
@@ -0,0 +1,200 @@
1
+ # Changelog
2
+
3
+ ## 0.2.0 — 2026-11-20
4
+
5
+ - The SSH audio tunnel example now ends in a private Unix socket (`unix:/run/user/<uid>/reply-reader-pulse.sock`,
6
+ mode 0600) instead of the loopback port `127.0.0.1:4714`, which every local process and host-network container
7
+ could reach, with the desktop's microphone behind it. New `examples/reply-reader-vps-audio.service` for a cloud
8
+ VPS that cannot reach the desktop: the desktop opens a reverse tunnel. Existing `tcp:` outputs keep working.
9
+ - Music steps aside while the reader speaks: by default, music played by gentle-stream goes down to volume 20
10
+ (of gentle-stream's 0-100) and its volume comes back after. `/read-music off|pause|duck [level]` chooses (saved in `settings.json` as
11
+ `"music": { "mode": "duck", "level": 20 }`; no argument shows it). Pause mode plays the music again only if it
12
+ was playing before. Once per machine: the holder of the reading turn steps it aside when the machine starts
13
+ reading and restores it when nothing reads or waits, so queued readings do not flap; a pause restores it and a
14
+ resume steps it aside again. The prior state is kept in `$XDG_RUNTIME_DIR/pi-reply-reader/music.json`, so a
15
+ session start restores music a dead reader left aside; a volume you changed meanwhile stays. On a listener
16
+ output, `reply-reader --serve` does it on the listener. Generic `before`/`after` hooks (`sh -c`, as you) run at
17
+ the same moments. Every command runs in the background with a 3 s timeout and never delays speech; without
18
+ gentle-stream or with nothing playing, nothing happens and nothing is said. A new `/read` in the session already reading keeps the music
19
+ aside; a listener reading that fell back to local playback steps it aside again on resume; a broken, empty or
20
+ out-of-range `music.json` counts as no state and is replaced, never passed to gentle-stream.
21
+
22
+ - Auto-read shows it is on: while `/read-auto` is on, the footer says `Auto-read on · desktop` or
23
+ `Auto-read questions · desktop` (just `Auto-read on` before an output is chosen), also with nothing playing,
24
+ and `Auto-read on · Reading P12.R1 on desktop · Alt+M pauses` while the session reads. With it off the footer
25
+ is unchanged.
26
+ - Auto-read and the output are remembered: the last `/read-auto` choice (on, questions, off; the toggle
27
+ included) and the last output (`/read-output`, or the pick at the first reading's question) are saved in
28
+ `settings.json` (`autoRead`, `output`, keeping the other keys) and every new Pi session starts with them.
29
+ Nothing saved starts as before (off, the output asked). A saved output gone from `outputs.json` warns
30
+ `Saved output "desktop" is not in …/outputs.json; choose one.` and the first reading asks. A saved "on"
31
+ never reads the replies already in the session.
32
+
33
+ - Synthesis on the listener: an output in `outputs.json` can be `{ "ssh": "you@host", "fallback": "<PULSE_SERVER>" }`.
34
+ The agent host sends each reading's fragments over SSH to `reply-reader --serve` on the listener, which
35
+ synthesizes and plays them, so a slow agent host no longer delays readings. Pause/resume, `/read-stop`, the
36
+ line, announcements and the player timeout behave as for any output. When the listener does not answer,
37
+ lacks `reply-reader`, its voice or `paplay`, or fails mid-reading, the reading goes on from the sentence last
38
+ heard on the agent host through `fallback`, with one warning per session; without a fallback it fails with
39
+ `Playback on "<output>" failed: <reason>`. The listener waits while it reads something of its own; a
40
+ `/read-stop` or `/read` there drops the agent host's reading still waiting, which ends quietly. Long
41
+ readings (over 5000 sentences or 1 MiB) are sent in several messages and stay on the listener. Bad `ssh`
42
+ values (empty, a leading `-`, whitespace, control characters) and unknown keys are reported and the entry
43
+ skipped. Text from the listener or `ssh` is shown without control characters. `--serve` ends quietly when
44
+ the agent host goes away, and a reading on the listener never ends a running `--serve` as an orphan.
45
+ - `reply-reader --download-voice` downloads the voice (asking `[y/N]` on a terminal) and exits; a listener
46
+ without its voice names it in the warning.
47
+
48
+ - Readings say their project when it changes: a reading whose project (the folder name of its Git root, or of
49
+ its working folder outside a repository) differs from the last reading's on the machine, or the first one,
50
+ starts with the project's name, then its announcement if it waited ("pi-reply-reader. Respuesta P tres, R
51
+ dos."). Readings of the same project say none. Every Pi session and the `reply-reader` command share the
52
+ memory under `$XDG_RUNTIME_DIR/pi-reply-reader/`; resuming does not repeat it.
53
+ - `pauseKey` refuses `ctrl` with a digit and any `super` key (one warning, Alt+M is used): terminals without
54
+ the Kitty keyboard protocol never send them, so they silently never fired.
55
+ - Esc is Pi's again: the reader never takes it. Esc interrupts the agent and closes dialogs and screens
56
+ (pi-reply-thread's Alt+R view, `ask_user_question`) even while a reading plays or is paused. Before, a reading
57
+ took every Esc and paused or resumed instead, so a view could not be closed and the agent could not be
58
+ interrupted. Readings stop with Esc no longer: Alt+M pauses and resumes them. Set `"pauseKey"` in
59
+ `settings.json` (as `"alt+o"`) to use another key. A key that is not valid or that Pi, gentle-pi,
60
+ pi-reply-thread or the terminal already uses gets one warning, and Alt+M is used instead.
61
+ - Pause and resume: `/read-pause` pauses the reading playing, in this or any other Pi session on the machine
62
+ (`Reading paused.`), and run again resumes it (`Reading resumed.`); with nothing playing it says `Nothing is
63
+ being read.`. The pause key, Alt+M, does the same with the same messages (`pauseKey` in settings.json picks
64
+ another one). Pausing drops nothing that waits. A paused reading's player is ended (so the player timeout never fires on it) but it keeps
65
+ its turn on the machine: nothing waiting starts. Resuming starts again from the sentence, item or row that was
66
+ being heard, with the same voice and speed. The footer reads `Reading P12.R1 on local · Alt+M pauses`, and
67
+ while paused `Paused P12.R1 · Alt+M resumes · /read-stop ends`. `/read-stop` ends a reading, playing or paused,
68
+ and drops what waits, as before. A prompt's reading is ended instead of paused (`Reading stopped: a prompt is
69
+ not paused.`); a `reply-reader` command reading cannot be paused from Pi.
70
+ - See and skip the line: `/read-queue` lists the readings waiting on the machine, in order, with their session
71
+ (`Waiting on this machine:` / `1. P12.R2 · api (this session)`), or says `Nothing waits to be read.`;
72
+ `/read-next` ends the reading, playing or paused, here or in another session, and the next one waiting starts
73
+ with its announcement (`Skipped to the next reading.`; `Reading stopped; nothing else waits.` when nothing
74
+ does). Each session publishes its line under `$XDG_RUNTIME_DIR/pi-reply-reader/`, and the footer's
75
+ `· N waiting ·` now counts every session's; without a usable `XDG_RUNTIME_DIR` both stay per session.
76
+ Readings play in the listed order: a session with readings waiting refreshes its line every 250 ms, and a
77
+ session whose next reading has an earlier one of another session before it yields to it while that
78
+ session's line is under 2 s old (10 s at most per reading, counting only time the machine is free, never
79
+ time another reading plays), so a frozen session holds the others about 2 s. A session waiting for you (the
80
+ output question, the voice download confirm) says so in its line and is not waited for, and a session that
81
+ ends or drops its line stops beating at once, even mid-start. Two sessions with the
82
+ same label are listed with a tag from their session ID (`api #3f9c`).
83
+ - Auto-read also reads the prompts that wait for you, through the same line: an `ask_user_question` /
84
+ `ask_user_choice` call reads the text written before it in the same message (cleaned like a reply, on its own; not in
85
+ `questions` mode), then each
86
+ question with its option labels only ("Pregunta 1 de 2: ¿Cómo suena? Opciones: uno, Bien; dos, Mal."); text
87
+ before other tool calls is not read; a command confirmation reads only the program ("Confirmación de comando:
88
+ git." / "Command confirmation: git."), and any other dialog its title. Once answered, a prompt's reading is
89
+ dropped, or stopped if it plays, as a whole. The reader's own questions are not read.
90
+ - Auto-read reads every new reply, each once and in order, as soon as it is written, even while the agent keeps
91
+ working. Before, only the last reply of a run was read: a reply followed by a background-job or subagent
92
+ notice that started another turn was skipped.
93
+ - Between queued readings (auto-reads and **Read after it**): about 1.5 s of silence, then the next reading
94
+ says which it is, in its language (`Respuesta P12.R2.` / `Reply P12.R2.`, `Archivo notas.md.` / `File
95
+ notes.md.`). A reading with nothing before it starts as before. While readings wait, the footer counts them:
96
+ `Reading P12.R2 on local · 2 waiting · Alt+M pauses`.
97
+ - A player that hangs no longer piles up: when `paplay` takes no audio for 15 s (say, a Pulse server behind an
98
+ SSH tunnel whose far side does not answer), or does not finish within the audio's length plus 15 s, the
99
+ reading fails with `Playback on "<output>" failed: timed out`. `REPLY_READER_PLAYER_TIMEOUT` sets the 15 s
100
+ (5 to 86400 seconds; any other value warns once and uses 15). Every stop sends SIGTERM, then SIGKILL 2 s
101
+ later if the player is still there, also from `reply-reader` before it exits. Players left by a Pi that
102
+ died are ended when a Pi session or a reading starts, and with `setpriv` installed a player dies with its
103
+ reader even when that is killed outright. Only this package's own players, in the same PID namespace, are
104
+ touched.
105
+ - Numbers are spoken as words in the text's language (Supertonic mispronounced digits): "51" "cincuenta y
106
+ uno", with Spanish "un"/"una" agreement by the next word, decimals, versions and IP addresses group by group,
107
+ and numbers over 9 digits or starting with 0 digit by digit.
108
+ - More readings: Spanish hundreds agree with a feminine noun (`400 líneas` "cuatrocientas líneas", `200.000
109
+ líneas` "doscientas mil líneas"); times read like a clock (`21:02` "veintiuno cero dos", `07:00` "siete en
110
+ punto"); dates with a year read in full (`2026-10-27` and `27/10/2026` "veintisiete de octubre de dos mil
111
+ veintiséis", "October twenty seven, two thousand twenty six"); globs (`*.hs.lan` "cualquier hs punto lan",
112
+ `bin/*` "todo lo de bin", `lab-*` "lab algo"; `**negrita**` and `*x*`, only letters inside `*` or `**`, are
113
+ not globs and read only the letters: "negrita"); tags, HTML or not: a pair reads its name and content (`<command>ls -la</command>` "command:
114
+ ls -la"), a lone `<archivo>` or `<iframe>` only its name ("archivo", "iframe"), a lone `</a>` or `<br/>`
115
+ "la etiqueta a" ("the a tag"); `<< text >>` reads like quotes, only the text. Diagnostics no longer report
116
+ globs and tags.
117
+ - Internal: the cleanup now builds a narration plan (blocks with a role: heading, paragraph, item, row, code
118
+ block) and renders it in the reading's language; playback speaks the rendered fragments with each one's own
119
+ pause instead of splitting the text again. `speechNarration(markdown, language?)` returns the text, the
120
+ fragments and diagnostics: technical tokens no reading rule claimed, with their line. What is spoken and
121
+ played is byte-identical to 0.1.0.
122
+ - New readings: a bare folder (`src/` "la carpeta src") and a path ending in a dot file
123
+ (`ckan-docker/.prettierrc.json` "prettierrc punto json, en ckan docker"), issue and PR numbers (`#43`
124
+ "número 43"), key combinations (`Ctrl+Shift+P` "Control más Shift más P") and minimum versions (`v1+` "v1 o
125
+ superior", `1.4+` "1 punto 4 o superior"), with "number", "plus" and "or later" in English. Diagnostics no
126
+ longer report these tokens.
127
+ - Counts such as `100+` read "100 o más" ("100 or more"); a dot file with no extension inside a path reads as
128
+ a file: `ckan-docker/.gitignore` "gitignore, en ckan docker".
129
+ - `npm run build` removes `dist/` before compiling, so a packed tarball never carries stale files.
130
+ - Auto-read no longer interrupts: a reply due while a reading plays, in this or any other session on the
131
+ machine, waits and is read once nothing plays, one session's replies in order. A manual `/read` (or a read
132
+ request from another extension) and `/read-stop` stop the reading playing and drop every auto-read
133
+ waiting on the machine; `/read-auto off` and the session's end drop that session's. Sessions coordinate
134
+ through `$XDG_RUNTIME_DIR/pi-reply-reader/` as before (`waiting.json` and a short `reading.lock` mutex);
135
+ without it a reply only waits for its own session.
136
+ - A manual `/read` or a read request (pi-reply-thread's Alt+R `s`) while something is being read anywhere on
137
+ the machine asks first: `Something is being read.` with **Stop it and read now** (as before: stop, drop the
138
+ waiting auto-reads, read) and **Read after it** (it waits like an auto-read, after the session's waiting
139
+ replies; `/read-stop` and another manual reading drop it, `/read-auto off` keeps it). Dismissing the
140
+ question changes nothing. In Pi's TUI the question is a small overlay of its own, so it shows above the Alt+R
141
+ view; elsewhere it uses the host's selector. With nothing playing, or without a UI, it reads at once as
142
+ before. `/read-stop` and the pause key never ask.
143
+ - The `reply-reader` command now drops the auto-reads waiting in Pi sessions when it starts reading, as a
144
+ manual `/read` does; it never asks.
145
+
146
+ ## 0.1.0 — 2026-11-17
147
+
148
+ First release.
149
+
150
+ - Event contract v1 for other extensions over `pi.events`, for `pi-reply-thread`'s Alt+R `s` key:
151
+ `reply-reader:ping` `{ v: 1 }` is answered at once with `reply-reader:ready` `{ v: 1 }` (also sent at every
152
+ session start), and `reply-reader:read` `{ v: 1, id, text }` reads `text` aloud like `/read`, naming `id`
153
+ in the footer. Invalid payloads are ignored.
154
+ - `/read-auto on|questions|off` (bare toggles): read each new reply, or only its "Needs your decision"
155
+ section, when the agent's turn ends; off at every session start.
156
+ - `/read <file|ID|empty>#<section>`: read only that section; add `rest` to read on to the end.
157
+ - `reply-reader <file.md>` command: reads a Markdown file (or `-` for standard input) aloud outside Pi, with
158
+ `--output`, `--speed` (this run only), `--voice` and `--help`. Exit codes 0/1/2, and 129/130/143 when a
159
+ signal stops it. It shares the one-reading-per-machine rule with `/read`. `npm i -g pi-reply-reader`
160
+ installs it as compiled JavaScript, without installing Pi.
161
+ - English replies and files are read with English connecting words ("the command", "Code block.", "1 point 1",
162
+ units and marks), detected from the text itself; Spanish text reads as before.
163
+ - `/read` reads a reply aloud on request only: the latest reply of the branch, or one by ID with
164
+ `/read P12.R1` (any case, a `.Q<n>` suffix accepted, numbered like `pi-reply-thread`'s `/replies`) or by
165
+ its entry ID. Nothing plays by itself. A new reading stops the one playing, and Esc stops it; the footer
166
+ shows `Reading P12.R1 on local · Esc stops` meanwhile.
167
+ - `/read-stop` stops the reading playing and says "Reading stopped."; with nothing playing it says
168
+ "Nothing is being read." and changes nothing.
169
+ - One reading per machine: a new `/read` in any Pi session or process of your user stops a reading playing in
170
+ another, and `/read-stop` stops it too; the session whose reading was stopped clears its footer with no
171
+ error. Coordinated through `$XDG_RUNTIME_DIR/pi-reply-reader/reading.json`; an entry whose process is gone
172
+ is ignored, only a player started by the reader is ever signalled, and without a usable `XDG_RUNTIME_DIR`
173
+ each session stops only its own readings, as before.
174
+ - `/read <file.md>` reads a Markdown file aloud (`.md` or `.markdown`, any case), resolved against the
175
+ session's working directory (absolute and `~/` paths work too), with the same cleanup, voice, output,
176
+ Esc and footer as a reply. A missing or unreadable file gets one warning naming it, and nothing plays.
177
+ - Local Spanish voice, Supertonic 3 through sherpa-onnx-node 2.0.1, on the CPU with no API key. The first
178
+ `/read` asks before downloading it once (129 MB, pinned size and sha256) into
179
+ `$XDG_DATA_HOME/pi-reply-reader/voices`; a failed download keeps nothing. Text is synthesized sentence by
180
+ sentence, so audio starts after the first sentence, and the next sentence is synthesized while one plays;
181
+ both voices are brought to the same loudness.
182
+ - `/read-voice [male|female]` picks the voice for the next readings: male (default) or female.
183
+ - Configurable voice speed, 1.1 by default. `/read-speed <n>` sets any speed from 0.5 to 2.0 (`1,15` works
184
+ too, and so does `.9` without the leading zero); `/read-speed` alone offers 0.8 to 1.5. It is saved in `$XDG_CONFIG_HOME/pi-reply-reader/settings.json`
185
+ as `{ "speed": … }`, keeping other keys, for every later reading and session; a reading already playing
186
+ keeps its speed, and the pauses do not change. An invalid file or speed warns once per session and uses
187
+ 1.1; if saving fails, the speed applies to the session with a warning.
188
+ - Replies are cleaned for listening: Markdown syntax is removed, table rows become sentences, code blocks
189
+ are announced as "Bloque de código.", URLs are read as their host, reply IDs as "P 11, R 1, Q 1",
190
+ symbols such as `→` and `≈` as words, and emoji are dropped. Technical names are read by kind: a path as
191
+ its file or folder plus where it is, a branch, a command, a file name, a commit hash, a pair of words.
192
+ Approximations and units are spelled out, numbered items read "1:" instead of stopping after the number,
193
+ and bold-only lines and headings are read as titles. Numbers with dots read "punto" (`1.1` "1 punto 1",
194
+ `## 5.2. Título` "5 punto 2: Título"), while Spanish thousands such as `2.750` and IP addresses stay.
195
+ - Named outputs: `local` (this machine's default sink) plus the names in
196
+ `$XDG_CONFIG_HOME/pi-reply-reader/outputs.json`, each mapped to a `PULSE_SERVER`. The first `/read` of a
197
+ session asks which one when there is more than `local`; `/read-output [name]` switches. Bad entries are
198
+ skipped with a warning.
199
+ - `examples/reply-reader-desktop-audio.service`: a systemd user unit that tunnels the audio over SSH to the
200
+ machine you sit at, which needs only PipeWire or PulseAudio, with no port opened on it.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Daniel Li
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.