@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.
@@ -0,0 +1,407 @@
1
+ /**
2
+ * Settings › Plugins › Herald. Two groups, two stores:
3
+ *
4
+ * - **Speech** is the host settings document from `shared/settings.ts` — read
5
+ * by every client of this daemon, acted on by each according to its own
6
+ * platform switch. Saved through `useSettings`.
7
+ * - **Summaries** is the daemon's file — which events get a summary, which
8
+ * model writes it, and the prompt it is written from — read by the hooks, so
9
+ * it goes through two RPCs.
10
+ *
11
+ * Async function expressions only; see `client/herald.tsx`.
12
+ */
13
+ import { type PluginSurfaceProps, usePaseo, useRpc, useSettings } from "@getpaseo/plugin/client";
14
+ import { useToast } from "@getpaseo/plugin/client/react-native";
15
+ import {
16
+ SettingsAction,
17
+ SettingsGroup,
18
+ SettingsSection,
19
+ SettingsSelect,
20
+ SettingsSwitch,
21
+ } from "@getpaseo/plugin/client/ui";
22
+ import { useCallback, useEffect, useMemo, useState } from "react";
23
+ import { ScrollView, Text, View } from "react-native";
24
+
25
+ import {
26
+ ANNOUNCE_KEYS,
27
+ listSpeechVoices,
28
+ readConfig,
29
+ writeConfig,
30
+ type AnnounceKey,
31
+ type HeraldConfig,
32
+ type SpeechVoice,
33
+ } from "../shared/herald";
34
+ import {
35
+ RATE_OPTIONS,
36
+ speechSettings,
37
+ type RateOption,
38
+ type SpeechEngine,
39
+ type SpeechSettings,
40
+ } from "../shared/settings";
41
+ import { getAnnouncer, mirrorSettings } from "./announcer";
42
+ import { OptionPicker, type PickerOption } from "./option-picker";
43
+ import { PromptEditor } from "./prompt-editor";
44
+ import { canSpeak, listVoices, onVoicesChanged, speechPlatform, type Voice } from "./web";
45
+
46
+ const RATE_LABELS: Record<RateOption, string> = {
47
+ "0.8": "Slower",
48
+ "1": "Normal",
49
+ "1.2": "Faster",
50
+ "1.5": "Fast",
51
+ };
52
+
53
+ const ANNOUNCE_LABELS: Record<AnnounceKey, { label: string; hint: string }> = {
54
+ question: { label: "Questions", hint: "The agent asked you something and is waiting for the answer." },
55
+ plan: { label: "Plan approvals", hint: "The agent wrote a plan and wants a go-ahead." },
56
+ permission: { label: "Tool permissions", hint: "Allow-or-deny prompts for commands and edits. Noisy unless agents run restricted." },
57
+ finished: { label: "Finished turns", hint: "The agent stopped and is waiting for your next message." },
58
+ error: { label: "Errors and interruptions", hint: "The turn failed or was cancelled." },
59
+ };
60
+
61
+ function errorText(error: unknown): string {
62
+ return error instanceof Error ? error.message : String(error);
63
+ }
64
+
65
+ export function HeraldSettingsScreen(props: PluginSurfaceProps) {
66
+ const { theme, layout } = props;
67
+ const toast = useToast();
68
+ const paseo = usePaseo();
69
+ const settings = useSettings(speechSettings);
70
+ const read = useRpc(readConfig);
71
+ const write = useRpc(writeConfig);
72
+
73
+ // Keep the announcer's fallback current with what this screen shows.
74
+ useEffect(() => {
75
+ if (settings.status === "ready") mirrorSettings(settings.values);
76
+ }, [settings]);
77
+
78
+ const saveSpeech = useCallback(
79
+ async function saveSpeech(patch: Partial<SpeechSettings>) {
80
+ if (settings.status !== "ready") return;
81
+ const next = { ...settings.values, ...patch };
82
+ const saved = await settings.save(next, settings.revision);
83
+ if (saved) mirrorSettings(next);
84
+ else toast.error(settings.saveError ?? "The speech settings were not saved.");
85
+ },
86
+ [settings, toast],
87
+ );
88
+
89
+ // ---- voices -------------------------------------------------------------
90
+ const [voices, setVoices] = useState<Voice[]>(() => listVoices());
91
+ useEffect(() => onVoicesChanged(() => setVoices(listVoices())), []);
92
+ const voiceOptions = useMemo((): PickerOption[] => {
93
+ const options: PickerOption[] = voices.map((voice) => ({ label: voice.name, value: voice.name, detail: voice.lang }));
94
+ const current = settings.status === "ready" ? settings.values.voice : "";
95
+ if (current !== "" && !options.some((option) => option.value === current)) {
96
+ options.unshift({ label: current, value: current, detail: "not on this device" });
97
+ }
98
+ return [{ label: "System default", value: "" }, ...options];
99
+ }, [voices, settings]);
100
+
101
+ // ---- the daemon Mac's voices ---------------------------------------------
102
+ const fetchSayVoices = useRpc(listSpeechVoices);
103
+ const [sayVoices, setSayVoices] = useState<{ available: boolean; voices: SpeechVoice[] } | null>(null);
104
+ useEffect(() => {
105
+ let cancelled = false;
106
+ fetchSayVoices({})
107
+ .then((result) => {
108
+ if (!cancelled) setSayVoices(result);
109
+ })
110
+ .catch((caught: unknown) => {
111
+ console.warn("[herald] could not list say voices", caught);
112
+ if (!cancelled) setSayVoices({ available: false, voices: [] });
113
+ });
114
+ return () => {
115
+ cancelled = true;
116
+ };
117
+ }, [fetchSayVoices]);
118
+ const sayVoiceOptions = useMemo((): PickerOption[] => {
119
+ const options: PickerOption[] = (sayVoices?.voices ?? []).map((voice) => ({
120
+ label: voice.name,
121
+ value: voice.name,
122
+ detail: voice.lang,
123
+ }));
124
+ const current = settings.status === "ready" ? settings.values.sayVoice : "";
125
+ if (current !== "" && !options.some((option) => option.value === current)) {
126
+ options.unshift({ label: current, value: current, detail: "not installed on the daemon" });
127
+ }
128
+ return [{ label: "The Mac's default voice", value: "" }, ...options];
129
+ }, [sayVoices, settings]);
130
+
131
+ const [testing, setTesting] = useState(false);
132
+ const onTest = useCallback(
133
+ async function onTest() {
134
+ const announcer = getAnnouncer();
135
+ if (announcer === null) return;
136
+ setTesting(true);
137
+ try {
138
+ // Forced: this is where the voice is chosen, so it has to speak even
139
+ // with announcements off, and on the web it is the press that hands
140
+ // the browser its audio permission.
141
+ await announcer.speakText("This is Herald. Your agents will be announced like this.", { force: true });
142
+ } catch (caught) {
143
+ toast.error(errorText(caught));
144
+ } finally {
145
+ setTesting(false);
146
+ }
147
+ },
148
+ [toast],
149
+ );
150
+
151
+ // ---- daemon config ------------------------------------------------------
152
+ const [config, setConfig] = useState<HeraldConfig | null>(null);
153
+ const [configError, setConfigError] = useState<string | null>(null);
154
+ useEffect(() => {
155
+ let cancelled = false;
156
+ read({})
157
+ .then((loaded) => {
158
+ if (!cancelled) setConfig(loaded);
159
+ })
160
+ .catch((caught: unknown) => {
161
+ if (!cancelled) setConfigError(errorText(caught));
162
+ });
163
+ return () => {
164
+ cancelled = true;
165
+ };
166
+ }, [read]);
167
+
168
+ const saveConfig = useCallback(
169
+ async function saveConfig(next: HeraldConfig) {
170
+ setConfig(next);
171
+ try {
172
+ setConfig(await write(next));
173
+ setConfigError(null);
174
+ } catch (caught) {
175
+ setConfigError(errorText(caught));
176
+ toast.error(errorText(caught));
177
+ }
178
+ },
179
+ [write, toast],
180
+ );
181
+
182
+ const [models, setModels] = useState<PickerOption[]>([]);
183
+ useEffect(() => {
184
+ let cancelled = false;
185
+ async function loadModels() {
186
+ const available = await paseo.providers.listAvailable();
187
+ const providers = available.providers.filter((entry) => entry.available).map((entry) => entry.provider);
188
+ const lists = await Promise.all(
189
+ providers.map(function (provider) {
190
+ return paseo.providers.listModels(provider).catch(() => null);
191
+ }),
192
+ );
193
+ const options: PickerOption[] = [];
194
+ lists.forEach((result, index) => {
195
+ const provider = providers[index];
196
+ if (result === null || provider === undefined) return;
197
+ (result.models ?? [])
198
+ .filter((model) => model.isSelectable !== false)
199
+ .forEach((model) => options.push({ label: model.label, value: `${provider}/${model.id}`, detail: provider }));
200
+ });
201
+ if (!cancelled) setModels(options);
202
+ }
203
+ loadModels().catch((caught: unknown) => {
204
+ console.warn("[herald] could not list models", caught);
205
+ });
206
+ return () => {
207
+ cancelled = true;
208
+ };
209
+ }, [paseo]);
210
+
211
+ const modelOptions = useMemo((): PickerOption[] => {
212
+ const current = config?.summarizer.provider ?? "";
213
+ if (current === "" || models.some((option) => option.value === current)) return models;
214
+ return [{ label: current, value: current, detail: "typed in" }, ...models];
215
+ }, [models, config]);
216
+
217
+ const styles = useMemo(
218
+ () => ({
219
+ screen: { flex: 1, backgroundColor: theme.colors.surface0 },
220
+ content: { padding: layout.compact ? 12 : 20, gap: 16 },
221
+ note: { color: theme.colors.foregroundMuted, fontSize: 12, lineHeight: 17 },
222
+ error: { color: theme.colors.statusDanger, fontSize: 13 },
223
+ }),
224
+ [theme, layout.compact],
225
+ );
226
+
227
+ const platform = speechPlatform();
228
+ const speech = settings.status === "ready" ? settings.values : null;
229
+
230
+ return (
231
+ <ScrollView style={styles.screen} contentContainerStyle={styles.content}>
232
+ <SettingsGroup title="Speech">
233
+ <SettingsSection
234
+ title="Where to speak"
235
+ info={
236
+ <Text style={styles.note}>
237
+ These switches are shared by every device connected to this daemon; each device follows its
238
+ own. You are on {platform === "desktop" ? "the desktop app" : platform === "browser" ? "a browser tab" : "a phone"}.
239
+ </Text>
240
+ }
241
+ >
242
+ <SettingsSwitch
243
+ label="Announce out loud"
244
+ hint="The master switch. Off means nothing is spoken or vibrated anywhere."
245
+ value={speech?.enabled ?? true}
246
+ disabled={speech === null}
247
+ onValueChange={(value) => void saveSpeech({ enabled: value })}
248
+ />
249
+ <SettingsSwitch
250
+ label="Speak on the desktop app"
251
+ value={speech?.speakOnDesktop ?? true}
252
+ disabled={speech === null}
253
+ onValueChange={(value) => void saveSpeech({ speakOnDesktop: value })}
254
+ />
255
+ <SettingsSwitch
256
+ label="Speak in a browser tab"
257
+ hint="A browser only lets a page speak after it has been tapped once."
258
+ value={speech?.speakInBrowser ?? true}
259
+ disabled={speech === null}
260
+ onValueChange={(value) => void saveSpeech({ speakInBrowser: value })}
261
+ />
262
+ <SettingsSwitch
263
+ label="Vibrate on phones"
264
+ hint="Phones cannot speak from a plugin yet; a short buzz is the most they can do."
265
+ value={speech?.vibrateOnMobile ?? false}
266
+ disabled={speech === null}
267
+ onValueChange={(value) => void saveSpeech({ vibrateOnMobile: value })}
268
+ />
269
+ </SettingsSection>
270
+ {platform === "mobile" ? null : (
271
+ <SettingsSection
272
+ title="Voice"
273
+ info={
274
+ <Text style={styles.note}>
275
+ The daemon Mac can render each sentence with its own voices, which sound far better than a
276
+ browser's, and this device plays the audio. If the daemon is not a Mac, or a render fails,
277
+ the browser voice is used instead.
278
+ </Text>
279
+ }
280
+ >
281
+ <SettingsSelect<SpeechEngine>
282
+ label="Voice source"
283
+ value={speech?.engine ?? "say"}
284
+ options={[
285
+ {
286
+ label: sayVoices?.available === false ? "The daemon Mac (say) — not available" : "The daemon Mac (say)",
287
+ value: "say",
288
+ },
289
+ { label: "This device's browser voice", value: "web" },
290
+ ]}
291
+ disabled={speech === null}
292
+ onValueChange={(value) => void saveSpeech({ engine: value })}
293
+ />
294
+ {speech?.engine === "say" ? (
295
+ <OptionPicker
296
+ label="Mac voice"
297
+ hint="Installed on the daemon Mac. Add more under System Settings › Accessibility › Spoken Content there."
298
+ title="Mac voice"
299
+ searchPlaceholder="Search voices or languages"
300
+ value={speech.sayVoice}
301
+ options={sayVoiceOptions}
302
+ disabled={sayVoices === null || !sayVoices.available}
303
+ onSelect={(value) => void saveSpeech({ sayVoice: value })}
304
+ theme={theme}
305
+ compact={layout.compact}
306
+ />
307
+ ) : canSpeak() ? (
308
+ <OptionPicker
309
+ label="Browser voice"
310
+ hint="A system voice on this device. Other devices keep their own default."
311
+ title="Browser voice"
312
+ searchPlaceholder="Search voices or languages"
313
+ value={speech?.voice ?? ""}
314
+ options={voiceOptions}
315
+ disabled={speech === null}
316
+ onSelect={(value) => void saveSpeech({ voice: value })}
317
+ theme={theme}
318
+ compact={layout.compact}
319
+ />
320
+ ) : null}
321
+ <SettingsSelect<RateOption>
322
+ label="Speed"
323
+ value={speech?.rate ?? "1"}
324
+ options={RATE_OPTIONS.map((rate) => ({ label: RATE_LABELS[rate], value: rate }))}
325
+ disabled={speech === null}
326
+ onValueChange={(value) => void saveSpeech({ rate: value })}
327
+ />
328
+ <SettingsAction
329
+ label="Test voice"
330
+ hint="Speaks one sentence with the settings above."
331
+ actionLabel={testing ? "Speaking…" : "Speak"}
332
+ disabled={testing || speech === null}
333
+ onPress={() => void onTest()}
334
+ />
335
+ </SettingsSection>
336
+ )}
337
+ </SettingsGroup>
338
+
339
+ <SettingsGroup title="Summaries">
340
+ <SettingsSection
341
+ title="Model"
342
+ info={
343
+ <Text style={styles.note}>
344
+ Each summary is one short turn of a helper agent on the daemon, placed under the agent it
345
+ describes and archived when it finishes. A small, fast model is plenty for one sentence.
346
+ </Text>
347
+ }
348
+ >
349
+ {configError === null ? null : <Text style={styles.error}>{configError}</Text>}
350
+ <OptionPicker
351
+ label="Summary model"
352
+ title="Summary model"
353
+ searchPlaceholder="Search models or providers"
354
+ value={config?.summarizer.provider ?? ""}
355
+ options={modelOptions}
356
+ disabled={config === null}
357
+ onSelect={(value) => {
358
+ if (config !== null && value !== "") void saveConfig({ ...config, summarizer: { ...config.summarizer, provider: value } });
359
+ }}
360
+ theme={theme}
361
+ compact={layout.compact}
362
+ />
363
+ </SettingsSection>
364
+ <SettingsSection
365
+ title="Prompt"
366
+ info={
367
+ <Text style={styles.note}>
368
+ What the helper is asked, before every summary. Herald fills in the agent, the event and
369
+ what was said; the rest is yours — the length, the tone, the language, what matters for
370
+ each kind of event.
371
+ </Text>
372
+ }
373
+ >
374
+ <PromptEditor
375
+ label="Summary prompt"
376
+ hint="Opens the prompt for editing, with the list of placeholders Herald fills in."
377
+ value={config?.summarizer.prompt ?? ""}
378
+ disabled={config === null}
379
+ onSave={(next) => {
380
+ if (config !== null) void saveConfig({ ...config, summarizer: { ...config.summarizer, prompt: next } });
381
+ }}
382
+ theme={theme}
383
+ compact={layout.compact}
384
+ />
385
+ </SettingsSection>
386
+ <SettingsSection
387
+ title="What gets announced"
388
+ info={<Text style={styles.note}>An event that is switched off still appears in the Herald panel, without a summary and without being spoken.</Text>}
389
+ >
390
+ {ANNOUNCE_KEYS.map((key) => (
391
+ <SettingsSwitch
392
+ key={key}
393
+ label={ANNOUNCE_LABELS[key].label}
394
+ hint={ANNOUNCE_LABELS[key].hint}
395
+ value={config?.announce[key] ?? true}
396
+ disabled={config === null}
397
+ onValueChange={(value) => {
398
+ if (config !== null) void saveConfig({ ...config, announce: { ...config.announce, [key]: value } });
399
+ }}
400
+ />
401
+ ))}
402
+ </SettingsSection>
403
+ </SettingsGroup>
404
+ <View style={{ height: 24 }} />
405
+ </ScrollView>
406
+ );
407
+ }
@@ -0,0 +1,146 @@
1
+ /**
2
+ * Herald's card in an agent's transcript: the sentence written about the
3
+ * turn or question just above it, and a play icon right after the header's
4
+ * label that says it again — absent on iOS and Android, which cannot play it.
5
+ *
6
+ * The row is written by the daemon (`server/card.ts`); this only draws it.
7
+ * The host re-validates `data` against `HeraldCardSchema` before calling this,
8
+ * so an older row that no longer fits renders as unavailable rather than here.
9
+ *
10
+ * Async function expressions only; see `client/herald.tsx`.
11
+ */
12
+ import type { PluginTimelineItemProps } from "@getpaseo/plugin/client";
13
+ import { Icon, useToast } from "@getpaseo/plugin/client/react-native";
14
+ import { useCallback, useMemo, useState } from "react";
15
+ import { ActivityIndicator, Pressable, Text, View } from "react-native";
16
+
17
+ import type { AttentionReason } from "../shared/herald";
18
+ import type { HeraldCard } from "../shared/timeline";
19
+ import { getAnnouncer } from "./announcer";
20
+ import { canPlaySpeech } from "./web";
21
+
22
+ function reasonLabel(reason: AttentionReason): string {
23
+ switch (reason) {
24
+ case "question":
25
+ return "Question";
26
+ case "plan":
27
+ return "Plan to approve";
28
+ case "permission":
29
+ return "Permission";
30
+ case "finished":
31
+ return "Finished";
32
+ case "error":
33
+ return "Error";
34
+ case "canceled":
35
+ return "Interrupted";
36
+ }
37
+ }
38
+
39
+ function spokenText(card: HeraldCard): string | null {
40
+ switch (card.summary.status) {
41
+ case "ready":
42
+ return card.summary.text;
43
+ case "failed":
44
+ return card.summary.fallback;
45
+ // In a card, `off` is a summary that was never written — the event was
46
+ // superseded before its turn in the queue. A kind switched off in settings
47
+ // never reaches a card at all, because none is published for it.
48
+ case "off":
49
+ return card.summary.fallback;
50
+ case "pending":
51
+ return null;
52
+ }
53
+ }
54
+
55
+ export function HeraldTimelineCard({ theme, layout, item }: PluginTimelineItemProps<HeraldCard>) {
56
+ const card = item.data;
57
+ // The agent carried on, so this completion was not one. The row cannot be
58
+ // taken back, only replaced, so the replacement draws nothing at all.
59
+ const superseded = card.superseded;
60
+ const text = spokenText(card);
61
+ const toast = useToast();
62
+ const [speaking, setSpeaking] = useState(false);
63
+
64
+ const styles = useMemo(() => {
65
+ const { colors } = theme;
66
+ return {
67
+ card: {
68
+ borderWidth: 1,
69
+ borderColor: colors.border,
70
+ borderRadius: 10,
71
+ backgroundColor: colors.surface1,
72
+ paddingHorizontal: layout.compact ? 10 : 12,
73
+ paddingVertical: layout.compact ? 8 : 10,
74
+ gap: 6,
75
+ },
76
+ header: { flexDirection: "row" as const, alignItems: "center" as const, gap: 6 },
77
+ brand: { color: colors.foregroundMuted, fontSize: 12, fontWeight: "600" as const },
78
+ reason: { color: colors.foregroundMuted, fontSize: 12 },
79
+ spacer: { flex: 1 },
80
+ text: {
81
+ color: colors.foreground,
82
+ fontSize: layout.compact ? 15 : 14,
83
+ lineHeight: layout.compact ? 21 : 20,
84
+ fontStyle: "italic" as const,
85
+ },
86
+ pending: { flexDirection: "row" as const, alignItems: "center" as const, gap: 8 },
87
+ pendingText: { color: colors.foregroundMuted, fontSize: 13 },
88
+ note: { color: colors.foregroundMuted, fontSize: 11 },
89
+ play: { padding: 4 },
90
+ playDisabled: { opacity: 0.4 },
91
+ };
92
+ }, [theme, layout.compact]);
93
+
94
+ const play = useCallback(
95
+ async function play() {
96
+ const announcer = getAnnouncer();
97
+ if (announcer === null || text === null) return;
98
+ setSpeaking(true);
99
+ try {
100
+ const blocked = await announcer.speakText(text);
101
+ if (blocked !== null) toast.show(blocked, { variant: "info" });
102
+ } catch (error) {
103
+ toast.error(error instanceof Error ? error.message : String(error));
104
+ } finally {
105
+ setSpeaking(false);
106
+ }
107
+ },
108
+ [text, toast],
109
+ );
110
+
111
+ if (superseded) return null;
112
+
113
+ return (
114
+ <View style={styles.card}>
115
+ <View style={styles.header}>
116
+ <Icon name="Megaphone" size={14} color={theme.colors.foregroundMuted} />
117
+ <Text style={styles.brand}>Herald</Text>
118
+ <Text style={styles.reason}>· {reasonLabel(card.reason)}</Text>
119
+ {canPlaySpeech() ? (
120
+ <Pressable
121
+ accessibilityRole="button"
122
+ accessibilityLabel={speaking ? "Speaking" : "Play the summary"}
123
+ hitSlop={8}
124
+ disabled={text === null || speaking}
125
+ onPress={() => void play()}
126
+ style={[styles.play, text === null || speaking ? styles.playDisabled : null]}
127
+ >
128
+ <Icon name={speaking ? "Volume2" : "Play"} size={14} color={theme.colors.foreground} />
129
+ </Pressable>
130
+ ) : null}
131
+ <View style={styles.spacer} />
132
+ </View>
133
+ {card.summary.status === "pending" ? (
134
+ <View style={styles.pending}>
135
+ <ActivityIndicator size="small" color={theme.colors.foregroundMuted} />
136
+ <Text style={styles.pendingText}>Writing the summary…</Text>
137
+ </View>
138
+ ) : (
139
+ <Text style={styles.text}>{text ?? card.headline}</Text>
140
+ )}
141
+ {card.summary.status === "failed" ? (
142
+ <Text style={styles.note}>Summary failed: {card.summary.error}</Text>
143
+ ) : null}
144
+ </View>
145
+ );
146
+ }