@gpambrozio/paseo-herald 0.6.0 → 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,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.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
+
20
+ ## [0.6.1] — 2026-10-31
21
+
22
+ ### Fixed
23
+
24
+ - **Herald no longer lists finished agents it has no record of.** An agent Paseo still marked as
25
+ finished but Herald never saw finish showed up as a "Finished" card reading "No summary: this
26
+ happened before Herald was watching this agent", and each one counted toward the number beside
27
+ Herald in the sidebar. Those are left out now. Agents waiting on a question, a permission or an
28
+ error still show, whether or not Herald saw them happen.
29
+
10
30
  ## [0.6.0] — 2026-10-07
11
31
 
12
32
  **Requires Paseo 0.11.** This version does not load on Paseo 0.10 or older; stay on 0.5.1 until you
package/client/herald.tsx CHANGED
@@ -7,7 +7,8 @@
7
7
  * Two sources, joined by agent id in `client/rows.ts` and loaded by
8
8
  * `client/waiting.ts`, which the sidebar row reads too. An agent Paseo flags
9
9
  * that Herald has no entry for (an event before the plugin loaded, say) is
10
- * still listed, with what Paseo knows about the reason.
10
+ * still listed, with what Paseo knows about the reason — unless the flag is a
11
+ * finished turn, which has nothing left to act on and is left out.
11
12
  *
12
13
  * Async **function expressions**, never async arrows, anywhere in this file:
13
14
  * the app `eval`s the client bundle, and Hermes's eval compiler on iOS and
package/client/rows.ts CHANGED
@@ -38,21 +38,20 @@ export interface FlaggedAgent {
38
38
  * keeps an agent flagged until the user's next message, however long ago the
39
39
  * turn ended, and that is right — a question asked a week ago is still
40
40
  * unanswered. A *closed* session is not waiting on anyone until it is opened
41
- * again, and a turn reported as finished on an agent that is *running* was
42
- * not the end of anything — some providers say a turn is done and carry on.
43
- * Those two are the cases dropped here.
41
+ * again, so it is dropped here. A finished turn Herald has no entry for is
42
+ * dropped too, by `joinRows`, whatever the agent's status.
44
43
  */
45
44
  function isCurrent(agent: FlaggedAgent): boolean {
46
- if (agent.status === "closed") return false;
47
- if (agent.attentionReason === "finished" && agent.status === "running") return false;
48
- return true;
45
+ return agent.status !== "closed";
49
46
  }
50
47
 
51
48
  /**
52
49
  * Herald's entries win over Paseo's flags for the same agent, since they carry
53
- * the reason and the sentence. A *finished* entry on an agent that is working
54
- * again is already withheld by the daemon, which knows each entry's agent
55
- * without having to enumerate every running one — see `Liveness`.
50
+ * the reason and the sentence. A Paseo flag Herald has no entry for gets a row
51
+ * only when something is still waiting on the user, never for a finished turn.
52
+ * A *finished* entry on an agent that is working again is already withheld by
53
+ * the daemon, which knows each entry's agent without having to enumerate every
54
+ * running one — see `Liveness`.
56
55
  */
57
56
  export function joinRows(entries: AttentionEntry[], flagged: FlaggedAgent[]): Row[] {
58
57
  const byAgent = new Map<string, Row>();
@@ -69,6 +68,11 @@ export function joinRows(entries: AttentionEntry[], flagged: FlaggedAgent[]): Ro
69
68
  });
70
69
  flagged.forEach((agent) => {
71
70
  if (byAgent.has(agent.id) || !isCurrent(agent)) return;
71
+ // Paseo keeps a finished agent flagged until the next message, so a finished
72
+ // turn Herald never recorded would get a card it has nothing to say about.
73
+ // A question, permission or error Herald never saw is still unanswered, and
74
+ // keeps its row.
75
+ if (agent.attentionReason === "finished") return;
72
76
  byAgent.set(agent.id, {
73
77
  agentId: agent.id,
74
78
  title: agent.title,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gpambrozio/paseo-herald",
3
- "version": "0.6.0",
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
+ }