@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 +50 -0
- package/LICENSE +21 -0
- package/README.md +102 -0
- package/client/announcer.ts +285 -0
- package/client/herald.tsx +617 -0
- package/client/option-picker.tsx +171 -0
- package/client/prompt-editor.tsx +185 -0
- package/client/settings-screen.tsx +407 -0
- package/client/timeline-card.tsx +146 -0
- package/client/web.ts +255 -0
- package/index.client.tsx +65 -0
- package/index.server.ts +55 -0
- package/package.json +43 -0
- package/paseo-plugin.json +7 -0
- package/server/card.ts +75 -0
- package/server/config.ts +62 -0
- package/server/hooks.ts +372 -0
- package/server/liveness.ts +159 -0
- package/server/say.ts +132 -0
- package/server/sdk-types.ts +24 -0
- package/server/store.ts +194 -0
- package/server/summarize.ts +223 -0
- package/server/timeline.ts +194 -0
- package/server/workspaces.ts +33 -0
- package/shared/herald.ts +234 -0
- package/shared/settings.ts +60 -0
- package/shared/timeline.ts +32 -0
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
|
+

|
|
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
|
+

|
|
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
|
+
}
|