@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 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.1",
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 output = latestOutputText(event.timeline);
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(event.timeline) },
414
+ { output, lastUser: turn === null ? null : lastUserMessage(turn) },
396
415
  );
397
416
  }),
398
417
 
@@ -21,8 +21,14 @@ import type {
21
21
 
22
22
  export type PaseoApi = PluginHandlerContext["paseo"];
23
23
 
24
- export type AgentTimelineItem =
25
- PluginLifecycleEvents["agent.turn_ended"]["timeline"][number];
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"];
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Turns what the hooks hand us — a timeline snapshot or a permission request —
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
+ }