@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/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
|
+
}
|
package/index.client.tsx
ADDED
|
@@ -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
|
+
}
|
package/index.server.ts
ADDED
|
@@ -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
|
+
}
|
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
|
+
}
|
package/server/config.ts
ADDED
|
@@ -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
|
+
}
|