@gpambrozio/paseo-herald 0.4.0 → 0.5.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 CHANGED
@@ -7,6 +7,41 @@ 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.1] — 2026-09-27
11
+
12
+ ### Changed
13
+
14
+ - **Removing Herald no longer deletes its settings and its list.** They used to sit inside the folder
15
+ Paseo installs the plugin into, which Paseo deletes when you remove the plugin. They now live in
16
+ `~/.paseo/plugin-data/herald/`, and Herald moves them there the first time it starts.
17
+
18
+ ### Fixed
19
+
20
+ - **Herald cleans up its summary helpers again on a password-protected Paseo.** Herald removes the
21
+ helper agents it uses to write each announcement, and it did that with whichever `paseo` command
22
+ it found first, which could be an older copy unable to reach Paseo 0.10. The helpers then piled
23
+ up in your agent list. Herald now uses the command that came with the running Paseo first.
24
+ - **Herald notices an agent waiting for you within a moment again.** Since Paseo 0.9, Herald had
25
+ stopped hearing Paseo's live agent updates, so it only found out on its regular check every ten
26
+ seconds: announcements came up to ten seconds late, and the Herald panel was just as slow to add
27
+ or clear an agent. Nothing was missed, only delayed. Herald now listens to Paseo's agent updates
28
+ again, on both the announcements and the panel.
29
+
30
+ ## [0.5.0] — 2026-09-23
31
+
32
+ ### Changed
33
+
34
+ - **Herald no longer announces agents that another agent started.** A subagent, or a worker a
35
+ FirstMate first mate sent off, reports to the agent that started it, and Paseo tells that agent
36
+ when it finishes, fails or needs your permission. You now hear that agent's announcement, in its
37
+ words, instead of both. These agents still appear in the Herald panel, without a spoken summary.
38
+ To hear them as before, turn on *Agents started by another agent* in Herald's settings.
39
+ - **Some of those agents' news is not spoken by anyone.** Paseo tells the starting agent only about
40
+ the task it handed over. So when you send a prompt yourself to an agent whose first task is done,
41
+ or when an agent was started without asking to be told when it finishes, its questions and
42
+ results stay in the Herald panel and are not spoken. Turn on *Agents started by another agent* if
43
+ you would rather hear them.
44
+
10
45
  ## [0.4.0] — 2026-09-22
11
46
 
12
47
  ### Added
package/README.md CHANGED
@@ -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
 
@@ -0,0 +1,81 @@
1
+ /**
2
+ * Hearing Paseo's agent stream at all.
3
+ *
4
+ * Since Paseo 0.9, `paseo.agents.subscribe()` only adds a local listener to
5
+ * observations the same API instance opened with `agents.list({ subscribe })`,
6
+ * and every plugin runtime gets an API instance of its own — so a bare
7
+ * `subscribe()` hears nothing, ever. This opens that observation.
8
+ *
9
+ * Herald only takes the stream as a nudge to poll sooner; what is listed comes
10
+ * from its own polls. So the snapshot is ignored and asked for one agent long:
11
+ * the daemon filters an observation's updates by its `filter`, not by the page,
12
+ * so every agent's changes still arrive.
13
+ *
14
+ * Paseo re-requests an observation after a reconnect on its own, but releases
15
+ * one whose request fails, silently; that is caught through `error` and the
16
+ * observation is reopened with backoff rather than left deaf.
17
+ */
18
+ import type { PluginClientContext } from "@getpaseo/plugin/client";
19
+
20
+ type Paseo = PluginClientContext["paseo"];
21
+ export type AgentUpdate = Parameters<Parameters<Paseo["agents"]["subscribe"]>[0]>[0];
22
+ type AgentObservation = Awaited<ReturnType<typeof openObservation>>["subscription"];
23
+
24
+ const RETRY_MIN_MS = 2_000;
25
+ const RETRY_MAX_MS = 60_000;
26
+
27
+ function openObservation(paseo: Paseo, signal: AbortSignal) {
28
+ return paseo.agents.list({ subscribe: {}, page: { limit: 1 }, signal });
29
+ }
30
+
31
+ /**
32
+ * Calls `onUpdate` for every agent update the daemon sends, for as long as the
33
+ * returned cleanup has not run. The cleanup releases the observation.
34
+ */
35
+ export function watchAgents(paseo: Paseo, onUpdate: (update: AgentUpdate) => void): () => void {
36
+ const lifetime = new AbortController();
37
+ let observation: AgentObservation | null = null;
38
+ let retry: ReturnType<typeof setTimeout> | null = null;
39
+ let retryDelay = RETRY_MIN_MS;
40
+
41
+ function reopen(error: unknown): void {
42
+ observation = null;
43
+ if (lifetime.signal.aborted || retry !== null) return;
44
+ console.warn("[herald] the agent stream failed; reopening", error);
45
+ retry = setTimeout(() => {
46
+ retry = null;
47
+ open();
48
+ }, retryDelay);
49
+ retryDelay = Math.min(retryDelay * 2, RETRY_MAX_MS);
50
+ }
51
+
52
+ function open(): void {
53
+ openObservation(paseo, lifetime.signal)
54
+ .then(({ subscription }) => {
55
+ if (lifetime.signal.aborted) {
56
+ void subscription.release().catch(() => undefined);
57
+ return;
58
+ }
59
+ observation = subscription;
60
+ subscription.subscribe({
61
+ snapshot() {
62
+ retryDelay = RETRY_MIN_MS;
63
+ },
64
+ update(message) {
65
+ if (message.type === "agent_update") onUpdate(message.payload as AgentUpdate);
66
+ },
67
+ error: reopen,
68
+ });
69
+ })
70
+ .catch(reopen);
71
+ }
72
+
73
+ open();
74
+ return () => {
75
+ lifetime.abort();
76
+ if (retry !== null) clearTimeout(retry);
77
+ retry = null;
78
+ void observation?.release().catch(() => undefined);
79
+ observation = null;
80
+ };
81
+ }
@@ -17,6 +17,7 @@ import type { PluginClientContext } from "@getpaseo/plugin/client";
17
17
 
18
18
  import { listAttention, renderSpeech, type AttentionEntry } from "../shared/herald";
19
19
  import { DEFAULT_SPEECH, speechSettings, type SpeechSettings } from "../shared/settings";
20
+ import { watchAgents } from "./agents";
20
21
  import {
21
22
  canPlayAudio,
22
23
  canSpeak,
@@ -236,7 +237,7 @@ export function startAnnouncer(client: PluginClientContext): Announcer {
236
237
 
237
238
  // Paseo's own stream says an agent needs attention before the summary is
238
239
  // ready; use it to start polling quickly rather than waiting for the tick.
239
- const unsubscribe = client.paseo.agents.subscribe((update) => {
240
+ const unwatch = watchAgents(client.paseo, (update) => {
240
241
  if (update.kind === "upsert" && update.agent.requiresAttention) schedule(BUSY_POLL_MS / 2);
241
242
  });
242
243
 
@@ -244,7 +245,7 @@ export function startAnnouncer(client: PluginClientContext): Announcer {
244
245
  stop() {
245
246
  stopped = true;
246
247
  if (timer !== null) clearTimeout(timer);
247
- unsubscribe();
248
+ unwatch();
248
249
  // A plugin reload starts the replacement announcer at once, so whatever
249
250
  // this one was saying has to stop or the two talk over each other.
250
251
  stopSpeaking();
package/client/herald.tsx CHANGED
@@ -19,6 +19,7 @@ import { type ReactElement, useCallback, useEffect, useMemo, useRef, useState }
19
19
  import { ActivityIndicator, Pressable, ScrollView, Text, View } from "react-native";
20
20
 
21
21
  import { listAttention, type AttentionEntry, type AttentionReason } from "../shared/herald";
22
+ import { watchAgents } from "./agents";
22
23
  import { getAnnouncer, isMutedHere, setMutedHere, speechText } from "./announcer";
23
24
  import { canPlaySpeech, speechPlatform } from "./web";
24
25
 
@@ -456,17 +457,23 @@ export function HeraldSurface(props: PluginSurfaceProps) {
456
457
  useEffect(() => {
457
458
  void refresh();
458
459
  const timer = setInterval(() => void refresh(), pending ? BUSY_REFRESH_MS : IDLE_REFRESH_MS);
460
+ return () => {
461
+ clearInterval(timer);
462
+ };
463
+ }, [refresh, pending]);
464
+ // Its own effect, so the observation is not closed and reopened every time
465
+ // `pending` flips the poll's pace.
466
+ useEffect(() => {
459
467
  let debounce: ReturnType<typeof setTimeout> | null = null;
460
- const unsubscribe = paseo.agents.subscribe(() => {
468
+ const unwatch = watchAgents(paseo, () => {
461
469
  if (debounce !== null) clearTimeout(debounce);
462
470
  debounce = setTimeout(() => void refresh(), 400);
463
471
  });
464
472
  return () => {
465
- clearInterval(timer);
466
473
  if (debounce !== null) clearTimeout(debounce);
467
- unsubscribe();
474
+ unwatch();
468
475
  };
469
- }, [refresh, pending, paseo]);
476
+ }, [refresh, paseo]);
470
477
 
471
478
  const openAgent = props.navigation?.openAgent;
472
479
  const onOpen = useMemo(
@@ -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/index.server.ts CHANGED
@@ -1,9 +1,9 @@
1
- import { join } from "node:path";
2
1
 
3
2
  import type { PluginServerContext } from "@getpaseo/plugin/server";
4
3
 
5
4
  import { sweepHelpers } from "./server/cleanup";
6
- import { pluginDir, readHeraldConfig, writeHeraldConfig } from "./server/config";
5
+ import { readHeraldConfig, writeHeraldConfig } from "./server/config";
6
+ import { dataPath, migrateLegacyData } from "./server/data-dir";
7
7
  import { registerHooks } from "./server/hooks";
8
8
  import { Liveness } from "./server/liveness";
9
9
  import { listSayVoices, renderWithSay, sayAvailable } from "./server/say";
@@ -23,7 +23,8 @@ import { speechSettings } from "./shared/settings";
23
23
  const SWEEP_DELAY_MS = 30_000;
24
24
 
25
25
  export default function contribute(server: PluginServerContext) {
26
- const store = new AttentionStore(join(pluginDir(), "attention.json"));
26
+ migrateLegacyData(["config.json", "attention.json"]);
27
+ const store = new AttentionStore(dataPath("attention.json"));
27
28
  // Not awaited, because a contribution registers its handlers synchronously —
28
29
  // it returns a cleanup, not a promise. Events therefore arrive *during* this
29
30
  // read, so the store merges rather than overwrites: see `touched` there.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gpambrozio/paseo-herald",
3
- "version": "0.4.0",
3
+ "version": "0.5.1",
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",
package/server/cleanup.ts CHANGED
@@ -20,7 +20,7 @@ import { access, constants } from "node:fs/promises";
20
20
  import { homedir } from "node:os";
21
21
  import { delimiter, join } from "node:path";
22
22
 
23
- import { paseoHome } from "./config";
23
+ import { paseoHome } from "./data-dir";
24
24
 
25
25
  /** Stamped on every helper at creation, and the only thing a sweep goes by. */
26
26
  export const HELPER_LABEL_KEY = "herald.role";
@@ -49,10 +49,20 @@ export interface CliResult {
49
49
 
50
50
  let cliLookup: Promise<string | null> | null = null;
51
51
 
52
- async function findCli(): Promise<string | null> {
53
- const onPath = (process.env.PATH ?? "").split(delimiter).filter((dir) => dir !== "");
54
- for (const dir of [...onPath, join(homedir(), ".local", "bin"), ...EXTRA_CLI_DIRS]) {
55
- const candidate = join(dir, "paseo");
52
+ /**
53
+ * The daemon hands its plugins `PASEO_CLI`, the CLI it shipped with, which is
54
+ * the one that surely speaks its protocol — an older standalone `paseo` first
55
+ * on `PATH` may not reach a password-protected daemon at all. `PATH` and the
56
+ * usual install directories are the fallback for a daemon that does not.
57
+ */
58
+ export async function findCli(env: NodeJS.ProcessEnv = process.env): Promise<string | null> {
59
+ const onPath = (env.PATH ?? "").split(delimiter).filter((dir) => dir !== "");
60
+ const shipped = env.PASEO_CLI?.trim();
61
+ const candidates = [
62
+ ...(shipped === undefined || shipped === "" ? [] : [shipped]),
63
+ ...[...onPath, join(homedir(), ".local", "bin"), ...EXTRA_CLI_DIRS].map((dir) => join(dir, "paseo")),
64
+ ];
65
+ for (const candidate of candidates) {
56
66
  try {
57
67
  await access(candidate, constants.X_OK);
58
68
  return candidate;
package/server/config.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * The daemon's own file: `$PASEO_HOME/plugins/herald/config.json`. It holds
2
+ * The daemon's own file: `$PASEO_HOME/plugin-data/herald/config.json`. It holds
3
3
  * what the hooks act on — which events get a summary and which model writes
4
4
  * it — and nothing the app only draws.
5
5
  *
@@ -7,21 +7,13 @@
7
7
  * to take effect on the next event, and the file is a few hundred bytes.
8
8
  */
9
9
  import { mkdir, readFile, writeFile } from "node:fs/promises";
10
- import { homedir } from "node:os";
11
- import { dirname, join } from "node:path";
10
+ import { dirname } from "node:path";
12
11
 
13
12
  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
- }
13
+ import { dataPath } from "./data-dir";
22
14
 
23
15
  function configPath(): string {
24
- return join(pluginDir(), "config.json");
16
+ return dataPath("config.json");
25
17
  }
26
18
 
27
19
  /**
@@ -0,0 +1,153 @@
1
+ /**
2
+ * Where this plugin keeps its own files: `$PASEO_HOME/plugin-data/herald/`.
3
+ *
4
+ * They used to live in `$PASEO_HOME/plugins/herald/`, which is also where Paseo
5
+ * installs an npm or Git plugin, and `paseo plugin remove` deletes that
6
+ * directory whole. Paseo never touches `plugin-data/`. `migrateLegacyData`
7
+ * carries the files over by name — never the directory itself, which on a
8
+ * managed install also holds Paseo's version directories.
9
+ *
10
+ * Every plugin in this repository carries its own copy of this module.
11
+ */
12
+ import { randomUUID } from "node:crypto";
13
+ import { cpSync, linkSync, lstatSync, mkdirSync, renameSync, rmSync } from "node:fs";
14
+ import { homedir } from "node:os";
15
+ import { dirname, join } from "node:path";
16
+
17
+ export const PLUGIN_ID = "herald";
18
+
19
+ export function paseoHome(): string {
20
+ return process.env.PASEO_HOME ?? join(homedir(), ".paseo");
21
+ }
22
+
23
+ export function pluginDir(): string {
24
+ return join(paseoHome(), "plugin-data", PLUGIN_ID);
25
+ }
26
+
27
+ /** Where the files used to live; read only to move them out. */
28
+ export function legacyPluginDir(): string {
29
+ return join(paseoHome(), "plugins", PLUGIN_ID);
30
+ }
31
+
32
+ /**
33
+ * Where one entry is read and written: the new directory when it has it or
34
+ * when neither does, the legacy one when only that has it — which is only
35
+ * after its move failed. So the copy in use is always the one the next start
36
+ * keeps: a file both have is served from the new place, whose copy wins, and
37
+ * a file whose move failed is edited where it is and carried over next time,
38
+ * edits and all.
39
+ */
40
+ export function dataPath(entry: string): string {
41
+ const current = join(pluginDir(), entry);
42
+ const legacy = join(legacyPluginDir(), entry);
43
+ return !exists(current) && exists(legacy) ? legacy : current;
44
+ }
45
+
46
+ /**
47
+ * - `moved`: it was only in the legacy directory, and now it is only in the new one.
48
+ * - `absent`: the legacy directory does not have it.
49
+ * - `kept`: both have it; the new one wins and the legacy copy is left alone.
50
+ * - `failed`: logged, and the legacy copy is where it was, to be tried again on the next start.
51
+ */
52
+ export type MigrationOutcome = "moved" | "absent" | "kept" | "failed";
53
+
54
+ function exists(path: string): boolean {
55
+ try {
56
+ lstatSync(path);
57
+ return true;
58
+ } catch (error) {
59
+ if (errorCode(error) === "ENOENT") return false;
60
+ throw error;
61
+ }
62
+ }
63
+
64
+ function errorCode(error: unknown): string | undefined {
65
+ return (error as NodeJS.ErrnoException).code;
66
+ }
67
+
68
+ /**
69
+ * Moves each named entry — a file or a directory, or a path inside one — from
70
+ * the legacy directory into the new one, unless the new one already has it.
71
+ * One entry failing does not stop the others; `dataPath` serves it from where
72
+ * it is until a later start moves it.
73
+ *
74
+ * A file is hard-linked into place and then unlinked from the old place: the
75
+ * link refuses to replace a file that appeared in the meantime, so a writer
76
+ * racing the move is never overwritten. Across filesystems, a copy under a
77
+ * temporary name is linked into place the same way. A directory is renamed.
78
+ *
79
+ * Synchronous on purpose: the server entry calls it before binding a handler,
80
+ * so no handler writes during the move.
81
+ */
82
+ export function migrateLegacyData(entries: readonly string[]): Record<string, MigrationOutcome> {
83
+ const outcomes: Record<string, MigrationOutcome> = {};
84
+ for (const entry of entries) {
85
+ outcomes[entry] = migrateEntry(join(legacyPluginDir(), entry), join(pluginDir(), entry));
86
+ }
87
+ return outcomes;
88
+ }
89
+
90
+ function migrateEntry(from: string, to: string): MigrationOutcome {
91
+ try {
92
+ if (!exists(from)) return "absent";
93
+ if (exists(to)) return "kept";
94
+ mkdirSync(dirname(to), { recursive: true });
95
+ const moved = lstatSync(from).isDirectory() ? moveDirectory(from, to) : moveFile(from, to);
96
+ if (!moved) return "kept";
97
+ console.log(`[${PLUGIN_ID}] moved ${from} to ${to}`);
98
+ return "moved";
99
+ } catch (error) {
100
+ console.error(`[${PLUGIN_ID}] could not move ${from} to ${to}; it stays where it is:`, error);
101
+ return "failed";
102
+ }
103
+ }
104
+
105
+ /** False when `to` appeared before the link could land; `from` is then untouched. */
106
+ function moveFile(from: string, to: string): boolean {
107
+ try {
108
+ linkSync(from, to);
109
+ } catch (error) {
110
+ if (errorCode(error) === "EEXIST") return false;
111
+ if (errorCode(error) !== "EXDEV") throw error;
112
+ const temporary = `${to}.${randomUUID()}.tmp`;
113
+ try {
114
+ cpSync(from, temporary, { errorOnExist: true, force: false, preserveTimestamps: true });
115
+ linkSync(temporary, to);
116
+ } catch (copyError) {
117
+ if (errorCode(copyError) === "EEXIST") return false;
118
+ throw copyError;
119
+ } finally {
120
+ rmSync(temporary, { force: true });
121
+ }
122
+ }
123
+ removeOriginal(from, to);
124
+ return true;
125
+ }
126
+
127
+ function moveDirectory(from: string, to: string): boolean {
128
+ try {
129
+ renameSync(from, to);
130
+ return true;
131
+ } catch (error) {
132
+ if (errorCode(error) !== "EXDEV") throw error;
133
+ }
134
+ const temporary = `${to}.${randomUUID()}.tmp`;
135
+ try {
136
+ cpSync(from, temporary, { recursive: true, errorOnExist: true, force: false, preserveTimestamps: true, verbatimSymlinks: true });
137
+ if (exists(to)) return false;
138
+ renameSync(temporary, to);
139
+ } finally {
140
+ rmSync(temporary, { recursive: true, force: true });
141
+ }
142
+ removeOriginal(from, to);
143
+ return true;
144
+ }
145
+
146
+ function removeOriginal(from: string, to: string): void {
147
+ try {
148
+ rmSync(from, { recursive: true, force: true });
149
+ } catch (error) {
150
+ // Both copies exist now, and the new one wins from here on.
151
+ console.error(`[${PLUGIN_ID}] moved ${from} to ${to} but could not remove the original:`, error);
152
+ }
153
+ }
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