@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 +20 -0
- package/client/herald.tsx +2 -1
- package/client/rows.ts +13 -9
- 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,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,
|
|
42
|
-
*
|
|
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
|
-
|
|
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
|
|
54
|
-
*
|
|
55
|
-
*
|
|
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.
|
|
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
|
+
}
|