@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 +35 -0
- package/README.md +8 -0
- package/client/agents.ts +81 -0
- package/client/announcer.ts +3 -2
- package/client/herald.tsx +11 -4
- package/client/settings-screen.tsx +9 -0
- package/index.server.ts +4 -3
- package/package.json +1 -1
- package/server/cleanup.ts +15 -5
- package/server/config.ts +4 -12
- package/server/data-dir.ts +153 -0
- package/server/hooks.ts +20 -2
- package/shared/herald.ts +21 -0
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
|
|
package/client/agents.ts
ADDED
|
@@ -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
|
+
}
|
package/client/announcer.ts
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
474
|
+
unwatch();
|
|
468
475
|
};
|
|
469
|
-
}, [refresh,
|
|
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 {
|
|
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
|
-
|
|
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.
|
|
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 "./
|
|
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
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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/
|
|
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 {
|
|
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
|
|
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 (!
|
|
209
|
-
// Switched off
|
|
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
|
|