@gpambrozio/paseo-herald 0.2.3 → 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 +27 -0
- package/README.md +17 -4
- package/client/settings-screen.tsx +21 -1
- package/client/web.ts +1 -1
- package/index.server.ts +33 -0
- package/package.json +1 -1
- package/server/card.ts +1 -1
- package/server/cleanup.ts +196 -0
- package/server/hooks.ts +25 -4
- package/server/host-types.ts +28 -0
- package/server/liveness.ts +1 -1
- package/server/sdk-types.ts +1 -1
- package/server/summarize.ts +42 -4
- package/server/timeline.ts +1 -1
- package/server/workspaces.ts +1 -1
- package/shared/herald.ts +17 -1
- package/server/paseo-api.ts +0 -17
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,33 @@ follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Every version
|
|
|
7
7
|
as `@gpambrozio/paseo-herald` and tagged here, so a version is something to install and a line to
|
|
8
8
|
read before you move.
|
|
9
9
|
|
|
10
|
+
## [0.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
|
+
|
|
29
|
+
## [0.2.4] — 2026-09-19
|
|
30
|
+
|
|
31
|
+
### Fixed
|
|
32
|
+
|
|
33
|
+
- **Installs from npm — verified this time.** 0.2.3 fixed one missing dependency and left a second
|
|
34
|
+
one behind, so the install still failed the same way. Both are gone, and the published package was
|
|
35
|
+
installed on a real daemon to prove it rather than reasoned about.
|
|
36
|
+
|
|
10
37
|
## [0.2.3] — 2026-09-19
|
|
11
38
|
|
|
12
39
|
### 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
|
|
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,
|
|
68
|
-
event are announced: questions, plan approvals, tool
|
|
69
|
-
that is switched off still appears in the panel,
|
|
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
|
|
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
|
-
*
|
|
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.
|
|
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",
|
package/server/card.ts
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
* failed — the daemon replaces the row live and on refetch. Rows live in the
|
|
6
6
|
* daemon's memory: they survive scroll and reconnect, not a daemon restart.
|
|
7
7
|
*/
|
|
8
|
-
import type { PaseoApi } from "./
|
|
8
|
+
import type { PaseoApi } from "./host-types";
|
|
9
9
|
|
|
10
10
|
import type { AttentionEntry } from "../shared/herald";
|
|
11
11
|
import { HERALD_CARD_KIND, HERALD_CARD_VERSION, type HeraldCard } from "../shared/timeline";
|
|
@@ -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
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
* the agent move on: a new turn, the permission answered, the agent
|
|
16
16
|
* archived. Paseo's own attention flag decides what the panel *lists*.
|
|
17
17
|
*/
|
|
18
|
-
import type { PaseoApi } from "./
|
|
18
|
+
import type { PaseoApi } from "./host-types";
|
|
19
19
|
import type {
|
|
20
20
|
PluginHookAgent,
|
|
21
21
|
PluginHookContext,
|
|
@@ -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
|
-
|
|
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)
|
|
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) => {
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Paseo's types, taken from the one package the host actually provides.
|
|
3
|
+
*
|
|
4
|
+
* A running plugin is given `@getpaseo/plugin`. It is not given
|
|
5
|
+
* `@getpaseo/client` or `@getpaseo/protocol`, which are devDependencies here —
|
|
6
|
+
* and an npm install runs `--omit=dev`, so neither is on disk. The daemon's
|
|
7
|
+
* runtime-boundary plugin resolves every import reachable from an entry, type
|
|
8
|
+
* imports included, and fails the *install* when one is missing. A directory or
|
|
9
|
+
* Git install never shows this, because `npm install` in the folder has put the
|
|
10
|
+
* whole SDK there; `server/sdk-types.ts` gets away with importing
|
|
11
|
+
* `@getpaseo/client` only because nothing imports *it*.
|
|
12
|
+
*
|
|
13
|
+
* So every Paseo type this plugin needs is projected out of `@getpaseo/plugin`,
|
|
14
|
+
* which re-declares them structurally. Same types, no dependency. Add to this
|
|
15
|
+
* file rather than reaching for the upstream package.
|
|
16
|
+
*/
|
|
17
|
+
import type {
|
|
18
|
+
PluginHandlerContext,
|
|
19
|
+
PluginLifecycleEvents,
|
|
20
|
+
} from "@getpaseo/plugin/server";
|
|
21
|
+
|
|
22
|
+
export type PaseoApi = PluginHandlerContext["paseo"];
|
|
23
|
+
|
|
24
|
+
export type AgentTimelineItem =
|
|
25
|
+
PluginLifecycleEvents["agent.turn_ended"]["timeline"][number];
|
|
26
|
+
|
|
27
|
+
export type AgentPermissionRequest =
|
|
28
|
+
PluginLifecycleEvents["agent.permission_requested"]["request"];
|
package/server/liveness.ts
CHANGED
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
* Answers are cached for a short while so the clients' polling does not turn
|
|
21
21
|
* into one daemon fetch per entry per poll.
|
|
22
22
|
*/
|
|
23
|
-
import type { PaseoApi } from "./
|
|
23
|
+
import type { PaseoApi } from "./host-types";
|
|
24
24
|
|
|
25
25
|
import type { AttentionEntry } from "../shared/herald";
|
|
26
26
|
import type { AttentionStore } from "./store";
|
package/server/sdk-types.ts
CHANGED
|
@@ -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
|
|
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";
|
package/server/summarize.ts
CHANGED
|
@@ -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
|
-
import type { PaseoApi } from "./
|
|
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:
|
|
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
|
-
|
|
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
|
|
258
|
+
void retire(helper, deps, true);
|
|
221
259
|
throw error;
|
|
222
260
|
}
|
|
223
261
|
}
|
package/server/timeline.ts
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
* here touches the network or a model, which is what makes it the part with
|
|
5
5
|
* tests.
|
|
6
6
|
*/
|
|
7
|
-
import type { AgentPermissionRequest, AgentTimelineItem } from "
|
|
7
|
+
import type { AgentPermissionRequest, AgentTimelineItem } from "./host-types";
|
|
8
8
|
|
|
9
9
|
import type { AttentionReason } from "../shared/herald";
|
|
10
10
|
|
package/server/workspaces.ts
CHANGED
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
|
|
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({
|
package/server/paseo-api.ts
DELETED
|
@@ -1,17 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* `PaseoApi` without importing `@getpaseo/client`.
|
|
3
|
-
*
|
|
4
|
-
* The host provides `@getpaseo/plugin` to a running plugin; it does not provide
|
|
5
|
-
* `@getpaseo/client`. That distinction is invisible to a plugin installed from a
|
|
6
|
-
* directory or from Git, where `npm install` has already put the whole SDK on
|
|
7
|
-
* disk — but an npm install runs `--omit=dev`, so a devDependency is simply not
|
|
8
|
-
* there, and the daemon's runtime-boundary plugin fails the build for any
|
|
9
|
-
* *reachable* module that imports one. `server/sdk-types.ts` gets away with it
|
|
10
|
-
* only because nothing imports it.
|
|
11
|
-
*
|
|
12
|
-
* So the type is taken from where it is already re-exported, through a context
|
|
13
|
-
* the host hands every handler. Same type, no dependency.
|
|
14
|
-
*/
|
|
15
|
-
import type { PluginHandlerContext } from "@getpaseo/plugin/server";
|
|
16
|
-
|
|
17
|
-
export type PaseoApi = PluginHandlerContext["paseo"];
|