@gpambrozio/paseo-herald 0.2.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.
package/CHANGELOG.md ADDED
@@ -0,0 +1,50 @@
1
+ # Changelog
2
+
3
+ Notable changes to `herald`. The other plugins in this repository version separately.
4
+
5
+ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the version numbers
6
+ follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Every version is published to npm
7
+ as `@gpambrozio/paseo-herald` and tagged here, so a version is something to install and a line to
8
+ read before you move.
9
+
10
+ ## [0.2.1] — 2026-09-19
11
+
12
+ ### Added
13
+
14
+ - **Installs from npm.** On Paseo 0.9 and newer,
15
+ `paseo plugin install npm:@gpambrozio/paseo-herald` fetches the plugin from the npm
16
+ registry — no clone, no repository path to remember. Installing from this repository keeps
17
+ working, and nothing about what the plugin does has changed.
18
+
19
+ ## [0.2.0] — 2026-09-17
20
+
21
+ ### Added
22
+
23
+ - **The summary prompt is yours to edit.** Settings › Plugins › Herald now opens the whole prompt the
24
+ helper is given, so you can ask for shorter sentences, another language, or more detail about the
25
+ things you care about. Herald fills in the agent, the event and what was said wherever you put
26
+ them, and one press restores the original prompt.
27
+ - **A settings button in the panel header**, beside refresh, so the voice, the model and the prompt
28
+ are one press away from the list rather than a trip through Settings.
29
+
30
+ ### Changed
31
+
32
+ - The model that writes the summaries is now picked from the list of your providers' models only. The
33
+ box for typing one by hand is gone; a model you had typed in is kept and still shown.
34
+
35
+ ## [0.1.0] — 2026-09-16
36
+
37
+ ### Added
38
+
39
+ - **A Herald panel in the sidebar** listing every agent that is waiting on you — a question asked, a
40
+ plan or a permission to approve, a turn finished, a turn failed — with a one-sentence summary of
41
+ what it needs. Tap a row to open that session, or the speaker beside its title to hear it again.
42
+ - **Spoken announcements.** When one of those events happens, a small helper agent writes the
43
+ sentence and the Paseo app on your desk speaks it — in the daemon Mac's own voice, which it renders
44
+ and the app plays, or in the browser's voice when the daemon is not a Mac. The desktop app speaks
45
+ on its own; a browser tab speaks once you have pressed *Test voice*; phones can vibrate instead,
46
+ since a plugin cannot yet speak there.
47
+ - **A card in the agent's conversation.** The same sentence appears in the agent's own transcript,
48
+ right after the turn or question it is about, with a play icon to hear it again.
49
+ - **Settings** for where to speak, which voice source and voice, how fast, which kinds of event to
50
+ announce, and which model writes the summaries — Claude Haiku 4.5 unless you pick another.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Gustavo Ambrozio
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.
package/README.md ADDED
@@ -0,0 +1,102 @@
1
+ # Herald
2
+
3
+ A [Paseo](https://paseo.sh) plugin that tells you, out loud, when one of your agents needs you.
4
+
5
+ When an agent asks a question, pauses for permission, wants a plan approved, finishes its turn, or
6
+ fails, Herald has a small helper agent write one spoken sentence about it — what is being asked and
7
+ the choices, or what was done and whether anything is left — and the Paseo app on your desk speaks
8
+ it. A **Herald** panel in the sidebar lists every agent waiting on you with that sentence. Tap a row
9
+ to open that session, or the speaker beside its title to hear the sentence again.
10
+
11
+ ![The Herald panel: three finished agents, each headed by its workspace title with a speaker icon
12
+ beside it and how long ago it finished, then what the agent was last asked, its own last line, and
13
+ in italics the sentence Herald wrote about it. Mute here, Test voice, a refresh button and a settings
14
+ button sit in the header, next to a badge counting the agents waiting.](docs/panel.png)
15
+
16
+ ## The sentence is in the conversation too
17
+
18
+ Every announced event also leaves a card in the agent's own transcript, right where the turn or the
19
+ question happened, with a play icon to hear it again. It is written as soon as the event lands, so it
20
+ reads "Writing the summary…" for the second or two the helper takes.
21
+
22
+ ![A Herald card in an agent's conversation: a small panel headed "Herald · Finished" with a play
23
+ icon, and under it, in italics, the sentence written about the turn that just ended. The agent's
24
+ composer sits below it.](docs/timeline-card.png)
25
+
26
+ ## What you need
27
+
28
+ - Paseo **0.8.0 or newer**, on the daemon and on the device running the app.
29
+ - Speech comes out of the device running the Paseo app, not the daemon machine. The voice, by
30
+ default, is the daemon Mac's: it renders each sentence with `say` and the app plays the audio, so
31
+ you hear the Mac's voices rather than a browser's. If the daemon is not a Mac, the browser's own
32
+ voice is used. The **desktop app** speaks on its own. A **browser tab** speaks once you have pressed
33
+ *Test voice* in the panel (browsers do not let a page play sound until it has been tapped). **Phones
34
+ cannot speak** from a plugin yet; Herald can vibrate instead, and Paseo's own notifications already
35
+ carry the text there.
36
+ - Summaries are written by a helper agent through whichever provider you pick, Claude Haiku 4.5 by
37
+ default. Each event is one short turn of that model; the helper appears briefly under the agent it
38
+ describes and is archived when it finishes.
39
+
40
+ ## Install
41
+
42
+ ```bash
43
+ paseo plugin install npm:@gpambrozio/paseo-herald
44
+ ```
45
+
46
+ That is the shortest route on **Paseo 0.9 or newer**, which installs plugins straight from npm; add
47
+ `@<version>` to pin one. On 0.8, install from this repository instead:
48
+
49
+ ```bash
50
+ paseo plugin add gpambrozio/paseo-plugins --path herald
51
+ ```
52
+
53
+ Pin a repository install with `--ref herald/v<version>`. To hack on it, clone the repository and
54
+ `paseo plugin install "$PWD"` from this folder after `npm install` and `npm run typecheck`.
55
+
56
+ ## Settings
57
+
58
+ **Settings › Plugins › Herald** — the gear in the panel's header, *Herald settings* from the Command
59
+ Center, or the settings screen itself.
60
+
61
+ - **Speech** — the master switch; whether the desktop app, browser tabs, and phones act on it; the
62
+ voice source (the daemon Mac's `say` voices, or this device's browser voice), which voice, the
63
+ speed; a test button. To add Mac voices, install them on the daemon Mac under System Settings ›
64
+ Accessibility › Spoken Content. These are shared by every device connected to the daemon, and each
65
+ device follows its own switch. *Mute here* in the panel silences just the device you are on until
66
+ the app restarts.
67
+ - **Summaries** — the model that writes them, the prompt they are written from, and which kinds of
68
+ event are announced: questions, plan approvals, tool permissions, finished turns, errors. A kind
69
+ that is switched off still appears in the panel, without a summary and without being spoken.
70
+
71
+ ### The prompt
72
+
73
+ *Summary prompt* opens the whole prompt the helper is given, to edit however you like — shorter
74
+ sentences, another language, more about what matters to you for a finished turn than for a question.
75
+ Herald fills in the parts that change per event wherever you put them:
76
+
77
+ | Placeholder | Filled with |
78
+ | --- | --- |
79
+ | `{{agent}}` | What the work is called: the agent's title, or its workspace's. |
80
+ | `{{workspace}}` | The workspace's title, or the folder name when it has none. |
81
+ | `{{folder}}` | The last part of the agent's working directory. |
82
+ | `{{event}}` | A sentence saying why the agent is waiting. |
83
+ | `{{headline}}` | The one line Herald builds without a model: the question, the command, "Finished". |
84
+ | `{{detail}}` | The choices, the command, or the start of the final message. Often empty. |
85
+ | `{{request}}` | What you last asked this agent for. Empty when the agent paused without one. |
86
+ | `{{output}}` | What the agent said since that message. Empty for a pause. |
87
+
88
+ A **line** whose placeholder has nothing to fill it for that event is left out whole, so keep a label
89
+ and its placeholder on the same line — `Detail: {{detail}}` simply disappears when there is no detail.
90
+ Anything else in double braces is sent as you typed it. *Restore the default* brings the original
91
+ prompt back, and an empty prompt is the default one.
92
+
93
+ The default prompt ends by asking for a small JSON object, which is what Herald reads the sentence
94
+ out of. You can drop that — Herald then speaks whatever the model replies, trimmed to the first 45
95
+ words — but the result is less predictable, so the editor says so.
96
+
97
+ ## What the helper sees
98
+
99
+ With the default prompt, for a finished turn the helper is given what the agent said after your last
100
+ message, and your last message. For a question or permission it is given the question and the choices, or the command. That
101
+ text goes to the model you chose, through your own provider credentials, the same way the agent's own
102
+ work does.
@@ -0,0 +1,285 @@
1
+ /**
2
+ * The part that runs while the app is open, whether or not the Herald panel
3
+ * is on screen. `index.client.tsx` starts one per connected client and stops
4
+ * it on cleanup; a surface would not do, because a surface is unmounted the
5
+ * moment the user navigates anywhere.
6
+ *
7
+ * It pulls, because a plugin has no server-to-client push: a short poll of
8
+ * the entries RPC, quickened when Paseo's own agent stream reports an agent
9
+ * needing attention or a summary is still being written. Each entry is spoken
10
+ * once per device, remembered by its event id.
11
+ *
12
+ * Async **function expressions**, never async arrows, anywhere in this file —
13
+ * Hermes evaluates an async arrow in an eval'd bundle to `undefined`.
14
+ */
15
+ import { settingsRpc } from "@getpaseo/plugin";
16
+ import type { PluginClientContext } from "@getpaseo/plugin/client";
17
+
18
+ import { listAttention, renderSpeech, type AttentionEntry } from "../shared/herald";
19
+ import { DEFAULT_SPEECH, speechSettings, type SpeechSettings } from "../shared/settings";
20
+ import {
21
+ canPlayAudio,
22
+ canSpeak,
23
+ playAudio,
24
+ primeSpeech,
25
+ speak,
26
+ speechPlatform,
27
+ stopAudio,
28
+ stopSpeaking,
29
+ vibrate,
30
+ } from "./web";
31
+
32
+ const IDLE_POLL_MS = 10_000;
33
+ const BUSY_POLL_MS = 2_000;
34
+
35
+ /**
36
+ * The settings as last read by anything — the announcer's own RPC read or a
37
+ * mounted screen's `useSettings` — and the fallback when the read fails.
38
+ */
39
+ let mirroredSettings: SpeechSettings | null = null;
40
+
41
+ export function mirrorSettings(values: SpeechSettings): void {
42
+ mirroredSettings = values;
43
+ }
44
+
45
+ /**
46
+ * Muted on this device only. Module scope so it survives navigating away and
47
+ * back, and nothing more: the settings document is shared by every client of
48
+ * the daemon, which is the wrong place for "not right now, not here".
49
+ */
50
+ let mutedHere = false;
51
+
52
+ export function isMutedHere(): boolean {
53
+ return mutedHere;
54
+ }
55
+
56
+ export function setMutedHere(muted: boolean): void {
57
+ mutedHere = muted;
58
+ }
59
+
60
+ /** What is said for an entry, or null when there is nothing to say yet or ever. */
61
+ export function speechText(entry: AttentionEntry): string | null {
62
+ switch (entry.summary.status) {
63
+ case "ready":
64
+ return entry.summary.text;
65
+ case "failed":
66
+ return entry.summary.fallback;
67
+ case "pending":
68
+ case "off":
69
+ return null;
70
+ }
71
+ }
72
+
73
+ export interface Announcer {
74
+ stop(): void;
75
+ /** Poll now rather than at the next tick. */
76
+ poke(): void;
77
+ readSettings(): Promise<SpeechSettings>;
78
+ /**
79
+ * Say one entry again, announced before or not. Resolves to null once it has
80
+ * played, or to the reason this device stayed quiet, for the caller to show.
81
+ */
82
+ speakEntry(entry: AttentionEntry): Promise<string | null>;
83
+ /**
84
+ * `force` skips the switches, for *Test voice* alone: it is how the voice is
85
+ * checked while announcements are off, and on the web it is the press that
86
+ * hands the browser its audio permission. Gating it would disable it exactly
87
+ * when someone is trying to get sound working.
88
+ */
89
+ speakText(text: string, options?: { force?: boolean }): Promise<string | null>;
90
+ }
91
+
92
+ let active: Announcer | null = null;
93
+
94
+ /** The running announcer, for the panel's buttons. Null before the client entry has run. */
95
+ export function getAnnouncer(): Announcer | null {
96
+ return active;
97
+ }
98
+
99
+ export function startAnnouncer(client: PluginClientContext): Announcer {
100
+ let stopped = false;
101
+ let polling = false;
102
+ let seeded = false;
103
+ let warnedSettings = false;
104
+ let warnedSay = false;
105
+ let timer: ReturnType<typeof setTimeout> | null = null;
106
+ const spoken = new Set<string>();
107
+ /** Deliveries queue behind one another, so a button press never talks over the poll. */
108
+ let chain: Promise<void> = Promise.resolve();
109
+
110
+ async function readSettings(): Promise<SpeechSettings> {
111
+ try {
112
+ const result = await client.rpc(settingsRpc(speechSettings.id).read, {});
113
+ if (result.status === "ready") {
114
+ const parsed = speechSettings.schema.safeParse(result.values);
115
+ if (parsed.success) {
116
+ mirroredSettings = parsed.data;
117
+ return parsed.data;
118
+ }
119
+ }
120
+ } catch (error) {
121
+ if (!warnedSettings) {
122
+ warnedSettings = true;
123
+ console.warn("[herald] could not read speech settings, using the last known values", error);
124
+ }
125
+ }
126
+ return mirroredSettings ?? DEFAULT_SPEECH;
127
+ }
128
+
129
+ /**
130
+ * Why this device stays quiet, or null when it may speak. One function for
131
+ * both callers: the poll drops a blocked announcement silently, a pressed
132
+ * control shows the reason. A switch the user set has to mean what it says,
133
+ * and a control that simply did nothing would have no way to explain itself.
134
+ */
135
+ function blockedMessage(settings: SpeechSettings): string | null {
136
+ if (mutedHere) return "Herald is muted on this device. Unmute it from the Herald panel.";
137
+ if (!settings.enabled) return "Announcements are off in Settings › Plugins › Herald.";
138
+ switch (speechPlatform()) {
139
+ case "desktop":
140
+ return settings.speakOnDesktop ? null : "Speaking on the desktop app is off in Herald settings.";
141
+ case "browser":
142
+ return settings.speakInBrowser ? null : "Speaking in a browser tab is off in Herald settings.";
143
+ case "mobile":
144
+ return settings.vibrateOnMobile ? null : "Vibrating on phones is off in Herald settings.";
145
+ }
146
+ }
147
+
148
+ /**
149
+ * The daemon Mac's voice when asked for and reachable, the browser's voice
150
+ * otherwise. A failed render or a refused playback falls through to the
151
+ * browser voice rather than to silence, and is logged once.
152
+ */
153
+ async function deliverNow(text: string, settings: SpeechSettings): Promise<void> {
154
+ // Checked here rather than only at the call site: this runs once per
155
+ // queued delivery, and a reload can stop the announcer while one waits.
156
+ if (stopped) return;
157
+ if (speechPlatform() === "mobile") {
158
+ vibrate();
159
+ return;
160
+ }
161
+ const rate = Number(settings.rate);
162
+ if (settings.engine === "say" && canPlayAudio()) {
163
+ try {
164
+ const audio = await client.rpc(renderSpeech, { text, voice: settings.sayVoice, rate });
165
+ if (stopped) return;
166
+ await playAudio(`data:${audio.mimeType};base64,${audio.base64}`);
167
+ return;
168
+ } catch (error) {
169
+ if (!warnedSay) {
170
+ warnedSay = true;
171
+ console.warn("[herald] the daemon's say voice is unavailable, using the browser voice", error);
172
+ }
173
+ }
174
+ }
175
+ if (!canSpeak()) return;
176
+ await speak(text, { voice: settings.voice, rate });
177
+ }
178
+
179
+ function deliver(text: string, settings: SpeechSettings): Promise<void> {
180
+ const next = chain.then(
181
+ function run() {
182
+ return deliverNow(text, settings);
183
+ },
184
+ function runAfterFailure() {
185
+ return deliverNow(text, settings);
186
+ },
187
+ );
188
+ chain = next.catch(() => {});
189
+ return next;
190
+ }
191
+
192
+ async function announce(entries: AttentionEntry[], settings: SpeechSettings): Promise<void> {
193
+ // Oldest first, so a batch that arrived together reads in order.
194
+ const ordered = [...entries].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
195
+ for (const entry of ordered) {
196
+ spoken.add(entry.eventId);
197
+ const text = speechText(entry);
198
+ if (text !== null && blockedMessage(settings) === null) await deliver(text, settings);
199
+ }
200
+ }
201
+
202
+ function schedule(delay: number): void {
203
+ if (stopped) return;
204
+ if (timer !== null) clearTimeout(timer);
205
+ timer = setTimeout(() => void poll(), delay);
206
+ }
207
+
208
+ async function poll(): Promise<void> {
209
+ if (stopped || polling) return;
210
+ polling = true;
211
+ let busy = false;
212
+ try {
213
+ const { entries } = await client.rpc(listAttention, {});
214
+ if (stopped) return;
215
+ const present = new Set(entries.map((entry) => entry.eventId));
216
+ if (!seeded) {
217
+ // Whatever was already waiting when this client came up has been
218
+ // waiting a while; the panel shows it, but it is not news to announce.
219
+ entries.forEach((entry) => spoken.add(entry.eventId));
220
+ seeded = true;
221
+ }
222
+ busy = entries.some((entry) => entry.summary.status === "pending");
223
+ const fresh = entries.filter(
224
+ (entry) => !spoken.has(entry.eventId) && entry.summary.status !== "pending",
225
+ );
226
+ if (fresh.length > 0) await announce(fresh, await readSettings());
227
+ // Forget ids that are gone; an event id never comes back.
228
+ for (const id of [...spoken]) if (!present.has(id)) spoken.delete(id);
229
+ } catch (error) {
230
+ console.warn("[herald] could not list what needs attention", error);
231
+ } finally {
232
+ polling = false;
233
+ schedule(busy ? BUSY_POLL_MS : IDLE_POLL_MS);
234
+ }
235
+ }
236
+
237
+ // Paseo's own stream says an agent needs attention before the summary is
238
+ // ready; use it to start polling quickly rather than waiting for the tick.
239
+ const unsubscribe = client.paseo.agents.subscribe((update) => {
240
+ if (update.kind === "upsert" && update.agent.requiresAttention) schedule(BUSY_POLL_MS / 2);
241
+ });
242
+
243
+ const announcer: Announcer = {
244
+ stop() {
245
+ stopped = true;
246
+ if (timer !== null) clearTimeout(timer);
247
+ unsubscribe();
248
+ // A plugin reload starts the replacement announcer at once, so whatever
249
+ // this one was saying has to stop or the two talk over each other.
250
+ stopSpeaking();
251
+ stopAudio();
252
+ if (active === announcer) active = null;
253
+ },
254
+ poke() {
255
+ schedule(0);
256
+ },
257
+ readSettings,
258
+ /**
259
+ * Both of these run their first statement in the press handler's own task,
260
+ * which is the only place a browser grants audio. Everything after the
261
+ * first `await` is too late, so `primeSpeech()` goes first — before the
262
+ * settings read, before the render.
263
+ */
264
+ async speakEntry(entry) {
265
+ primeSpeech();
266
+ const settings = await readSettings();
267
+ const blocked = blockedMessage(settings);
268
+ if (blocked !== null) return blocked;
269
+ const text = speechText(entry) ?? `${entry.agentTitle ?? "An agent"}: ${entry.headline}`;
270
+ await deliver(text, settings);
271
+ return null;
272
+ },
273
+ async speakText(text, options) {
274
+ primeSpeech();
275
+ const settings = await readSettings();
276
+ const blocked = options?.force === true ? null : blockedMessage(settings);
277
+ if (blocked !== null) return blocked;
278
+ await deliver(text, settings);
279
+ return null;
280
+ },
281
+ };
282
+ active = announcer;
283
+ schedule(500);
284
+ return announcer;
285
+ }