@gpambrozio/paseo-herald 0.3.0 → 0.5.0

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 CHANGED
@@ -7,6 +7,33 @@ follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Every version
7
7
  as `@gpambrozio/paseo-herald` and tagged here, so a version is something to install and a line to
8
8
  read before you move.
9
9
 
10
+ ## [0.5.0] — 2026-09-23
11
+
12
+ ### Changed
13
+
14
+ - **Herald no longer announces agents that another agent started.** A subagent, or a worker a
15
+ FirstMate first mate sent off, reports to the agent that started it, and Paseo tells that agent
16
+ when it finishes, fails or needs your permission. You now hear that agent's announcement, in its
17
+ words, instead of both. These agents still appear in the Herald panel, without a spoken summary.
18
+ To hear them as before, turn on *Agents started by another agent* in Herald's settings.
19
+ - **Some of those agents' news is not spoken by anyone.** Paseo tells the starting agent only about
20
+ the task it handed over. So when you send a prompt yourself to an agent whose first task is done,
21
+ or when an agent was started without asking to be told when it finishes, its questions and
22
+ results stay in the Herald panel and are not spoken. Turn on *Agents started by another agent* if
23
+ you would rather hear them.
24
+
25
+ ## [0.4.0] — 2026-09-22
26
+
27
+ ### Added
28
+
29
+ - **A one-line description of the plugin**, shown next to it in Paseo's plugins list, so it is
30
+ clear what it does without opening it.
31
+
32
+ ### Changed
33
+
34
+ - **Paseo 0.9 or newer is now required.** On 0.8 this version will not load. Staying on 0.8 means
35
+ staying on the previous release, which keeps working.
36
+
10
37
  ## [0.3.0] — 2026-09-21
11
38
 
12
39
  ### Added
package/README.md CHANGED
@@ -25,7 +25,7 @@ composer sits below it.](docs/timeline-card.png)
25
25
 
26
26
  ## What you need
27
27
 
28
- - Paseo **0.8.0 or newer**, on the daemon and on the device running the app.
28
+ - Paseo **0.9.0 or newer**, on the daemon and on the device running the app.
29
29
  - Speech comes out of the device running the Paseo app, not the daemon machine. The voice, by
30
30
  default, is the daemon Mac's: it renders each sentence with `say` and the app plays the audio, so
31
31
  you hear the Mac's voices rather than a browser's. If the daemon is not a Mac, the browser's own
@@ -46,7 +46,7 @@ paseo plugin install npm:@gpambrozio/paseo-herald
46
46
  ```
47
47
 
48
48
  That is the shortest route on **Paseo 0.9 or newer**, which installs plugins straight from npm; add
49
- `@<version>` to pin one. On 0.8, install from this repository instead:
49
+ `@<version>` to pin one. On 0.8, install the last release that supported it from this repository instead:
50
50
 
51
51
  ```bash
52
52
  paseo plugin add gpambrozio/paseo-plugins --path herald
@@ -70,6 +70,14 @@ Center, or the settings screen itself.
70
70
  sessions are deleted, and which kinds of event are announced: questions, plan approvals, tool
71
71
  permissions, finished turns, errors. A kind that is switched off still appears in the panel,
72
72
  without a summary and without being spoken.
73
+ - **Agents started by another agent** — off by default. A subagent, or a worker a
74
+ FirstMate first mate dispatched, reports to the agent that started it: Paseo tells
75
+ that agent when it finishes, fails or needs a permission, and you hear the parent's announcement,
76
+ in its words, rather than two. Such an agent is still listed in the panel, like a switched-off
77
+ kind. Turn it on to hear both. Paseo tells the parent only about the task it handed over, so
78
+ while this is off two things go unannounced by anyone: anything that agent does after its first
79
+ task has finished or failed — a prompt you send it yourself, say — and every agent started
80
+ without asking to be told when it finishes.
73
81
 
74
82
  ### The prompt
75
83
 
@@ -419,6 +419,15 @@ export function HeraldSettingsScreen(props: PluginSurfaceProps) {
419
419
  }}
420
420
  />
421
421
  ))}
422
+ <SettingsSwitch
423
+ label="Agents started by another agent"
424
+ hint="Subagents and FirstMate workers report to the agent that started them, and Paseo tells it when they finish, fail or need a permission, so you hear that agent instead. Off also silences what that agent is never told: their later turns you start yourself, and any started without a finish notification. On announces both."
425
+ value={config?.subagents.announce ?? false}
426
+ disabled={config === null}
427
+ onValueChange={(value) => {
428
+ if (config !== null) void saveConfig({ ...config, subagents: { ...config.subagents, announce: value } });
429
+ }}
430
+ />
422
431
  </SettingsSection>
423
432
  </SettingsGroup>
424
433
  <View style={{ height: 24 }} />
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gpambrozio/paseo-herald",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "description": "Paseo plugin: speaks one sentence when an agent needs you, and lists everything waiting in a sidebar panel",
5
5
  "license": "MIT",
6
6
  "homepage": "https://github.com/gpambrozio/paseo-plugins/tree/main/herald",
@@ -29,9 +29,9 @@
29
29
  "test": "vitest run --passWithNoTests"
30
30
  },
31
31
  "devDependencies": {
32
- "@getpaseo/client": "0.8.0",
33
- "@getpaseo/plugin": "0.8.0",
34
- "@getpaseo/protocol": "0.8.0",
32
+ "@getpaseo/client": "0.9.0",
33
+ "@getpaseo/plugin": "0.9.0",
34
+ "@getpaseo/protocol": "0.9.0",
35
35
  "@types/node": "^26.5.0",
36
36
  "@types/react": "~19.2.0",
37
37
  "react": "19.1.0",
package/paseo-plugin.json CHANGED
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "id": "herald",
3
+ "description": "Speaks one sentence when an agent needs you, and lists what is waiting",
3
4
  "requirements": {
4
- "paseo": ">=0.8.0"
5
+ "paseo": ">=0.9.0"
5
6
  }
6
7
  }
package/server/hooks.ts CHANGED
@@ -73,6 +73,23 @@ export const TURN_REPEAT_WINDOW_MS = 15_000;
73
73
  */
74
74
  export const INTERRUPT_GRACE_MS = 10_000;
75
75
 
76
+ /**
77
+ * Whether an event gets a summary, a transcript card and a voice; otherwise it
78
+ * is only listed. An agent another agent started reports to that agent — Paseo
79
+ * tells the parent when it finishes, fails or asks for a permission — so unless
80
+ * the user has asked for subagents too, the parent's announcement is the one
81
+ * they hear. Herald's own helpers have a parent as well, but never get here.
82
+ *
83
+ * A parent is not a subscription, and nothing in the hook payload says which
84
+ * one this is: Paseo stops telling the parent after the child's first finish or
85
+ * error, and never tells it about a child started without `notifyOnFinish`. Both
86
+ * are muted anyway — a known gap, see "Agents another agent started" in AGENTS.md.
87
+ */
88
+ export function isAnnounced(agent: PluginHookAgent, reason: AttentionReason, config: HeraldConfig): boolean {
89
+ if (agent.parentAgentId !== null && !config.subagents.announce) return false;
90
+ return config.announce[announceKeyFor(reason)];
91
+ }
92
+
76
93
  export function registerHooks(server: PluginLifecycleRegistration, deps: HookDeps): () => void {
77
94
  const now = deps.now ?? (() => new Date());
78
95
  const maxConcurrent = deps.maxConcurrent ?? 2;
@@ -205,8 +222,9 @@ export function registerHooks(server: PluginLifecycleRegistration, deps: HookDep
205
222
  headline,
206
223
  detail,
207
224
  };
208
- if (!config.announce[announceKeyFor(reason)]) {
209
- // Switched off: listed in the panel, no summary, no card in the transcript.
225
+ if (!isAnnounced(agent, reason, config)) {
226
+ // Switched off, or a subagent its parent speaks for: listed in the panel,
227
+ // no summary, no card in the transcript.
210
228
  deps.store.upsert({ ...base, summary: { status: "off", fallback: fallbackSpeech(base) } });
211
229
  return;
212
230
  }
package/shared/herald.ts CHANGED
@@ -191,6 +191,21 @@ export const DEFAULT_CLEANUP = {
191
191
  deleteHelpers: true,
192
192
  };
193
193
 
194
+ /**
195
+ * Whether an agent another agent started is announced. Paseo records the one
196
+ * that started it as its parent (`paseo.parent-agent-id`) and tells the parent
197
+ * when it finishes, fails or asks for a permission, so the parent's own
198
+ * announcement already covers it — a FirstMate worker's news reaches the user
199
+ * in the first mate's words. Off by default; on announces both.
200
+ *
201
+ * Off also mutes what the parent is never told: the child's later turns once its
202
+ * first one has finished or failed, and a child started without a finish
203
+ * notification. Those are listed in the panel and spoken by nobody.
204
+ */
205
+ export const DEFAULT_SUBAGENTS = {
206
+ announce: false,
207
+ };
208
+
194
209
  export const DEFAULT_ANNOUNCE: Record<AnnounceKey, boolean> = {
195
210
  question: true,
196
211
  plan: true,
@@ -223,6 +238,11 @@ export const HeraldConfigSchema = z.object({
223
238
  error: z.boolean().default(true),
224
239
  })
225
240
  .default(DEFAULT_ANNOUNCE),
241
+ subagents: z
242
+ .object({
243
+ announce: z.boolean().default(DEFAULT_SUBAGENTS.announce),
244
+ })
245
+ .default(DEFAULT_SUBAGENTS),
226
246
  cleanup: z
227
247
  .object({
228
248
  deleteHelpers: z.boolean().default(DEFAULT_CLEANUP.deleteHelpers),
@@ -234,6 +254,7 @@ export type HeraldConfig = z.infer<typeof HeraldConfigSchema>;
234
254
  export const DEFAULT_CONFIG: HeraldConfig = {
235
255
  summarizer: { ...DEFAULT_SUMMARIZER },
236
256
  announce: { ...DEFAULT_ANNOUNCE },
257
+ subagents: { ...DEFAULT_SUBAGENTS },
237
258
  cleanup: { ...DEFAULT_CLEANUP },
238
259
  };
239
260