@gpambrozio/paseo-herald 0.5.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,26 @@ 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
+
10
30
  ## [0.5.0] — 2026-09-23
11
31
 
12
32
  ### Changed
@@ -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(
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.5.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
+ }