@gpambrozio/paseo-herald 0.2.4 → 0.3.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,25 @@ 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.3.0] — 2026-09-21
11
+
12
+ ### Added
13
+
14
+ - **Summary helpers no longer pile up in your history.** Each summary is written by a short-lived
15
+ helper agent, and every one of them used to stay behind as a session you never asked for. Herald
16
+ now deletes each helper the moment its sentence is written, and clears any that were left over
17
+ shortly after the daemon starts — including everything that accumulated before this release. A
18
+ summary still being written is never touched.
19
+ - **A switch to keep them anyway**, under Settings › Plugins › Herald › Summaries. Turn *Delete the
20
+ helper when it is done* off when a summary comes out wrong and you want to read what the helper
21
+ was actually asked. It is on by default.
22
+
23
+ ### Changed
24
+
25
+ - Herald now needs the `paseo` command on the daemon's `PATH`, which is where it normally is. It is
26
+ used only to delete the helpers; without it they simply pile up as before, and nothing else
27
+ changes.
28
+
10
29
  ## [0.2.4] — 2026-09-19
11
30
 
12
31
  ### Fixed
package/README.md CHANGED
@@ -35,7 +35,9 @@ composer sits below it.](docs/timeline-card.png)
35
35
  carry the text there.
36
36
  - Summaries are written by a helper agent through whichever provider you pick, Claude Haiku 4.5 by
37
37
  default. Each event is one short turn of that model; the helper appears briefly under the agent it
38
- describes and is archived when it finishes.
38
+ describes and is deleted once its sentence is written, so it leaves nothing in your history.
39
+ - The `paseo` command, on the daemon's `PATH`. It is what deletes the helpers, and it is the only
40
+ thing Herald needs it for — without it, helper sessions simply pile up.
39
41
 
40
42
  ## Install
41
43
 
@@ -64,9 +66,10 @@ Center, or the settings screen itself.
64
66
  Accessibility › Spoken Content. These are shared by every device connected to the daemon, and each
65
67
  device follows its own switch. *Mute here* in the panel silences just the device you are on until
66
68
  the app restarts.
67
- - **Summaries** — the model that writes them, the prompt they are written from, and which kinds of
68
- event are announced: questions, plan approvals, tool permissions, finished turns, errors. A kind
69
- that is switched off still appears in the panel, without a summary and without being spoken.
69
+ - **Summaries** — the model that writes them, the prompt they are written from, whether the helper
70
+ sessions are deleted, and which kinds of event are announced: questions, plan approvals, tool
71
+ permissions, finished turns, errors. A kind that is switched off still appears in the panel,
72
+ without a summary and without being spoken.
70
73
 
71
74
  ### The prompt
72
75
 
@@ -94,6 +97,16 @@ The default prompt ends by asking for a small JSON object, which is what Herald
94
97
  out of. You can drop that — Herald then speaks whatever the model replies, trimmed to the first 45
95
98
  words — but the result is less predictable, so the editor says so.
96
99
 
100
+ ## Helper sessions
101
+
102
+ A helper agent is a session like any other, so left alone every summary would put one in your
103
+ history. Herald deletes each one the moment its sentence is written, and shortly after the daemon
104
+ starts it clears any that were left over — the ones from before you upgraded, and any orphaned by a
105
+ plugin reload or a daemon that stopped mid-summary. A summary still being written is never touched.
106
+
107
+ Turn *Delete the helper when it is done* off under **Summaries** to keep them instead, which is worth
108
+ doing when a summary comes out wrong and you want to read what the helper was actually asked.
109
+
97
110
  ## What the helper sees
98
111
 
99
112
  With the default prompt, for a finished turn the helper is given what the agent said after your last
@@ -342,7 +342,7 @@ export function HeraldSettingsScreen(props: PluginSurfaceProps) {
342
342
  info={
343
343
  <Text style={styles.note}>
344
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.
345
+ describes. A small, fast model is plenty for one sentence.
346
346
  </Text>
347
347
  }
348
348
  >
@@ -383,6 +383,26 @@ export function HeraldSettingsScreen(props: PluginSurfaceProps) {
383
383
  compact={layout.compact}
384
384
  />
385
385
  </SettingsSection>
386
+ <SettingsSection
387
+ title="Helper sessions"
388
+ info={
389
+ <Text style={styles.note}>
390
+ A helper agent is a session like any other, so every summary would otherwise leave one
391
+ behind in your history. Herald deletes each one as its sentence is written, and clears any
392
+ left over shortly after the daemon starts.
393
+ </Text>
394
+ }
395
+ >
396
+ <SettingsSwitch
397
+ label="Delete the helper when it is done"
398
+ hint="Off keeps every helper session, so you can read what it was asked and what it answered."
399
+ value={config?.cleanup.deleteHelpers ?? true}
400
+ disabled={config === null}
401
+ onValueChange={(value) => {
402
+ if (config !== null) void saveConfig({ ...config, cleanup: { ...config.cleanup, deleteHelpers: value } });
403
+ }}
404
+ />
405
+ </SettingsSection>
386
406
  <SettingsSection
387
407
  title="What gets announced"
388
408
  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>}
package/client/web.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  /**
2
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
3
+ * AGENTS.md allows them in. Each export declares the narrow shape of the
4
4
  * globals it uses, gates on `Platform.OS`, and gives native the alternative or
5
5
  * a no-op — so the rest of `client/` never reaches for `window` and typechecks
6
6
  * without the DOM library.
package/index.server.ts CHANGED
@@ -2,6 +2,7 @@ import { join } from "node:path";
2
2
 
3
3
  import type { PluginServerContext } from "@getpaseo/plugin/server";
4
4
 
5
+ import { sweepHelpers } from "./server/cleanup";
5
6
  import { pluginDir, readHeraldConfig, writeHeraldConfig } from "./server/config";
6
7
  import { registerHooks } from "./server/hooks";
7
8
  import { Liveness } from "./server/liveness";
@@ -11,6 +12,16 @@ import { summarize } from "./server/summarize";
11
12
  import { listAttention, listSpeechVoices, readConfig, renderSpeech, writeConfig } from "./shared/herald";
12
13
  import { speechSettings } from "./shared/settings";
13
14
 
15
+ /**
16
+ * How long after load the leftover summary helpers are swept.
17
+ *
18
+ * This plugin is loaded *by* the daemon, and the sweep talks to that daemon
19
+ * through the `paseo` CLI, which needs it to be listening. A sweep that ran the
20
+ * moment this module was evaluated would meet a daemon still starting and give
21
+ * up for the life of the process, so it waits.
22
+ */
23
+ const SWEEP_DELAY_MS = 30_000;
24
+
14
25
  export default function contribute(server: PluginServerContext) {
15
26
  const store = new AttentionStore(join(pluginDir(), "attention.json"));
16
27
  // Not awaited, because a contribution registers its handlers synchronously —
@@ -42,13 +53,35 @@ export default function contribute(server: PluginServerContext) {
42
53
  // client's `useSettings` reads and writes valid for this installation.
43
54
  server.registerSettings(speechSettings);
44
55
 
56
+ // Shared with the sweep below, which must not delete a helper still writing.
57
+ const liveHelpers = new Set<string>();
45
58
  const unregisterHooks = registerHooks(server, {
46
59
  store,
47
60
  readConfig: readHeraldConfig,
48
61
  summarize,
62
+ liveHelpers,
49
63
  });
50
64
 
65
+ // Each helper is deleted as its summary lands. This is for the ones no id
66
+ // survived for: everything from before the plugin did that, and whatever a
67
+ // reload or a stopped daemon orphaned mid-summary.
68
+ const sweep = setTimeout(() => {
69
+ void readHeraldConfig()
70
+ .then(async (config) => {
71
+ if (!config.cleanup.deleteHelpers) return;
72
+ const { deleted, failed } = await sweepHelpers({ keep: liveHelpers });
73
+ if (deleted > 0 || failed > 0) {
74
+ console.log(`[herald] deleted ${deleted} leftover summary helpers, ${failed} failed`);
75
+ }
76
+ })
77
+ .catch((error: unknown) => {
78
+ console.error("[herald] could not delete leftover summary helpers:", error);
79
+ });
80
+ }, SWEEP_DELAY_MS);
81
+ sweep.unref();
82
+
51
83
  return async () => {
84
+ clearTimeout(sweep);
52
85
  unregisterHooks();
53
86
  await store.flush();
54
87
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gpambrozio/paseo-herald",
3
- "version": "0.2.4",
3
+ "version": "0.3.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",
@@ -0,0 +1,196 @@
1
+ /**
2
+ * Putting a summary helper away for good.
3
+ *
4
+ * Every helper is a real Paseo agent, so every summary leaves a session in the
5
+ * user's history. `autoArchive` only soft-deletes it, and the plugin API has no
6
+ * hard delete — `PaseoAgentHandle` offers `archive()` and `detach()` and
7
+ * nothing else. The `paseo` CLI does, and plugin code runs unsandboxed next to
8
+ * the daemon, so that is the way in: `paseo delete <id>`, one child process per
9
+ * agent.
10
+ *
11
+ * Two callers. `server/summarize.ts` deletes each helper by id the moment it is
12
+ * done with it, which is precise and never races a summary still being written.
13
+ * `index.server.ts` runs `sweepHelpers` once a little after load, for the ones
14
+ * no id survived for: the backlog from before any of this existed, and the
15
+ * orphans a plugin reload or a stopped daemon leaves mid-summary. The sweep
16
+ * finds them by the label every helper carries.
17
+ */
18
+ import { spawn } from "node:child_process";
19
+ import { access, constants } from "node:fs/promises";
20
+ import { homedir } from "node:os";
21
+ import { delimiter, join } from "node:path";
22
+
23
+ import { paseoHome } from "./config";
24
+
25
+ /** Stamped on every helper at creation, and the only thing a sweep goes by. */
26
+ export const HELPER_LABEL_KEY = "herald.role";
27
+ export const HELPER_LABEL_VALUE = "summarizer";
28
+ export const HELPER_LABELS: Record<string, string> = { [HELPER_LABEL_KEY]: HELPER_LABEL_VALUE };
29
+
30
+ /** Where an install puts the binary, for a daemon started with a bare PATH. */
31
+ const EXTRA_CLI_DIRS = ["/usr/local/bin", "/opt/homebrew/bin"];
32
+
33
+ const LIST_TIMEOUT_MS = 20_000;
34
+ const DELETE_TIMEOUT_MS = 30_000;
35
+
36
+ /**
37
+ * `paseo ls` answers one page at a time — twenty agents, at the time of
38
+ * writing — so one pass is not the whole backlog. The sweep asks again until a
39
+ * page holds nothing it may delete, and gives up after this many passes rather
40
+ * than trusting the daemon to ever run out.
41
+ */
42
+ export const MAX_SWEEP_PASSES = 50;
43
+
44
+ export interface CliResult {
45
+ code: number | null;
46
+ stdout: string;
47
+ stderr: string;
48
+ }
49
+
50
+ let cliLookup: Promise<string | null> | null = null;
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");
56
+ try {
57
+ await access(candidate, constants.X_OK);
58
+ return candidate;
59
+ } catch {
60
+ // Not in this directory; try the next one.
61
+ }
62
+ }
63
+ return null;
64
+ }
65
+
66
+ /** The CLI's absolute path, looked up once per plugin process. */
67
+ export function paseoCli(): Promise<string | null> {
68
+ cliLookup ??= findCli();
69
+ return cliLookup;
70
+ }
71
+
72
+ function spawnCli(cli: string, args: string[], timeoutMs: number): Promise<CliResult> {
73
+ return new Promise((resolve, reject) => {
74
+ const child = spawn(cli, args, { stdio: ["ignore", "pipe", "pipe"] });
75
+ let stdout = "";
76
+ let stderr = "";
77
+ const timer = setTimeout(() => {
78
+ child.kill("SIGKILL");
79
+ reject(new Error(`paseo ${args[0] ?? ""} did not finish within ${timeoutMs / 1000} seconds`));
80
+ }, timeoutMs);
81
+ child.stdout.setEncoding("utf8").on("data", (chunk: string) => (stdout += chunk));
82
+ child.stderr.setEncoding("utf8").on("data", (chunk: string) => (stderr += chunk));
83
+ child.on("error", (error) => {
84
+ clearTimeout(timer);
85
+ reject(error);
86
+ });
87
+ child.on("close", (code) => {
88
+ clearTimeout(timer);
89
+ resolve({ code, stdout, stderr });
90
+ });
91
+ });
92
+ }
93
+
94
+ /**
95
+ * `--home` rather than the inherited `PASEO_HOME`, so the CLI always reaches
96
+ * the daemon this plugin is running inside; `--json` so a failure arrives as
97
+ * something worth putting in a log line.
98
+ */
99
+ async function runCli(args: string[], timeoutMs: number): Promise<CliResult> {
100
+ const cli = await paseoCli();
101
+ if (cli === null) {
102
+ throw new Error("The `paseo` command is not on the daemon's PATH, so summary helpers cannot be deleted.");
103
+ }
104
+ return spawnCli(cli, [...args, "--home", paseoHome(), "--json"], timeoutMs);
105
+ }
106
+
107
+ /** The CLI's complaint: the message out of its JSON error, or its first line. */
108
+ export function cliError(result: CliResult): string {
109
+ for (const stream of [result.stderr, result.stdout]) {
110
+ const text = stream.trim();
111
+ if (text === "") continue;
112
+ let parsed: unknown = null;
113
+ try {
114
+ parsed = JSON.parse(text);
115
+ } catch {
116
+ // Not JSON; the text itself is the complaint.
117
+ }
118
+ if (typeof parsed === "object" && parsed !== null) {
119
+ const error = (parsed as { error?: { message?: unknown } }).error;
120
+ if (typeof error?.message === "string" && error.message.trim() !== "") return error.message.trim();
121
+ }
122
+ return text.split("\n")[0] ?? text;
123
+ }
124
+ return `exit ${result.code}`;
125
+ }
126
+
127
+ /** The ids in one page of `paseo ls --json`, ignoring any entry without one. */
128
+ export function helperIdsIn(stdout: string): string[] {
129
+ const trimmed = stdout.trim();
130
+ if (trimmed === "") return [];
131
+ const parsed: unknown = JSON.parse(trimmed);
132
+ if (!Array.isArray(parsed)) throw new Error("`paseo ls` did not answer with a list of agents.");
133
+ return parsed.flatMap((entry: unknown) => {
134
+ const id = typeof entry === "object" && entry !== null ? (entry as { id?: unknown }).id : undefined;
135
+ return typeof id === "string" && id !== "" ? [id] : [];
136
+ });
137
+ }
138
+
139
+ /** One page of the helpers this plugin has ever created, archived ones included. */
140
+ export async function listHelperIds(): Promise<string[]> {
141
+ const result = await runCli(
142
+ ["ls", "--all", "--global", "--label", `${HELPER_LABEL_KEY}=${HELPER_LABEL_VALUE}`],
143
+ LIST_TIMEOUT_MS,
144
+ );
145
+ if (result.code !== 0) throw new Error(`\`paseo ls\` failed: ${cliError(result)}`);
146
+ return helperIdsIn(result.stdout);
147
+ }
148
+
149
+ /** Interrupts the agent if it is running, then removes it from the daemon's history. */
150
+ export async function deleteAgent(agentId: string): Promise<void> {
151
+ const result = await runCli(["delete", agentId], DELETE_TIMEOUT_MS);
152
+ if (result.code !== 0) throw new Error(`\`paseo delete\` failed: ${cliError(result)}`);
153
+ }
154
+
155
+ export interface SweepDeps {
156
+ /** Helpers a summary is still being written by. Never deleted. */
157
+ keep?: ReadonlySet<string>;
158
+ list?: () => Promise<string[]>;
159
+ remove?: (agentId: string) => Promise<void>;
160
+ }
161
+
162
+ export interface SweepResult {
163
+ deleted: number;
164
+ failed: number;
165
+ }
166
+
167
+ /**
168
+ * Deletes every helper the daemon still has, page by page.
169
+ *
170
+ * Two things end it besides running out: a page holding nothing but kept ids,
171
+ * and a pass that deleted nothing at all — without the second, a page of ids
172
+ * that all refuse to delete would be re-read until `MAX_SWEEP_PASSES`.
173
+ */
174
+ export async function sweepHelpers(deps: SweepDeps = {}): Promise<SweepResult> {
175
+ const keep = deps.keep ?? new Set<string>();
176
+ const list = deps.list ?? listHelperIds;
177
+ const remove = deps.remove ?? deleteAgent;
178
+ let deleted = 0;
179
+ let failed = 0;
180
+ for (let pass = 0; pass < MAX_SWEEP_PASSES; pass += 1) {
181
+ const ids = (await list()).filter((id) => !keep.has(id));
182
+ if (ids.length === 0) break;
183
+ const before = deleted;
184
+ for (const id of ids) {
185
+ try {
186
+ await remove(id);
187
+ deleted += 1;
188
+ } catch (error) {
189
+ failed += 1;
190
+ console.error(`[herald] could not delete summary helper ${id}:`, error);
191
+ }
192
+ }
193
+ if (deleted === before) break;
194
+ }
195
+ return { deleted, failed };
196
+ }
package/server/hooks.ts CHANGED
@@ -55,6 +55,12 @@ export interface HookDeps {
55
55
  now?: () => Date;
56
56
  /** How many helpers may be writing at once; more agents than this wait their turn. */
57
57
  maxConcurrent?: number;
58
+ /**
59
+ * Every helper this process has seen, newest last and capped. Shared with the
60
+ * load-time sweep in `index.server.ts` as the set it may not delete: the ones
61
+ * still writing a summary are by definition the most recent entries.
62
+ */
63
+ liveHelpers?: Set<string>;
58
64
  }
59
65
 
60
66
  /** A second `turn_ended` for the same turn inside this window is a repeat, not a new turn. */
@@ -97,7 +103,7 @@ export function registerHooks(server: PluginLifecycleRegistration, deps: HookDep
97
103
  // answers with may predate it.
98
104
  return generationOf(agentId) !== generation ? true : running;
99
105
  }
100
- const helpers = new Set<string>();
106
+ const helpers = deps.liveHelpers ?? new Set<string>();
101
107
  const recentTurns = new Map<string, number>();
102
108
  const interruptedAt = new Map<string, number>();
103
109
  /**
@@ -134,6 +140,20 @@ export function registerHooks(server: PluginLifecycleRegistration, deps: HookDep
134
140
  }
135
141
  }
136
142
 
143
+ /**
144
+ * An id is normally dropped when `agent.archived` arrives — but a *deleted*
145
+ * helper fires no such event, and the daemon deletes one per summary when the
146
+ * user has asked it to. So the set is capped the way `resolvedRequests` is.
147
+ * The oldest goes first, and a helper still writing is always the newest.
148
+ */
149
+ function rememberHelper(helperId: string): void {
150
+ helpers.add(helperId);
151
+ if (helpers.size > 1000) {
152
+ const oldest = helpers.values().next();
153
+ if (!oldest.done) helpers.delete(oldest.value);
154
+ }
155
+ }
156
+
137
157
  function isRepeatTurn(agentId: string, turnId: string | null): boolean {
138
158
  if (turnId === null) return false;
139
159
  const key = `${agentId}:${turnId}`;
@@ -226,7 +246,8 @@ export function registerHooks(server: PluginLifecycleRegistration, deps: HookDep
226
246
  provider: config.summarizer.provider,
227
247
  timeoutMs: config.summarizer.timeoutMs,
228
248
  prompt: config.summarizer.prompt,
229
- onHelperCreated: (helperId) => helpers.add(helperId),
249
+ deleteHelper: config.cleanup.deleteHelpers,
250
+ onHelperCreated: rememberHelper,
230
251
  },
231
252
  );
232
253
  } catch (error) {
@@ -268,7 +289,7 @@ export function registerHooks(server: PluginLifecycleRegistration, deps: HookDep
268
289
 
269
290
  const unsubscribers = [
270
291
  server.on("agent.created", (event) => {
271
- if (event.agent.title === HELPER_TITLE) helpers.add(event.agent.id);
292
+ if (event.agent.title === HELPER_TITLE) rememberHelper(event.agent.id);
272
293
  }),
273
294
 
274
295
  server.on("agent.permission_requested", async (event, context) => {
@@ -14,7 +14,7 @@
14
14
  * - types degraded → the access is `any`, no error → TS2578 "Unused
15
15
  * '@ts-expect-error' directive" → fail
16
16
  *
17
- * This replaces the throwaway file the root CLAUDE.md used to ask contributors
17
+ * This replaces the throwaway file the root AGENTS.md used to ask contributors
18
18
  * to write by hand. It is type-only, so it contributes nothing to either bundle.
19
19
  */
20
20
  import type { PaseoAgentHandle } from "@getpaseo/client";
@@ -8,9 +8,13 @@
8
8
  * this plugin's own hooks. `HELPER_TITLE` is one of the two things
9
9
  * `server/hooks.ts` uses to recognise and ignore it; the id reported through
10
10
  * `onHelperCreated` is the other.
11
+ *
12
+ * Visible also means it stays in the user's history, which is why `retire`
13
+ * deletes it outright when the config asks — see `server/cleanup.ts`.
11
14
  */
12
15
  import type { PaseoApi } from "./host-types";
13
16
  import { DEFAULT_SUMMARY_PROMPT, type AttentionReason, type PromptPlaceholder } from "../shared/herald";
17
+ import { HELPER_LABELS, deleteAgent } from "./cleanup";
14
18
  import { displayName, firstWords, plainText } from "./timeline";
15
19
 
16
20
  export const HELPER_TITLE = "Herald summary";
@@ -38,6 +42,10 @@ export interface SummarizerDeps {
38
42
  prompt?: string;
39
43
  /** Called as soon as the helper exists, before its first turn can end. */
40
44
  onHelperCreated?: (helperId: string) => void;
45
+ /** Delete the helper when it is done, rather than leaving an archived session behind. */
46
+ deleteHelper?: boolean;
47
+ /** How to delete it. The real one shells out to the `paseo` CLI; tests pass their own. */
48
+ deleteAgent?: (agentId: string) => Promise<void>;
41
49
  }
42
50
 
43
51
  export interface Summary {
@@ -179,6 +187,33 @@ export function parseSummaryText(lastMessage: string | null): string {
179
187
  return firstWords(unfenced, 45);
180
188
  }
181
189
 
190
+ /** Enough of a helper to put it away. Projected rather than imported: see `host-types`. */
191
+ interface RetirableHelper {
192
+ id: string;
193
+ archive: () => Promise<unknown>;
194
+ }
195
+
196
+ /**
197
+ * The helper's last rites, fire-and-forget: nothing the caller wants is still
198
+ * coming from it, and the summary should not wait on a child process.
199
+ *
200
+ * A delete covers an archive — the CLI interrupts the agent first — so it is
201
+ * tried on its own, and the archive is what happens when it is switched off or
202
+ * fails. `archive` is true only where the daemon has not already done it:
203
+ * `autoArchive` fires on a finished turn and on nothing else.
204
+ */
205
+ async function retire(helper: RetirableHelper, deps: SummarizerDeps, archive: boolean): Promise<void> {
206
+ if (deps.deleteHelper === true) {
207
+ try {
208
+ await (deps.deleteAgent ?? deleteAgent)(helper.id);
209
+ return;
210
+ } catch (error) {
211
+ console.error(`[herald] could not delete summary helper ${helper.id}:`, error);
212
+ }
213
+ }
214
+ if (archive) await helper.archive().catch(() => {});
215
+ }
216
+
182
217
  export async function summarize(request: SummaryRequest, deps: SummarizerDeps): Promise<Summary> {
183
218
  if (request.agent.workspaceId === null) {
184
219
  throw new Error("The agent has no workspace, so there is nowhere to place a summary helper.");
@@ -191,7 +226,7 @@ export async function summarize(request: SummaryRequest, deps: SummarizerDeps):
191
226
  autoArchive: true,
192
227
  outputSchema: SUMMARY_OUTPUT_SCHEMA as unknown as Record<string, unknown>,
193
228
  prompt: buildPrompt(request, deps.prompt),
194
- labels: { "herald.role": "summarizer" },
229
+ labels: HELPER_LABELS,
195
230
  });
196
231
  deps.onHelperCreated?.(helper.id);
197
232
  try {
@@ -213,11 +248,14 @@ export async function summarize(request: SummaryRequest, deps: SummarizerDeps):
213
248
  if (result.status !== "idle") {
214
249
  throw new Error(result.error ?? `The summary agent ended with status ${result.status}.`);
215
250
  }
216
- return { text: parseSummaryText(result.lastMessage), model: deps.provider };
251
+ const summary = { text: parseSummaryText(result.lastMessage), model: deps.provider };
252
+ // The turn finished, so autoArchive has it; only a delete is left to do.
253
+ void retire(helper, deps, false);
254
+ return summary;
217
255
  } catch (error) {
218
256
  // autoArchive only fires on a finished turn; a helper that timed out or
219
257
  // was denied is still there and has to be put away by hand.
220
- void helper.archive().catch(() => {});
258
+ void retire(helper, deps, true);
221
259
  throw error;
222
260
  }
223
261
  }
package/shared/herald.ts CHANGED
@@ -2,7 +2,7 @@
2
2
  * The contracts both halves agree on: what one "needs you" entry looks like,
3
3
  * the RPC that lists them, and the daemon-side configuration document.
4
4
  *
5
- * Which side owns a value follows the rule in the root CLAUDE.md — the side that
5
+ * Which side owns a value follows the rule in the root AGENTS.md — the side that
6
6
  * has to *read* it. Everything in `HeraldConfigSchema` is read by the daemon's
7
7
  * hooks (which events to summarise, which model writes the summary), so it
8
8
  * lives in the daemon's own file behind two RPCs. How the summary is *spoken*
@@ -181,6 +181,16 @@ export const DEFAULT_SUMMARIZER = {
181
181
  prompt: DEFAULT_SUMMARY_PROMPT,
182
182
  };
183
183
 
184
+ /**
185
+ * Every summary is written by a helper agent, and an agent is a session in the
186
+ * user's history whether it is archived or not. Deleting it once the sentence
187
+ * is written is the default; keeping it is for reading what the helper was
188
+ * actually asked when a summary comes out wrong.
189
+ */
190
+ export const DEFAULT_CLEANUP = {
191
+ deleteHelpers: true,
192
+ };
193
+
184
194
  export const DEFAULT_ANNOUNCE: Record<AnnounceKey, boolean> = {
185
195
  question: true,
186
196
  plan: true,
@@ -213,12 +223,18 @@ export const HeraldConfigSchema = z.object({
213
223
  error: z.boolean().default(true),
214
224
  })
215
225
  .default(DEFAULT_ANNOUNCE),
226
+ cleanup: z
227
+ .object({
228
+ deleteHelpers: z.boolean().default(DEFAULT_CLEANUP.deleteHelpers),
229
+ })
230
+ .default(DEFAULT_CLEANUP),
216
231
  });
217
232
  export type HeraldConfig = z.infer<typeof HeraldConfigSchema>;
218
233
 
219
234
  export const DEFAULT_CONFIG: HeraldConfig = {
220
235
  summarizer: { ...DEFAULT_SUMMARIZER },
221
236
  announce: { ...DEFAULT_ANNOUNCE },
237
+ cleanup: { ...DEFAULT_CLEANUP },
222
238
  };
223
239
 
224
240
  export const readConfig = defineRpc({