@gpambrozio/paseo-herald 0.6.1 → 0.6.2
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 +10 -0
- package/package.json +1 -1
- package/server/hooks.ts +24 -5
- package/server/host-types.ts +8 -2
- package/server/timeline.ts +1 -1
- package/server/turn.ts +52 -0
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,16 @@ 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.6.2] — 2026-11-20
|
|
11
|
+
|
|
12
|
+
### Fixed
|
|
13
|
+
|
|
14
|
+
- **Herald announces finished turns again, with what the agent said.** Since Paseo 0.13 the event
|
|
15
|
+
Herald listens for has carried no messages, so every finished turn looked silent: none was announced,
|
|
16
|
+
and a failed or canceled one was announced without its last words or the request it answered.
|
|
17
|
+
Herald now reads the turn from the agent's history, so it keeps working once Paseo stops sending
|
|
18
|
+
the empty field altogether.
|
|
19
|
+
|
|
10
20
|
## [0.6.1] — 2026-10-31
|
|
11
21
|
|
|
12
22
|
### Fixed
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gpambrozio/paseo-herald",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.2",
|
|
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/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 "./host-types";
|
|
18
|
+
import type { AgentTimelineItem, PaseoApi } from "./host-types";
|
|
19
19
|
import type {
|
|
20
20
|
PluginHookAgent,
|
|
21
21
|
PluginHookContext,
|
|
@@ -31,6 +31,7 @@ import {
|
|
|
31
31
|
import { publishCard } from "./card";
|
|
32
32
|
import { isAgentRunning } from "./liveness";
|
|
33
33
|
import type { AttentionStore } from "./store";
|
|
34
|
+
import { carriedTurn, readEndedTurn } from "./turn";
|
|
34
35
|
import { HELPER_TITLE, type Summary, type SummaryRequest, type SummarizerDeps } from "./summarize";
|
|
35
36
|
import { createWorkspaceTitleLookup, type WorkspaceTitleLookup } from "./workspaces";
|
|
36
37
|
import {
|
|
@@ -52,6 +53,8 @@ export interface HookDeps {
|
|
|
52
53
|
publish?: (paseo: PaseoApi, entry: AttentionEntry, options?: { superseded?: boolean }) => Promise<void>;
|
|
53
54
|
/** Whether a turn is in flight right now; a summary the agent outran is dropped. */
|
|
54
55
|
isRunning?: (paseo: PaseoApi, agentId: string) => Promise<boolean>;
|
|
56
|
+
/** What was said in the turn that ended; since Paseo 0.13 the event carries none of it. */
|
|
57
|
+
readTurn?: (paseo: PaseoApi, agentId: string, turnId: string | null) => Promise<AgentTimelineItem[]>;
|
|
55
58
|
now?: () => Date;
|
|
56
59
|
/** How many helpers may be writing at once; more agents than this wait their turn. */
|
|
57
60
|
maxConcurrent?: number;
|
|
@@ -96,6 +99,20 @@ export function registerHooks(server: PluginLifecycleRegistration, deps: HookDep
|
|
|
96
99
|
const workspaceTitle = deps.workspaceTitle ?? createWorkspaceTitleLookup();
|
|
97
100
|
const publish = deps.publish ?? publishCard;
|
|
98
101
|
const isRunning = deps.isRunning ?? isAgentRunning;
|
|
102
|
+
const readTurnItems = deps.readTurn ?? readEndedTurn;
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* Null when the turn's timeline cannot be read. The turn is still announced,
|
|
106
|
+
* without its words: losing the words is better than losing the notice.
|
|
107
|
+
*/
|
|
108
|
+
async function readTurn(paseo: PaseoApi, agentId: string, turnId: string | null): Promise<AgentTimelineItem[] | null> {
|
|
109
|
+
try {
|
|
110
|
+
return await readTurnItems(paseo, agentId, turnId);
|
|
111
|
+
} catch (error) {
|
|
112
|
+
console.error(`[herald] could not read the turn ${agentId} just ended:`, error);
|
|
113
|
+
return null;
|
|
114
|
+
}
|
|
115
|
+
}
|
|
99
116
|
|
|
100
117
|
/**
|
|
101
118
|
* Whether the agent has carried on since the summary was commissioned, in
|
|
@@ -353,14 +370,16 @@ export function registerHooks(server: PluginLifecycleRegistration, deps: HookDep
|
|
|
353
370
|
if (isHelper(event.agent)) return;
|
|
354
371
|
if (isRepeatTurn(event.agent.id, event.turnId)) return;
|
|
355
372
|
const generation = generationOf(event.agent.id);
|
|
356
|
-
const
|
|
373
|
+
const turn = carriedTurn(event) ?? (await readTurn(context.paseo, event.agent.id, event.turnId));
|
|
374
|
+
if (generationOf(event.agent.id) !== generation) return;
|
|
375
|
+
const output = turn === null ? "" : latestOutputText(turn);
|
|
357
376
|
let reason: AttentionReason;
|
|
358
377
|
let headline: string;
|
|
359
378
|
switch (event.outcome.kind) {
|
|
360
379
|
case "completed":
|
|
361
380
|
// A turn that produced no words — a compaction, a bare tool run —
|
|
362
|
-
// gives the user nothing to hear.
|
|
363
|
-
if (output === "") return;
|
|
381
|
+
// gives the user nothing to hear. One we could not read may have.
|
|
382
|
+
if (output === "" && turn !== null) return;
|
|
364
383
|
reason = "finished";
|
|
365
384
|
headline = "Finished";
|
|
366
385
|
break;
|
|
@@ -392,7 +411,7 @@ export function registerHooks(server: PluginLifecycleRegistration, deps: HookDep
|
|
|
392
411
|
output === "" ? null : firstWords(output, 60),
|
|
393
412
|
config,
|
|
394
413
|
context,
|
|
395
|
-
{ output, lastUser: lastUserMessage(
|
|
414
|
+
{ output, lastUser: turn === null ? null : lastUserMessage(turn) },
|
|
396
415
|
);
|
|
397
416
|
}),
|
|
398
417
|
|
package/server/host-types.ts
CHANGED
|
@@ -21,8 +21,14 @@ import type {
|
|
|
21
21
|
|
|
22
22
|
export type PaseoApi = PluginHandlerContext["paseo"];
|
|
23
23
|
|
|
24
|
-
|
|
25
|
-
|
|
24
|
+
/** One row of an agent's timeline, as `timeline.refetch` returns it. */
|
|
25
|
+
export type TimelineEntry = Awaited<
|
|
26
|
+
ReturnType<ReturnType<PaseoApi["agents"]["ref"]>["timeline"]["refetch"]>
|
|
27
|
+
>["entries"][number];
|
|
28
|
+
|
|
29
|
+
// From the timeline page rather than `agent.turn_ended`, whose `timeline` field
|
|
30
|
+
// Paseo 0.17 removed.
|
|
31
|
+
export type AgentTimelineItem = TimelineEntry["item"];
|
|
26
32
|
|
|
27
33
|
export type AgentPermissionRequest =
|
|
28
34
|
PluginLifecycleEvents["agent.permission_requested"]["request"];
|
package/server/timeline.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Turns what the hooks
|
|
2
|
+
* Turns what the hooks see — a turn read back from the timeline, or a permission request —
|
|
3
3
|
* into the plain text an entry carries and a summary is written from. Nothing
|
|
4
4
|
* here touches the network or a model, which is what makes it the part with
|
|
5
5
|
* tests.
|
package/server/turn.ts
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The turn an `agent.turn_ended` event is about, read back from the agent's
|
|
3
|
+
* timeline.
|
|
4
|
+
*
|
|
5
|
+
* Paseo 0.11 and 0.12 put the agent's timeline on the event; 0.13 left the
|
|
6
|
+
* field empty to keep the payload small, and 0.17 dropped it from the SDK's
|
|
7
|
+
* types, though the daemon keeps sending it empty until 2027-05-31. So the event's
|
|
8
|
+
* own history is used while it has one, and otherwise the turn is read back:
|
|
9
|
+
* the latest whole turn (`direction: "tail", limit: 1, wholeTurns: true`),
|
|
10
|
+
* Paseo's documented way in, which daemons since 0.14 widen from one row back
|
|
11
|
+
* to the turn's first row. A 0.13 daemon ignores `wholeTurns` and returns the
|
|
12
|
+
* last row alone, which is less, not wrong.
|
|
13
|
+
*/
|
|
14
|
+
import type { AgentTimelineItem, PaseoApi, TimelineEntry } from "./host-types";
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* What was said in the turn `turnId`, given the timeline's latest whole turn.
|
|
18
|
+
*
|
|
19
|
+
* Paseo's example keeps only the entries tagged with `turnId`, but not every
|
|
20
|
+
* provider tags its rows: a live 0.16 daemon returned whole turns with no
|
|
21
|
+
* `turnId` on any entry, which that filter would empty. So the tags are used
|
|
22
|
+
* only to notice a turn that started after this one ended — the page then
|
|
23
|
+
* belongs to it, and there is nothing to read. Untagged pages are taken whole.
|
|
24
|
+
*/
|
|
25
|
+
export function endedTurnItems(
|
|
26
|
+
entries: readonly TimelineEntry[],
|
|
27
|
+
turnId: string | null,
|
|
28
|
+
): AgentTimelineItem[] {
|
|
29
|
+
const tags = entries.flatMap((entry) => (entry.turnId === undefined ? [] : [entry.turnId]));
|
|
30
|
+
if (turnId !== null && tags.length > 0 && !tags.includes(turnId)) return [];
|
|
31
|
+
return entries.map((entry) => entry.item);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
// Declared apart from the call so the 0.11 SDK, whose refetch options predate
|
|
35
|
+
// `wholeTurns`, still accepts it; the daemon client passes it through.
|
|
36
|
+
const LATEST_TURN = { direction: "tail", limit: 1, projection: "projected", wholeTurns: true } as const;
|
|
37
|
+
|
|
38
|
+
/** The history a 0.11 or 0.12 daemon put on the event; null when it sent none. */
|
|
39
|
+
export function carriedTurn(event: object): AgentTimelineItem[] | null {
|
|
40
|
+
const timeline = (event as { timeline?: readonly AgentTimelineItem[] }).timeline;
|
|
41
|
+
return timeline === undefined || timeline.length === 0 ? null : [...timeline];
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** Reads the turn that just ended. */
|
|
45
|
+
export async function readEndedTurn(
|
|
46
|
+
paseo: PaseoApi,
|
|
47
|
+
agentId: string,
|
|
48
|
+
turnId: string | null,
|
|
49
|
+
): Promise<AgentTimelineItem[]> {
|
|
50
|
+
const page = await paseo.agents.ref(agentId).timeline.refetch(LATEST_TURN);
|
|
51
|
+
return endedTurnItems(page.entries, turnId);
|
|
52
|
+
}
|