@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/client/web.ts ADDED
@@ -0,0 +1,255 @@
1
+ /**
2
+ * Every browser global this plugin touches, in the one module the root
3
+ * CLAUDE.md allows them in. Each export declares the narrow shape of the
4
+ * globals it uses, gates on `Platform.OS`, and gives native the alternative or
5
+ * a no-op — so the rest of `client/` never reaches for `window` and typechecks
6
+ * without the DOM library.
7
+ *
8
+ * Speech is the Web Speech API and nothing else: the host provides plugin code
9
+ * no audio module, and React Native core has none. That is why a phone gets a
10
+ * vibration at most, and why the two web cases differ — the Electron desktop
11
+ * speaks unprompted, a browser tab only once the page has been tapped, because
12
+ * Chromium and WebKit drop `speak()` without user activation and fire no event.
13
+ */
14
+ import { Platform, Vibration } from "react-native";
15
+
16
+ interface WebVoice {
17
+ readonly name: string;
18
+ readonly lang: string;
19
+ readonly default: boolean;
20
+ }
21
+
22
+ interface WebUtterance {
23
+ text: string;
24
+ rate: number;
25
+ volume: number;
26
+ voice: WebVoice | null;
27
+ onend: (() => void) | null;
28
+ onerror: ((event: { error?: string }) => void) | null;
29
+ }
30
+
31
+ interface WebSynth {
32
+ speak(utterance: WebUtterance): void;
33
+ cancel(): void;
34
+ getVoices(): WebVoice[];
35
+ readonly speaking: boolean;
36
+ addEventListener?(type: "voiceschanged", listener: () => void): void;
37
+ removeEventListener?(type: "voiceschanged", listener: () => void): void;
38
+ }
39
+
40
+ interface WebAudioElement {
41
+ src: string;
42
+ play(): Promise<void>;
43
+ pause(): void;
44
+ onended: (() => void) | null;
45
+ onerror: ((event: unknown) => void) | null;
46
+ }
47
+
48
+ interface WebGlobals {
49
+ speechSynthesis?: WebSynth;
50
+ SpeechSynthesisUtterance?: new (text: string) => WebUtterance;
51
+ Audio?: new (src?: string) => WebAudioElement;
52
+ /** The desktop preload's bridge; present in the Electron renderer and nowhere else. */
53
+ paseoDesktop?: unknown;
54
+ }
55
+
56
+ function web(): WebGlobals | null {
57
+ return Platform.OS === "web" ? (globalThis as WebGlobals) : null;
58
+ }
59
+
60
+ export type SpeechPlatform = "desktop" | "browser" | "mobile";
61
+
62
+ export function speechPlatform(): SpeechPlatform {
63
+ const globals = web();
64
+ if (globals === null) return "mobile";
65
+ return globals.paseoDesktop === undefined ? "browser" : "desktop";
66
+ }
67
+
68
+ export function canSpeak(): boolean {
69
+ const globals = web();
70
+ return (
71
+ globals !== null &&
72
+ typeof globals.speechSynthesis?.speak === "function" &&
73
+ typeof globals.SpeechSynthesisUtterance === "function"
74
+ );
75
+ }
76
+
77
+ export interface Voice {
78
+ name: string;
79
+ lang: string;
80
+ }
81
+
82
+ /** Empty until the browser has loaded its voice list; see `onVoicesChanged`. */
83
+ export function listVoices(): Voice[] {
84
+ const synth = web()?.speechSynthesis;
85
+ if (synth === undefined) return [];
86
+ return synth
87
+ .getVoices()
88
+ .map((voice) => ({ name: voice.name, lang: voice.lang }))
89
+ .sort((a, b) => a.lang.localeCompare(b.lang) || a.name.localeCompare(b.name));
90
+ }
91
+
92
+ export function onVoicesChanged(listener: () => void): () => void {
93
+ const synth = web()?.speechSynthesis;
94
+ if (synth?.addEventListener === undefined) return () => {};
95
+ synth.addEventListener("voiceschanged", listener);
96
+ return () => synth.removeEventListener?.("voiceschanged", listener);
97
+ }
98
+
99
+ export interface SpeakOptions {
100
+ /** A voice name from `listVoices`, or empty for the platform default. */
101
+ voice: string;
102
+ rate: number;
103
+ }
104
+
105
+ /**
106
+ * Chromium collects an utterance that nothing references before it ends, and
107
+ * then never fires `onend`; holding it here until it finishes is the known
108
+ * workaround.
109
+ */
110
+ const inFlight = new Set<WebUtterance>();
111
+
112
+ /**
113
+ * Resolves when the utterance ends. It also resolves after a generous guard
114
+ * time, because a browser that dropped the call for lack of user activation
115
+ * fires nothing at all, and a queue waiting on that event would never move.
116
+ * Rejects only when there is no speech synthesis here.
117
+ */
118
+ export function speak(text: string, options: SpeakOptions): Promise<void> {
119
+ const globals = web();
120
+ const synth = globals?.speechSynthesis;
121
+ const Utterance = globals?.SpeechSynthesisUtterance;
122
+ if (synth === undefined || Utterance === undefined || !canSpeak()) {
123
+ return Promise.reject(new Error("Speech synthesis is not available here."));
124
+ }
125
+ return new Promise<void>((resolve) => {
126
+ const utterance = new Utterance(text);
127
+ utterance.rate = options.rate;
128
+ if (options.voice !== "") {
129
+ const match = synth.getVoices().find((voice) => voice.name === options.voice);
130
+ if (match !== undefined) utterance.voice = match;
131
+ }
132
+ let settled = false;
133
+ const finish = () => {
134
+ if (settled) return;
135
+ settled = true;
136
+ inFlight.delete(utterance);
137
+ resolve();
138
+ };
139
+ utterance.onend = finish;
140
+ utterance.onerror = finish;
141
+ inFlight.add(utterance);
142
+ setTimeout(finish, Math.max(8_000, text.length * 150));
143
+ synth.speak(utterance);
144
+ });
145
+ }
146
+
147
+ export function stopSpeaking(): void {
148
+ web()?.speechSynthesis?.cancel();
149
+ }
150
+
151
+ export function canPlayAudio(): boolean {
152
+ return typeof web()?.Audio === "function";
153
+ }
154
+
155
+ /**
156
+ * One element for every playback, made on first use. WebKit unlocks the
157
+ * *element* a gesture played, not the page, so reusing this one is what makes
158
+ * `primeSpeech()` carry to the announcements that follow.
159
+ */
160
+ let player: WebAudioElement | null = null;
161
+
162
+ /** Settles the playback in progress, so `stopAudio` need not strand its caller. */
163
+ let settlePlayer: (() => void) | null = null;
164
+
165
+ function audioPlayer(): WebAudioElement | null {
166
+ const Audio = web()?.Audio;
167
+ if (Audio === undefined) return null;
168
+ if (player === null) player = new Audio();
169
+ return player;
170
+ }
171
+
172
+ /** A 1 ms 8 kHz silence: enough to unlock playback, inaudible. */
173
+ const SILENT_WAV =
174
+ "data:audio/wav;base64,UklGRiwAAABXQVZFZm10IBAAAAABAAEAQB8AAEAfAAABAAgAZGF0YQgAAACAgICAgICAgA==";
175
+
176
+ /**
177
+ * Takes the user activation a browser grants for audio, in the caller's own
178
+ * task.
179
+ *
180
+ * Chromium and WebKit allow audio only when a gesture asked for it, and the
181
+ * permission belongs to the *task the gesture runs in* — which the real
182
+ * delivery is never in, because it first awaits the settings and, on the `say`
183
+ * engine, a render RPC. So every press handler calls this synchronously before
184
+ * any await: it starts a silent clip on the element the announcer will reuse
185
+ * and speaks an inaudible utterance, unlocking both engines. That is what
186
+ * makes the documented "tap Test voice once" flow work.
187
+ */
188
+ export function primeSpeech(): void {
189
+ const globals = web();
190
+ if (globals === null) return;
191
+ const element = audioPlayer();
192
+ if (element !== null && element.src === "") {
193
+ element.src = SILENT_WAV;
194
+ void element.play().catch(() => {});
195
+ }
196
+ const synth = globals.speechSynthesis;
197
+ const Utterance = globals.SpeechSynthesisUtterance;
198
+ if (synth !== undefined && Utterance !== undefined && !synth.speaking) {
199
+ const silent = new Utterance(" ");
200
+ silent.volume = 0;
201
+ synth.speak(silent);
202
+ }
203
+ }
204
+
205
+ /**
206
+ * Plays audio the daemon rendered, handed over as a data URL. Resolves when it
207
+ * ends; rejects when the browser refuses — a tab without user activation, a
208
+ * format it cannot decode — so the caller can fall back to the browser voice.
209
+ */
210
+ export function playAudio(dataUrl: string): Promise<void> {
211
+ const element = audioPlayer();
212
+ if (element === null) return Promise.reject(new Error("Audio playback is not available here."));
213
+ return new Promise<void>((resolve, reject) => {
214
+ let settled = false;
215
+ const finish = (error: unknown) => {
216
+ if (settled) return;
217
+ settled = true;
218
+ if (settlePlayer === settle) settlePlayer = null;
219
+ element.onended = null;
220
+ element.onerror = null;
221
+ if (error === null) resolve();
222
+ else reject(error instanceof Error ? error : new Error("The browser could not play the audio."));
223
+ };
224
+ const settle = () => finish(null);
225
+ settlePlayer = settle;
226
+ element.onended = settle;
227
+ element.onerror = (event) => finish(event);
228
+ element.src = dataUrl;
229
+ element.play().catch((error: unknown) => finish(error));
230
+ });
231
+ }
232
+
233
+ /** Ends the playback in progress, settling its caller rather than stranding it. */
234
+ export function stopAudio(): void {
235
+ if (player === null) return;
236
+ player.pause();
237
+ const settle = settlePlayer;
238
+ settlePlayer = null;
239
+ settle?.();
240
+ }
241
+
242
+ /**
243
+ * Whether anything here can make a sound from plugin code: either engine will
244
+ * do. False on iOS and Android, where the host offers plugin code no audio
245
+ * module at all — which is why every play control is *hidden* there rather
246
+ * than left to fail when pressed.
247
+ */
248
+ export function canPlaySpeech(): boolean {
249
+ return canPlayAudio() || canSpeak();
250
+ }
251
+
252
+ /** The most a phone can do from plugin code. A no-op on web. */
253
+ export function vibrate(): void {
254
+ if (Platform.OS !== "web") Vibration.vibrate();
255
+ }
@@ -0,0 +1,65 @@
1
+ import type { PluginClientContext } from "@getpaseo/plugin/client";
2
+
3
+ import { startAnnouncer } from "./client/announcer";
4
+ import { HeraldSurface, bindSettingsOpener } from "./client/herald";
5
+ import { HeraldSettingsScreen } from "./client/settings-screen";
6
+ import { HeraldTimelineCard } from "./client/timeline-card";
7
+ import { HERALD_CARD_KIND, HERALD_CARD_VERSION, HeraldCardSchema } from "./shared/timeline";
8
+
9
+ export default function contribute(client: PluginClientContext) {
10
+ // Runs for as long as this client is connected, panel open or not; it is
11
+ // what speaks. Everything below is how the user sees and tunes it.
12
+ const announcer = startAnnouncer(client);
13
+
14
+ client.addSurface("herald", HeraldSurface);
15
+ // The surface's own settings button. A surface is given no way to open a
16
+ // settings screen, so the capability is lent to it from here.
17
+ bindSettingsOpener((id) => {
18
+ client.openSettings(id);
19
+ });
20
+ // Draws the rows `server/card.ts` appends. The kind/version pair has to
21
+ // match what the daemon wrote, which is why both sides import it.
22
+ client.addTimelineRenderer({
23
+ kind: HERALD_CARD_KIND,
24
+ version: HERALD_CARD_VERSION,
25
+ schema: HeraldCardSchema,
26
+ Component: HeraldTimelineCard,
27
+ });
28
+ client.addSidebarItem({
29
+ id: "herald",
30
+ title: "Herald",
31
+ icon: "Megaphone",
32
+ surface: "herald",
33
+ });
34
+ client.addSettingsScreen({
35
+ id: "herald",
36
+ title: "Herald",
37
+ icon: "Megaphone",
38
+ Component: HeraldSettingsScreen,
39
+ });
40
+ client.addCommandCenterItem({
41
+ id: "open-herald",
42
+ title: "Open Herald",
43
+ icon: "Megaphone",
44
+ keywords: ["herald", "attention", "waiting", "needs you", "speak", "voice"],
45
+ context: "global",
46
+ onSelect({ openSurface }) {
47
+ openSurface("herald");
48
+ },
49
+ });
50
+ client.addCommandCenterItem({
51
+ id: "herald-settings",
52
+ title: "Herald settings",
53
+ icon: "Settings",
54
+ keywords: ["herald", "voice", "speech", "announce", "summary model"],
55
+ context: "global",
56
+ onSelect({ openSettings }) {
57
+ openSettings("herald");
58
+ },
59
+ });
60
+
61
+ return () => {
62
+ bindSettingsOpener(null);
63
+ announcer.stop();
64
+ };
65
+ }
@@ -0,0 +1,55 @@
1
+ import { join } from "node:path";
2
+
3
+ import type { PluginServerContext } from "@getpaseo/plugin/server";
4
+
5
+ import { pluginDir, readHeraldConfig, writeHeraldConfig } from "./server/config";
6
+ import { registerHooks } from "./server/hooks";
7
+ import { Liveness } from "./server/liveness";
8
+ import { listSayVoices, renderWithSay, sayAvailable } from "./server/say";
9
+ import { AttentionStore } from "./server/store";
10
+ import { summarize } from "./server/summarize";
11
+ import { listAttention, listSpeechVoices, readConfig, renderSpeech, writeConfig } from "./shared/herald";
12
+ import { speechSettings } from "./shared/settings";
13
+
14
+ export default function contribute(server: PluginServerContext) {
15
+ const store = new AttentionStore(join(pluginDir(), "attention.json"));
16
+ // Not awaited, because a contribution registers its handlers synchronously —
17
+ // it returns a cleanup, not a promise. Events therefore arrive *during* this
18
+ // read, so the store merges rather than overwrites: see `touched` there.
19
+ void store.load().catch((error: unknown) => {
20
+ console.error("[herald] could not load saved entries:", error);
21
+ });
22
+
23
+ // Hooks hear an agent move on; they do not hear a session close. The list
24
+ // asks the daemon about each entry's agent before handing it out.
25
+ const liveness = new Liveness();
26
+ server.handle(listAttention, async (_input, { paseo }) => ({ entries: await liveness.visible(store, paseo) }));
27
+ server.handle(readConfig, () => readHeraldConfig());
28
+ server.handle(writeConfig, (config) => writeHeraldConfig(config));
29
+
30
+ // The daemon Mac renders speech with `say`; the app plays the bytes. Not a
31
+ // Mac, or no `say`: the client hears that and uses the browser's voice.
32
+ server.handle(listSpeechVoices, async () => {
33
+ const available = await sayAvailable();
34
+ return { available, voices: available ? await listSayVoices() : [] };
35
+ });
36
+ server.handle(renderSpeech, async ({ text, voice, rate }) => {
37
+ if (!(await sayAvailable())) throw new Error("The daemon is not a Mac, so `say` is not available.");
38
+ return renderWithSay(text, { voice, rate });
39
+ });
40
+
41
+ // Storage lives on the host; registering the definition is what makes the
42
+ // client's `useSettings` reads and writes valid for this installation.
43
+ server.registerSettings(speechSettings);
44
+
45
+ const unregisterHooks = registerHooks(server, {
46
+ store,
47
+ readConfig: readHeraldConfig,
48
+ summarize,
49
+ });
50
+
51
+ return async () => {
52
+ unregisterHooks();
53
+ await store.flush();
54
+ };
55
+ }
package/package.json ADDED
@@ -0,0 +1,43 @@
1
+ {
2
+ "name": "@gpambrozio/paseo-herald",
3
+ "version": "0.2.1",
4
+ "description": "Paseo plugin: speaks one sentence when an agent needs you, and lists everything waiting in a sidebar panel",
5
+ "license": "MIT",
6
+ "homepage": "https://github.com/gpambrozio/paseo-plugins/tree/main/herald",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/gpambrozio/paseo-plugins.git",
10
+ "directory": "herald"
11
+ },
12
+ "type": "module",
13
+ "files": [
14
+ "paseo-plugin.json",
15
+ "index.client.tsx",
16
+ "index.server.ts",
17
+ "client/",
18
+ "server/",
19
+ "shared/",
20
+ "CHANGELOG.md",
21
+ "!**/*.test.ts"
22
+ ],
23
+ "publishConfig": {
24
+ "access": "public",
25
+ "registry": "https://registry.npmjs.org"
26
+ },
27
+ "scripts": {
28
+ "typecheck": "tsc --noEmit",
29
+ "test": "vitest run --passWithNoTests"
30
+ },
31
+ "devDependencies": {
32
+ "@getpaseo/client": "0.8.0",
33
+ "@getpaseo/plugin": "0.8.0",
34
+ "@getpaseo/protocol": "0.8.0",
35
+ "@types/node": "^26.5.0",
36
+ "@types/react": "~19.2.0",
37
+ "react": "19.1.0",
38
+ "react-native": "0.81.5",
39
+ "typescript": "^7.0.2",
40
+ "vitest": "^5.0.0",
41
+ "zod": "^4.5.4"
42
+ }
43
+ }
@@ -0,0 +1,7 @@
1
+ {
2
+ "id": "herald",
3
+ "description": "Speaks one sentence when an agent needs you, and lists what is waiting",
4
+ "requirements": {
5
+ "paseo": ">=0.8.0"
6
+ }
7
+ }
package/server/card.ts ADDED
@@ -0,0 +1,75 @@
1
+ /**
2
+ * The summary card in the agent's own transcript. Appended as soon as an entry
3
+ * is recorded, so it lands right after the turn or the question it is about,
4
+ * and appended again under the same id when the summary is ready or has
5
+ * failed — the daemon replaces the row live and on refetch. Rows live in the
6
+ * daemon's memory: they survive scroll and reconnect, not a daemon restart.
7
+ */
8
+ import type { PaseoApi } from "@getpaseo/client";
9
+
10
+ import type { AttentionEntry } from "../shared/herald";
11
+ import { HERALD_CARD_KIND, HERALD_CARD_VERSION, type HeraldCard } from "../shared/timeline";
12
+ import { displayName } from "./timeline";
13
+
14
+ export function cardFor(entry: AttentionEntry, superseded = false): HeraldCard {
15
+ return {
16
+ eventId: entry.eventId,
17
+ reason: entry.reason,
18
+ name: displayName(entry),
19
+ headline: entry.headline,
20
+ detail: entry.detail,
21
+ summary: entry.summary,
22
+ superseded,
23
+ };
24
+ }
25
+
26
+ /** Reported once per distinct cause; a host that predates the feature would otherwise say so on every event. */
27
+ const reported = new Set<string>();
28
+
29
+ /**
30
+ * One chain per row. The pending append and the terminal one carry the same
31
+ * row id and are both started fire-and-forget, so without this a pending write
32
+ * held up by a slow round trip could land *after* the summary that replaced it
33
+ * and leave the card reading "Writing the summary…" for ever.
34
+ */
35
+ const chains = new Map<string, Promise<void>>();
36
+
37
+ export async function publishCard(
38
+ paseo: PaseoApi,
39
+ entry: AttentionEntry,
40
+ options?: { superseded?: boolean },
41
+ ): Promise<void> {
42
+ const rowId = `summary:${entry.eventId}`;
43
+ const superseded = options?.superseded === true;
44
+ const next = (chains.get(rowId) ?? Promise.resolve()).then(() => append(paseo, entry, rowId, superseded));
45
+ chains.set(rowId, next);
46
+ try {
47
+ await next;
48
+ } finally {
49
+ // Only the last link clears the row, or a later append would lose its queue.
50
+ if (chains.get(rowId) === next) chains.delete(rowId);
51
+ }
52
+ }
53
+
54
+ /** Never rejects: a card is a nicety, and the chain behind it has to keep moving. */
55
+ async function append(
56
+ paseo: PaseoApi,
57
+ entry: AttentionEntry,
58
+ rowId: string,
59
+ superseded: boolean,
60
+ ): Promise<void> {
61
+ try {
62
+ await paseo.agents.ref(entry.agentId).timeline.append({
63
+ type: "plugin",
64
+ id: rowId,
65
+ kind: HERALD_CARD_KIND,
66
+ version: HERALD_CARD_VERSION,
67
+ data: cardFor(entry, superseded),
68
+ });
69
+ } catch (error) {
70
+ const message = error instanceof Error ? error.message : String(error);
71
+ if (reported.has(message)) return;
72
+ reported.add(message);
73
+ console.warn(`[herald] could not add the summary card to agent ${entry.agentId}'s transcript: ${message}`);
74
+ }
75
+ }
@@ -0,0 +1,62 @@
1
+ /**
2
+ * The daemon's own file: `$PASEO_HOME/plugins/herald/config.json`. It holds
3
+ * what the hooks act on — which events get a summary and which model writes
4
+ * it — and nothing the app only draws.
5
+ *
6
+ * Read on every event rather than cached: a save from the settings screen has
7
+ * to take effect on the next event, and the file is a few hundred bytes.
8
+ */
9
+ import { mkdir, readFile, writeFile } from "node:fs/promises";
10
+ import { homedir } from "node:os";
11
+ import { dirname, join } from "node:path";
12
+
13
+ import { DEFAULT_CONFIG, HeraldConfigSchema, type HeraldConfig } from "../shared/herald";
14
+
15
+ export function paseoHome(): string {
16
+ return process.env.PASEO_HOME ?? join(homedir(), ".paseo");
17
+ }
18
+
19
+ export function pluginDir(): string {
20
+ return join(paseoHome(), "plugins", "herald");
21
+ }
22
+
23
+ function configPath(): string {
24
+ return join(pluginDir(), "config.json");
25
+ }
26
+
27
+ /**
28
+ * A missing file is the normal first run and yields the defaults. A file that
29
+ * does not parse is reported and *also* yields the defaults: a hook that threw
30
+ * here would silently stop announcing, which is worse than announcing with the
31
+ * default model until the file is fixed.
32
+ */
33
+ export async function readHeraldConfig(): Promise<HeraldConfig> {
34
+ let raw: string;
35
+ try {
36
+ raw = await readFile(configPath(), "utf8");
37
+ } catch (error) {
38
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return structuredClone(DEFAULT_CONFIG);
39
+ throw error;
40
+ }
41
+ let json: unknown;
42
+ try {
43
+ json = JSON.parse(raw);
44
+ } catch (error) {
45
+ console.error(`[herald] ${configPath()} is not JSON, using defaults:`, error);
46
+ return structuredClone(DEFAULT_CONFIG);
47
+ }
48
+ const parsed = HeraldConfigSchema.safeParse(json);
49
+ if (!parsed.success) {
50
+ console.error(`[herald] ${configPath()} is invalid, using defaults: ${parsed.error.message}`);
51
+ return structuredClone(DEFAULT_CONFIG);
52
+ }
53
+ return parsed.data;
54
+ }
55
+
56
+ export async function writeHeraldConfig(config: HeraldConfig): Promise<HeraldConfig> {
57
+ const parsed = HeraldConfigSchema.parse(config);
58
+ const path = configPath();
59
+ await mkdir(dirname(path), { recursive: true });
60
+ await writeFile(path, `${JSON.stringify(parsed, null, 2)}\n`, "utf8");
61
+ return parsed;
62
+ }