@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,234 @@
1
+ /**
2
+ * The contracts both halves agree on: what one "needs you" entry looks like,
3
+ * the RPC that lists them, and the daemon-side configuration document.
4
+ *
5
+ * Which side owns a value follows the rule in the root CLAUDE.md — the side that
6
+ * has to *read* it. Everything in `HeraldConfigSchema` is read by the daemon's
7
+ * hooks (which events to summarise, which model writes the summary), so it
8
+ * lives in the daemon's own file behind two RPCs. How the summary is *spoken*
9
+ * is read only by the app and lives in `shared/settings.ts`.
10
+ */
11
+ import { defineRpc } from "@getpaseo/plugin";
12
+ import { z } from "zod";
13
+
14
+ /**
15
+ * Why an agent is waiting. The first three come from permission requests —
16
+ * Paseo maps Claude's AskUserQuestion to `question` and ExitPlanMode to
17
+ * `plan`, and everything else that pauses for approval is `permission`. The
18
+ * last three come from how a turn ended.
19
+ */
20
+ export const ATTENTION_REASONS = [
21
+ "question",
22
+ "plan",
23
+ "permission",
24
+ "finished",
25
+ "error",
26
+ "canceled",
27
+ ] as const;
28
+ export type AttentionReason = (typeof ATTENTION_REASONS)[number];
29
+ export const AttentionReasonSchema = z.enum(ATTENTION_REASONS);
30
+
31
+ /**
32
+ * The summary's lifecycle. `pending` while the helper agent is writing;
33
+ * `ready` with its sentence; `failed` with the reason and a deterministic
34
+ * fallback built from the raw event; `off` when no summary was written at all
35
+ * — the event kind is switched off in the daemon config, or the user moved on
36
+ * before the queued summary reached the front — recorded so the panel and the
37
+ * transcript card can still say something, but never spoken by the announcer.
38
+ */
39
+ export const SummaryStateSchema = z.discriminatedUnion("status", [
40
+ z.object({ status: z.literal("pending") }),
41
+ z.object({ status: z.literal("ready"), text: z.string(), model: z.string() }),
42
+ z.object({ status: z.literal("failed"), error: z.string(), fallback: z.string() }),
43
+ z.object({ status: z.literal("off"), fallback: z.string() }),
44
+ ]);
45
+ export type SummaryState = z.infer<typeof SummaryStateSchema>;
46
+
47
+ export const AttentionEntrySchema = z.object({
48
+ agentId: z.string(),
49
+ workspaceId: z.string().nullable(),
50
+ /**
51
+ * The name the user knows the work by. Agents are usually untitled, so the
52
+ * workspace's title (or name) is the headline and the agent's own title,
53
+ * when it has one, is the second line. Defaulted so entries written before
54
+ * the field existed still load.
55
+ */
56
+ workspaceTitle: z.string().nullable().default(null),
57
+ agentTitle: z.string().nullable(),
58
+ /**
59
+ * The start of what the user last asked this agent, for telling two
60
+ * untitled agents in one workspace apart. Null for a pause, which carries
61
+ * no timeline.
62
+ */
63
+ lastRequest: z.string().nullable().default(null),
64
+ cwd: z.string(),
65
+ reason: AttentionReasonSchema,
66
+ /** Unique per event, so a client can remember what it has already spoken. */
67
+ eventId: z.string(),
68
+ /** The permission request this entry answers to, when it is one. */
69
+ requestId: z.string().nullable(),
70
+ createdAt: z.string(),
71
+ /** One line built without a model: the question, the command, "Finished". */
72
+ headline: z.string(),
73
+ /** The choices, the command, or the start of the final message. */
74
+ detail: z.string().nullable(),
75
+ summary: SummaryStateSchema,
76
+ });
77
+ export type AttentionEntry = z.infer<typeof AttentionEntrySchema>;
78
+
79
+ export const listAttention = defineRpc({
80
+ name: "herald.list",
81
+ input: z.object({}),
82
+ output: z.object({ entries: z.array(AttentionEntrySchema) }),
83
+ });
84
+
85
+ // ---------------------------------------------------------------------------
86
+ // Speech rendered on the daemon
87
+
88
+ export const SpeechVoiceSchema = z.object({ name: z.string(), lang: z.string() });
89
+ export type SpeechVoice = z.infer<typeof SpeechVoiceSchema>;
90
+
91
+ /**
92
+ * The daemon Mac's `say` voices, and whether `say` is there at all. The app
93
+ * cannot run a command, but the daemon can, and its voices are better than
94
+ * the browser's; so the daemon renders the sentence to audio and the app plays
95
+ * the bytes.
96
+ */
97
+ export const listSpeechVoices = defineRpc({
98
+ name: "herald.speech.voices",
99
+ input: z.object({}),
100
+ output: z.object({ available: z.boolean(), voices: z.array(SpeechVoiceSchema) }),
101
+ });
102
+
103
+ export const MAX_SPEECH_CHARS = 2000;
104
+
105
+ export const renderSpeech = defineRpc({
106
+ name: "herald.speech.render",
107
+ input: z.object({
108
+ text: z.string().min(1).max(MAX_SPEECH_CHARS),
109
+ /** A `say` voice name, or empty for the Mac's default. */
110
+ voice: z.string().default(""),
111
+ /** A multiplier on the voice's natural pace. */
112
+ rate: z.number().min(0.5).max(2).default(1),
113
+ }),
114
+ output: z.object({ mimeType: z.string(), base64: z.string() }),
115
+ });
116
+
117
+ // ---------------------------------------------------------------------------
118
+ // Daemon-side configuration
119
+
120
+ /** The event kinds a user can switch off. A canceled turn follows `error`. */
121
+ export const ANNOUNCE_KEYS = ["question", "plan", "permission", "finished", "error"] as const;
122
+ export type AnnounceKey = (typeof ANNOUNCE_KEYS)[number];
123
+
124
+ export function announceKeyFor(reason: AttentionReason): AnnounceKey {
125
+ return reason === "canceled" ? "error" : reason;
126
+ }
127
+
128
+ /**
129
+ * What a prompt template may put in `{{ }}`, and what the daemon fills each
130
+ * one with. The descriptions are what the settings screen lists, so they are
131
+ * written for the person editing the prompt.
132
+ *
133
+ * Two rules the editor states and `renderPrompt` keeps: a **line** whose
134
+ * placeholder has nothing to fill it for this event is left out whole — that
135
+ * is how "Detail: {{detail}}" disappears for an event with no detail — and a
136
+ * name that is not on this list is left in the prompt exactly as typed.
137
+ */
138
+ export const PROMPT_PLACEHOLDERS = [
139
+ { name: "agent", description: "What the work is called: the agent's title, or its workspace's." },
140
+ { name: "workspace", description: "The workspace's title, or the folder name when it has none." },
141
+ { name: "folder", description: "The last part of the agent's working directory." },
142
+ { name: "event", description: "A sentence saying why the agent is waiting — a question, a plan, a finished turn." },
143
+ { name: "headline", description: "The one line Herald builds without a model: the question, the command, \"Finished\"." },
144
+ { name: "detail", description: "The choices, the command, or the start of the final message. Often empty." },
145
+ { name: "request", description: "What the user last asked this agent for. Empty when the agent paused without one." },
146
+ { name: "output", description: "What the agent said since that last message. Empty for a pause." },
147
+ ] as const;
148
+ export type PromptPlaceholder = (typeof PROMPT_PLACEHOLDERS)[number]["name"];
149
+
150
+ /**
151
+ * The prompt every summary starts from, and what *Restore the default* puts
152
+ * back. The closing line is what makes the helper answer with
153
+ * `{"speech": "..."}`; a template without it still works — the parser falls
154
+ * back to reading the reply as prose — but the sentence is less predictable.
155
+ */
156
+ export const DEFAULT_SUMMARY_PROMPT = [
157
+ // One line per paragraph: the editor wraps them, and a break typed here is a
158
+ // break the reader has to tidy up before editing the sentence it lands in.
159
+ "You are Herald. You tell a developer, out loud, what one of their coding agents needs. Answer with the JSON object only. Do not run tools, read files, or ask anything back.",
160
+ "",
161
+ 'Agent: "{{agent}}", working in the workspace "{{workspace}}" (folder {{folder}}).',
162
+ "Event: {{event}}",
163
+ "Headline: {{headline}}",
164
+ "Detail: {{detail}}",
165
+ "",
166
+ "What the user last asked for: {{request}}",
167
+ "",
168
+ "What the agent said: {{output}}",
169
+ "",
170
+ "Write what should be spoken: one or two sentences, under 35 words, plain text with no markdown, no code, and no file paths unless nothing else identifies the work. Start with the agent's name as given above, so the listener knows which piece of work this is about. For a question, say what is being asked and the choices. For finished work, say what was done and whether anything is left for the user. For a permission, say what the agent wants to do.",
171
+ "",
172
+ 'Reply with exactly one JSON object shaped like {"speech": "..."} — the key must be "speech", no code fences, nothing before or after it.',
173
+ ].join("\n");
174
+
175
+ export const DEFAULT_SUMMARIZER = {
176
+ /** `provider/model`, the format the Paseo SDK takes. */
177
+ provider: "claude/claude-haiku-4-5",
178
+ /** How long one summary may take before it is given up on and the fallback is used. */
179
+ timeoutMs: 90_000,
180
+ /** The template the helper's prompt is rendered from. */
181
+ prompt: DEFAULT_SUMMARY_PROMPT,
182
+ };
183
+
184
+ export const DEFAULT_ANNOUNCE: Record<AnnounceKey, boolean> = {
185
+ question: true,
186
+ plan: true,
187
+ permission: true,
188
+ finished: true,
189
+ error: true,
190
+ };
191
+
192
+ /**
193
+ * Spelled with full defaults at every level so that parsing `{}` — a daemon
194
+ * that has never saved — yields a complete document. Zod 4 returns a
195
+ * `.default()` value as-is without parsing it, which is why the defaults are
196
+ * complete objects rather than `{}`.
197
+ */
198
+ export const HeraldConfigSchema = z.object({
199
+ summarizer: z
200
+ .object({
201
+ provider: z.string().min(1).default(DEFAULT_SUMMARIZER.provider),
202
+ timeoutMs: z.number().int().min(10_000).max(600_000).default(DEFAULT_SUMMARIZER.timeoutMs),
203
+ /** Blank is not an error: `buildPrompt` reads it as "use the default". */
204
+ prompt: z.string().default(DEFAULT_SUMMARY_PROMPT),
205
+ })
206
+ .default(DEFAULT_SUMMARIZER),
207
+ announce: z
208
+ .object({
209
+ question: z.boolean().default(true),
210
+ plan: z.boolean().default(true),
211
+ permission: z.boolean().default(true),
212
+ finished: z.boolean().default(true),
213
+ error: z.boolean().default(true),
214
+ })
215
+ .default(DEFAULT_ANNOUNCE),
216
+ });
217
+ export type HeraldConfig = z.infer<typeof HeraldConfigSchema>;
218
+
219
+ export const DEFAULT_CONFIG: HeraldConfig = {
220
+ summarizer: { ...DEFAULT_SUMMARIZER },
221
+ announce: { ...DEFAULT_ANNOUNCE },
222
+ };
223
+
224
+ export const readConfig = defineRpc({
225
+ name: "herald.config.read",
226
+ input: z.object({}),
227
+ output: HeraldConfigSchema,
228
+ });
229
+
230
+ export const writeConfig = defineRpc({
231
+ name: "herald.config.write",
232
+ input: HeraldConfigSchema,
233
+ output: HeraldConfigSchema,
234
+ });
@@ -0,0 +1,60 @@
1
+ /**
2
+ * How a summary is spoken, per daemon: the app reads it, the daemon never
3
+ * does, so it is a host settings document rather than a daemon file.
4
+ *
5
+ * `scope: "host"` reaches every authorized client of one daemon, which is
6
+ * why the platform switches exist: the same document is read on the desktop
7
+ * app, in a browser tab, and on a phone, and each one only acts on its own
8
+ * switch. That is how "speak on my Mac but not on my laptop's browser" is
9
+ * expressed without per-device storage, which the SDK does not have.
10
+ */
11
+ import { defineSettings } from "@getpaseo/plugin";
12
+ import { z } from "zod";
13
+
14
+ export const RATE_OPTIONS = ["0.8", "1", "1.2", "1.5"] as const;
15
+ export type RateOption = (typeof RATE_OPTIONS)[number];
16
+
17
+ /**
18
+ * Where the voice comes from. `say` has the daemon Mac render the sentence
19
+ * with its own voices and the app play the audio; `web` is the browser's own
20
+ * speech synthesis, which every web client has but which sounds worse. `say`
21
+ * falls back to `web` when the daemon is not a Mac or the render fails.
22
+ */
23
+ export const SPEECH_ENGINES = ["say", "web"] as const;
24
+ export type SpeechEngine = (typeof SPEECH_ENGINES)[number];
25
+
26
+ export const speechSettings = defineSettings({
27
+ id: "speech",
28
+ scope: "host",
29
+ version: 1,
30
+ schema: z.object({
31
+ /** The master switch. Off means nothing is spoken or vibrated anywhere. */
32
+ enabled: z.boolean().default(true),
33
+ /** The Electron desktop app, which can speak without a click. */
34
+ speakOnDesktop: z.boolean().default(true),
35
+ /** A browser tab, which speaks only after the page has been tapped once. */
36
+ speakInBrowser: z.boolean().default(true),
37
+ /** Phones cannot speak from plugin code; a short buzz is the most they can do. */
38
+ vibrateOnMobile: z.boolean().default(false),
39
+ engine: z.enum(SPEECH_ENGINES).default("say"),
40
+ /** A `say` voice on the daemon Mac by name, or empty for its default. */
41
+ sayVoice: z.string().default(""),
42
+ /** A browser voice by name, or empty for the platform default. Used by the `web` engine. */
43
+ voice: z.string().default(""),
44
+ /** Speech rate as a multiplier; kept as a string because it is picked from a list. */
45
+ rate: z.enum(RATE_OPTIONS).default("1"),
46
+ }),
47
+ });
48
+
49
+ export type SpeechSettings = z.infer<typeof speechSettings.schema>;
50
+
51
+ export const DEFAULT_SPEECH: SpeechSettings = {
52
+ enabled: true,
53
+ speakOnDesktop: true,
54
+ speakInBrowser: true,
55
+ vibrateOnMobile: false,
56
+ engine: "say",
57
+ sayVoice: "",
58
+ voice: "",
59
+ rate: "1",
60
+ };
@@ -0,0 +1,32 @@
1
+ /**
2
+ * The summary card Herald puts in an agent's transcript. The daemon appends
3
+ * it (`server/card.ts`), the app draws it (`client/timeline-card.tsx`), and
4
+ * this `kind`/`version` pair is the only thing tying the two together — a
5
+ * mismatch is not a compile error, it is a row that renders as unavailable.
6
+ */
7
+ import { z } from "zod";
8
+
9
+ import { AttentionReasonSchema, SummaryStateSchema } from "./herald";
10
+
11
+ /** Unique within this plugin; the host scopes it by plugin id. */
12
+ export const HERALD_CARD_KIND = "herald-summary";
13
+
14
+ /** Bump when `HeraldCardSchema` changes shape. */
15
+ export const HERALD_CARD_VERSION = 1;
16
+
17
+ export const HeraldCardSchema = z.object({
18
+ eventId: z.string(),
19
+ reason: AttentionReasonSchema,
20
+ /** What the work is called: the agent's title if it has one, else the workspace's. */
21
+ name: z.string().nullable(),
22
+ headline: z.string(),
23
+ detail: z.string().nullable(),
24
+ summary: SummaryStateSchema,
25
+ /**
26
+ * The agent carried on after the turn this describes, so the completion was
27
+ * not one. The row cannot be deleted — the host has append only, where the
28
+ * same id replaces — so it is replaced by this and drawn as nothing.
29
+ */
30
+ superseded: z.boolean().default(false),
31
+ });
32
+ export type HeraldCard = z.infer<typeof HeraldCardSchema>;