@gpambrozio/paseo-herald 0.5.1 → 0.6.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 +20 -0
- package/README.md +8 -5
- package/client/agents.ts +5 -1
- package/client/herald.tsx +69 -243
- package/client/rows.ts +165 -0
- package/client/screen.ts +32 -0
- package/client/sidebar.tsx +146 -0
- package/client/waiting.ts +109 -0
- package/index.client.tsx +11 -11
- package/package.json +5 -4
- package/paseo-plugin.json +1 -1
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.0] — 2026-10-07
|
|
11
|
+
|
|
12
|
+
**Requires Paseo 0.11.** This version does not load on Paseo 0.10 or older; stay on 0.5.1 until you
|
|
13
|
+
update Paseo.
|
|
14
|
+
|
|
15
|
+
### Added
|
|
16
|
+
|
|
17
|
+
- **The Herald row in the sidebar counts who is waiting for you.** A small number beside it says how
|
|
18
|
+
many agents need you right now, and it goes away when none do. Tap the number for a list of them;
|
|
19
|
+
pick one and Herald opens with that agent's card scrolled into view and outlined. Tapping the row
|
|
20
|
+
itself still opens Herald as before.
|
|
21
|
+
|
|
22
|
+
### Changed
|
|
23
|
+
|
|
24
|
+
- **The Herald page is titled "Herald" however you open it.** Opened from the Command Center, its
|
|
25
|
+
title read "herald". Your sidebar order, a hidden Herald row and saved links to it all carry over.
|
|
26
|
+
- Settings › Sidebar now shows a generic plugin icon for Herald instead of the megaphone, and the
|
|
27
|
+
page's title no longer has the megaphone beside it. Paseo draws both that way for every plugin on
|
|
28
|
+
its new sidebar.
|
|
29
|
+
|
|
10
30
|
## [0.5.1] — 2026-09-27
|
|
11
31
|
|
|
12
32
|
### Changed
|
package/README.md
CHANGED
|
@@ -6,7 +6,8 @@ When an agent asks a question, pauses for permission, wants a plan approved, fin
|
|
|
6
6
|
fails, Herald has a small helper agent write one spoken sentence about it — what is being asked and
|
|
7
7
|
the choices, or what was done and whether anything is left — and the Paseo app on your desk speaks
|
|
8
8
|
it. A **Herald** panel in the sidebar lists every agent waiting on you with that sentence. Tap a row
|
|
9
|
-
to open that session, or the speaker beside its title to hear the sentence again.
|
|
9
|
+
to open that session, or the speaker beside its title to hear the sentence again. The Herald row in
|
|
10
|
+
the sidebar counts who is waiting; tap the number for a quick list, and pick one to jump to its card.
|
|
10
11
|
|
|
11
12
|

|
|
|
25
26
|
|
|
26
27
|
## What you need
|
|
27
28
|
|
|
28
|
-
- Paseo **0.
|
|
29
|
+
- Paseo **0.11 or newer**, on the daemon and on the device running the app.
|
|
29
30
|
- Speech comes out of the device running the Paseo app, not the daemon machine. The voice, by
|
|
30
31
|
default, is the daemon Mac's: it renders each sentence with `say` and the app plays the audio, so
|
|
31
32
|
you hear the Mac's voices rather than a browser's. If the daemon is not a Mac, the browser's own
|
|
@@ -45,11 +46,13 @@ composer sits below it.](docs/timeline-card.png)
|
|
|
45
46
|
paseo plugin install npm:@gpambrozio/paseo-herald
|
|
46
47
|
```
|
|
47
48
|
|
|
48
|
-
That is the shortest route on **Paseo 0.
|
|
49
|
-
`@<version>` to pin one. On 0.
|
|
49
|
+
That is the shortest route on **Paseo 0.11 or newer**, which installs plugins straight from npm; add
|
|
50
|
+
`@<version>` to pin one. On Paseo 0.9 or 0.10, install the last release that supports them:
|
|
51
|
+
`paseo plugin install npm:@gpambrozio/paseo-herald@0.5.1`. On 0.8, install the last release that
|
|
52
|
+
supported it from this repository instead:
|
|
50
53
|
|
|
51
54
|
```bash
|
|
52
|
-
paseo plugin add gpambrozio/paseo-plugins --path herald
|
|
55
|
+
paseo plugin add gpambrozio/paseo-plugins --path herald --ref herald/v0.3.0
|
|
53
56
|
```
|
|
54
57
|
|
|
55
58
|
Pin a repository install with `--ref herald/v<version>`. To hack on it, clone the repository and
|
package/client/agents.ts
CHANGED
|
@@ -3,9 +3,13 @@
|
|
|
3
3
|
*
|
|
4
4
|
* Since Paseo 0.9, `paseo.agents.subscribe()` only adds a local listener to
|
|
5
5
|
* observations the same API instance opened with `agents.list({ subscribe })`,
|
|
6
|
-
* and
|
|
6
|
+
* and the app's own observations live on another instance — so a bare
|
|
7
7
|
* `subscribe()` hears nothing, ever. This opens that observation.
|
|
8
8
|
*
|
|
9
|
+
* Since 0.11 the whole installation shares one API instance, disposed only
|
|
10
|
+
* when the plugin unloads, so an observation nobody releases outlives the
|
|
11
|
+
* component that opened it. Always run the returned cleanup.
|
|
12
|
+
*
|
|
9
13
|
* Herald only takes the stream as a nudge to poll sooner; what is listed comes
|
|
10
14
|
* from its own polls. So the snapshot is ignored and asked for one agent long:
|
|
11
15
|
* the daemon filters an observation's updates by its `filter`, not by the page,
|
package/client/herald.tsx
CHANGED
|
@@ -1,33 +1,35 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The
|
|
3
|
-
* wrote for it, a button to open the session, and a button to hear it
|
|
2
|
+
* The Herald screen: every agent waiting on the user, each with the sentence
|
|
3
|
+
* Herald wrote for it, a button to open the session, and a button to hear it
|
|
4
|
+
* again. Opened with an `agent` param — the sidebar popover does that — it
|
|
5
|
+
* scrolls that agent's card into view and outlines it.
|
|
4
6
|
*
|
|
5
|
-
* Two sources, joined by agent id
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
* knows about the reason.
|
|
7
|
+
* Two sources, joined by agent id in `client/rows.ts` and loaded by
|
|
8
|
+
* `client/waiting.ts`, which the sidebar row reads too. An agent Paseo flags
|
|
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
11
|
*
|
|
11
12
|
* Async **function expressions**, never async arrows, anywhere in this file:
|
|
12
13
|
* the app `eval`s the client bundle, and Hermes's eval compiler on iOS and
|
|
13
14
|
* Android evaluates an async arrow to `undefined`. Same reason every closure
|
|
14
15
|
* over a list element goes through `.map`, never a `for…of` body.
|
|
15
16
|
*/
|
|
16
|
-
import
|
|
17
|
+
import type { PluginScreenProps } from "@getpaseo/plugin/client";
|
|
17
18
|
import { Icon, useToast } from "@getpaseo/plugin/client/react-native";
|
|
18
19
|
import { type ReactElement, useCallback, useEffect, useMemo, useRef, useState } from "react";
|
|
19
20
|
import { ActivityIndicator, Pressable, ScrollView, Text, View } from "react-native";
|
|
20
21
|
|
|
21
|
-
import { listAttention, type AttentionEntry, type AttentionReason } from "../shared/herald";
|
|
22
|
-
import { watchAgents } from "./agents";
|
|
23
22
|
import { getAnnouncer, isMutedHere, setMutedHere, speechText } from "./announcer";
|
|
23
|
+
import { lookOf, relativeTime, rowSubtitle, rowTitle, toneColor, withAlpha, type Row } from "./rows";
|
|
24
|
+
import { focusedAgentId } from "./screen";
|
|
25
|
+
import { useWaiting, useWaitingNudges } from "./waiting";
|
|
24
26
|
import { canPlaySpeech, speechPlatform } from "./web";
|
|
25
27
|
|
|
26
28
|
/**
|
|
27
29
|
* Opening the settings screen is a `PluginClientContext` capability:
|
|
28
|
-
* `
|
|
30
|
+
* `PluginScreenProps` carries no `openSettings`, so the screen cannot reach
|
|
29
31
|
* its own settings on its own. `index.client.tsx` has the context and hands the
|
|
30
|
-
* opener down here at contribution time — which happens before any
|
|
32
|
+
* opener down here at contribution time — which happens before any screen can
|
|
31
33
|
* mount — and the header button calls it. Module scope belongs to this client's
|
|
32
34
|
* bundle eval, the same place the other plugins here keep their surface caches.
|
|
33
35
|
*/
|
|
@@ -37,151 +39,16 @@ export function bindSettingsOpener(open: ((id: string) => void) | null): void {
|
|
|
37
39
|
openSettingsScreen = open;
|
|
38
40
|
}
|
|
39
41
|
|
|
40
|
-
/** A row's reason: one of Herald's, or "attention" when only Paseo's flag is known. */
|
|
41
|
-
type RowReason = AttentionReason | "attention";
|
|
42
|
-
|
|
43
|
-
interface Row {
|
|
44
|
-
agentId: string;
|
|
45
|
-
title: string | null;
|
|
46
|
-
workspaceId: string | null;
|
|
47
|
-
cwd: string;
|
|
48
|
-
reason: RowReason;
|
|
49
|
-
/** ISO time the row sorts by: the event, or when Paseo flagged the agent. */
|
|
50
|
-
at: string;
|
|
51
|
-
entry: AttentionEntry | null;
|
|
52
|
-
}
|
|
53
|
-
|
|
54
|
-
/** The fields this surface reads off a Paseo agent snapshot. */
|
|
55
|
-
interface FlaggedAgent {
|
|
56
|
-
id: string;
|
|
57
|
-
title: string | null;
|
|
58
|
-
workspaceId: string | null;
|
|
59
|
-
cwd: string;
|
|
60
|
-
status: string;
|
|
61
|
-
attentionReason: "finished" | "error" | "permission" | null;
|
|
62
|
-
at: string;
|
|
63
|
-
}
|
|
64
|
-
|
|
65
|
-
/**
|
|
66
|
-
* A Paseo-flagged agent worth a row: one whose session is still open. Paseo
|
|
67
|
-
* keeps an agent flagged until the user's next message, however long ago the
|
|
68
|
-
* turn ended, and that is right — a question asked a week ago is still
|
|
69
|
-
* unanswered. A *closed* session is not waiting on anyone until it is opened
|
|
70
|
-
* again, and a turn reported as finished on an agent that is *running* was
|
|
71
|
-
* not the end of anything — some providers say a turn is done and carry on.
|
|
72
|
-
* Those two are the cases dropped here.
|
|
73
|
-
*/
|
|
74
|
-
function isCurrent(agent: FlaggedAgent): boolean {
|
|
75
|
-
if (agent.status === "closed") return false;
|
|
76
|
-
if (agent.attentionReason === "finished" && agent.status === "running") return false;
|
|
77
|
-
return true;
|
|
78
|
-
}
|
|
79
|
-
|
|
80
|
-
/**
|
|
81
|
-
* Module-scope caches, because the surface is unmounted whenever the user
|
|
82
|
-
* navigates to an agent — which the Open button does — and mounted fresh on
|
|
83
|
-
* the way back. The list repaints before the first load answers.
|
|
84
|
-
*
|
|
85
|
-
* Workspace names come from the host API, not `useWorkspace`: the SDK's state
|
|
86
|
-
* hooks are for workspace and agent panels and throw in a sidebar surface
|
|
87
|
-
* ("Plugin state hooks must run inside a workspace panel").
|
|
88
|
-
*/
|
|
89
|
-
let cachedRows: Row[] | null = null;
|
|
90
|
-
let cachedWorkspaceNames: Record<string, string> = {};
|
|
91
|
-
|
|
92
|
-
const IDLE_REFRESH_MS = 10_000;
|
|
93
|
-
const BUSY_REFRESH_MS = 2_500;
|
|
94
|
-
|
|
95
42
|
const TEST_SENTENCE = "This is Herald. Your agents will be announced like this.";
|
|
96
43
|
|
|
97
|
-
function withAlpha(color: string, alpha: string): string {
|
|
98
|
-
return /^#[0-9a-fA-F]{6}$/.test(color) ? `${color}${alpha}` : color;
|
|
99
|
-
}
|
|
100
|
-
|
|
101
|
-
function relativeTime(iso: string): string {
|
|
102
|
-
const seconds = Math.round((Date.now() - new Date(iso).getTime()) / 1000);
|
|
103
|
-
if (!Number.isFinite(seconds)) return "";
|
|
104
|
-
if (seconds < 45) return "just now";
|
|
105
|
-
const minutes = Math.round(seconds / 60);
|
|
106
|
-
if (minutes < 60) return `${minutes} min ago`;
|
|
107
|
-
const hours = Math.round(minutes / 60);
|
|
108
|
-
if (hours < 24) return `${hours} h ago`;
|
|
109
|
-
const days = Math.round(hours / 24);
|
|
110
|
-
return days === 1 ? "yesterday" : `${days} days ago`;
|
|
111
|
-
}
|
|
112
|
-
|
|
113
|
-
function basename(path: string): string {
|
|
114
|
-
const parts = path.split("/").filter((part) => part !== "");
|
|
115
|
-
return parts[parts.length - 1] ?? path;
|
|
116
|
-
}
|
|
117
|
-
|
|
118
44
|
function errorText(error: unknown): string {
|
|
119
45
|
return error instanceof Error ? error.message : String(error);
|
|
120
46
|
}
|
|
121
47
|
|
|
122
|
-
interface ReasonLook {
|
|
123
|
-
icon: string;
|
|
124
|
-
label: string;
|
|
125
|
-
tone: "accent" | "success" | "warning" | "danger" | "muted";
|
|
126
|
-
}
|
|
127
|
-
|
|
128
|
-
function lookOf(reason: RowReason): ReasonLook {
|
|
129
|
-
switch (reason) {
|
|
130
|
-
case "question":
|
|
131
|
-
return { icon: "MessageCircle", label: "Question", tone: "accent" };
|
|
132
|
-
case "plan":
|
|
133
|
-
return { icon: "ClipboardList", label: "Plan to approve", tone: "accent" };
|
|
134
|
-
case "permission":
|
|
135
|
-
return { icon: "Shield", label: "Permission", tone: "warning" };
|
|
136
|
-
case "finished":
|
|
137
|
-
return { icon: "Check", label: "Finished", tone: "success" };
|
|
138
|
-
case "error":
|
|
139
|
-
return { icon: "X", label: "Error", tone: "danger" };
|
|
140
|
-
case "canceled":
|
|
141
|
-
return { icon: "Ban", label: "Interrupted", tone: "muted" };
|
|
142
|
-
case "attention":
|
|
143
|
-
return { icon: "Megaphone", label: "Needs you", tone: "accent" };
|
|
144
|
-
}
|
|
145
|
-
}
|
|
146
|
-
|
|
147
|
-
/**
|
|
148
|
-
* Herald's entries win over Paseo's flags for the same agent, since they carry
|
|
149
|
-
* the reason and the sentence. A *finished* entry on an agent that is working
|
|
150
|
-
* again is already withheld by the daemon, which knows each entry's agent
|
|
151
|
-
* without having to enumerate every running one — see `Liveness`.
|
|
152
|
-
*/
|
|
153
|
-
function joinRows(entries: AttentionEntry[], flagged: FlaggedAgent[]): Row[] {
|
|
154
|
-
const byAgent = new Map<string, Row>();
|
|
155
|
-
entries.forEach((entry) => {
|
|
156
|
-
byAgent.set(entry.agentId, {
|
|
157
|
-
agentId: entry.agentId,
|
|
158
|
-
title: entry.agentTitle,
|
|
159
|
-
workspaceId: entry.workspaceId,
|
|
160
|
-
cwd: entry.cwd,
|
|
161
|
-
reason: entry.reason,
|
|
162
|
-
at: entry.createdAt,
|
|
163
|
-
entry,
|
|
164
|
-
});
|
|
165
|
-
});
|
|
166
|
-
flagged.forEach((agent) => {
|
|
167
|
-
if (byAgent.has(agent.id) || !isCurrent(agent)) return;
|
|
168
|
-
byAgent.set(agent.id, {
|
|
169
|
-
agentId: agent.id,
|
|
170
|
-
title: agent.title,
|
|
171
|
-
workspaceId: agent.workspaceId,
|
|
172
|
-
cwd: agent.cwd,
|
|
173
|
-
reason: agent.attentionReason ?? "attention",
|
|
174
|
-
at: agent.at,
|
|
175
|
-
entry: null,
|
|
176
|
-
});
|
|
177
|
-
});
|
|
178
|
-
return [...byAgent.values()].sort((a, b) => b.at.localeCompare(a.at));
|
|
179
|
-
}
|
|
180
|
-
|
|
181
48
|
// ---------------------------------------------------------------------------
|
|
182
49
|
// Styles
|
|
183
50
|
|
|
184
|
-
function useStyles({ theme, layout }:
|
|
51
|
+
function useStyles({ theme, layout }: PluginScreenProps) {
|
|
185
52
|
return useMemo(() => {
|
|
186
53
|
const { colors } = theme;
|
|
187
54
|
const separator = withAlpha(colors.foregroundMuted, "33");
|
|
@@ -265,6 +132,7 @@ function useStyles({ theme, layout }: PluginSurfaceProps) {
|
|
|
265
132
|
pending: { flexDirection: "row" as const, alignItems: "center" as const, gap: 8 },
|
|
266
133
|
pendingText: { color: colors.foregroundMuted, fontSize: 13 },
|
|
267
134
|
cardPressed: { backgroundColor: colors.surface2 },
|
|
135
|
+
cardFocused: { borderColor: colors.accent },
|
|
268
136
|
speaker: { padding: 4 },
|
|
269
137
|
};
|
|
270
138
|
}, [theme, layout.compact]);
|
|
@@ -272,32 +140,20 @@ function useStyles({ theme, layout }: PluginSurfaceProps) {
|
|
|
272
140
|
|
|
273
141
|
type Styles = ReturnType<typeof useStyles>;
|
|
274
142
|
|
|
275
|
-
function toneColor(theme: PluginSurfaceProps["theme"], tone: ReasonLook["tone"]): string {
|
|
276
|
-
const { colors } = theme;
|
|
277
|
-
switch (tone) {
|
|
278
|
-
case "accent":
|
|
279
|
-
return colors.accent;
|
|
280
|
-
case "success":
|
|
281
|
-
return colors.statusSuccess;
|
|
282
|
-
case "warning":
|
|
283
|
-
return colors.statusWarning;
|
|
284
|
-
case "danger":
|
|
285
|
-
return colors.statusDanger;
|
|
286
|
-
case "muted":
|
|
287
|
-
return colors.foregroundMuted;
|
|
288
|
-
}
|
|
289
|
-
}
|
|
290
|
-
|
|
291
143
|
// ---------------------------------------------------------------------------
|
|
292
144
|
// Rows
|
|
293
145
|
|
|
294
146
|
interface RowCardProps {
|
|
295
147
|
row: Row;
|
|
296
|
-
|
|
297
|
-
|
|
148
|
+
title: string;
|
|
149
|
+
/** The agent the screen was opened on, from the sidebar popover. */
|
|
150
|
+
focused: boolean;
|
|
151
|
+
props: PluginScreenProps;
|
|
298
152
|
styles: Styles;
|
|
299
153
|
onOpen: ((agentId: string) => void) | null;
|
|
300
154
|
onSpeak: (row: Row) => void;
|
|
155
|
+
/** Where the card sits in the list, so the screen can scroll a focused one into view. */
|
|
156
|
+
onPlaced: (agentId: string, y: number) => void;
|
|
301
157
|
}
|
|
302
158
|
|
|
303
159
|
/**
|
|
@@ -305,16 +161,12 @@ interface RowCardProps {
|
|
|
305
161
|
* the sentence again — beside the title, not at the card's edge, so it is seen. Nested pressables: the speaker takes the touch
|
|
306
162
|
* and the card does not also open.
|
|
307
163
|
*/
|
|
308
|
-
function RowCard({ row,
|
|
164
|
+
function RowCard({ row, title, focused, props, styles, onOpen, onSpeak, onPlaced }: RowCardProps) {
|
|
309
165
|
const look = lookOf(row.reason);
|
|
310
166
|
const color = toneColor(props.theme, look.tone);
|
|
311
167
|
const muted = props.theme.colors.foregroundMuted;
|
|
312
168
|
const entry = row.entry;
|
|
313
|
-
|
|
314
|
-
// agent's own title or, failing that, what it was last asked — which is
|
|
315
|
-
// what tells two untitled agents in one workspace apart.
|
|
316
|
-
const title = workspaceName ?? entry?.workspaceTitle ?? basename(row.cwd);
|
|
317
|
-
const subtitle = row.title?.trim() || entry?.lastRequest || null;
|
|
169
|
+
const subtitle = rowSubtitle(row);
|
|
318
170
|
const spoken = entry === null ? null : speechText(entry);
|
|
319
171
|
// Hidden outright where nothing can play it, rather than offered and failing.
|
|
320
172
|
const canSpeakRow = canPlaySpeech() && (entry === null || spoken !== null);
|
|
@@ -348,7 +200,12 @@ function RowCard({ row, workspaceName, props, styles, onOpen, onSpeak }: RowCard
|
|
|
348
200
|
accessibilityLabel={`Open ${title}`}
|
|
349
201
|
disabled={onOpen === null}
|
|
350
202
|
onPress={onOpen === null ? undefined : () => onOpen(row.agentId)}
|
|
351
|
-
|
|
203
|
+
onLayout={(event) => onPlaced(row.agentId, event.nativeEvent.layout.y)}
|
|
204
|
+
style={({ pressed }) => [
|
|
205
|
+
styles.card,
|
|
206
|
+
focused ? styles.cardFocused : null,
|
|
207
|
+
pressed ? styles.cardPressed : null,
|
|
208
|
+
]}
|
|
352
209
|
>
|
|
353
210
|
<View style={styles.cardTop}>
|
|
354
211
|
<View style={[styles.reasonPill, { backgroundColor: withAlpha(color, "22") }]}>
|
|
@@ -398,82 +255,48 @@ function RowCard({ row, workspaceName, props, styles, onOpen, onSpeak }: RowCard
|
|
|
398
255
|
}
|
|
399
256
|
|
|
400
257
|
// ---------------------------------------------------------------------------
|
|
401
|
-
//
|
|
258
|
+
// Screen
|
|
402
259
|
|
|
403
|
-
export function
|
|
260
|
+
export function HeraldScreen(props: PluginScreenProps) {
|
|
404
261
|
const styles = useStyles(props);
|
|
405
|
-
const paseo = usePaseo();
|
|
406
|
-
const list = useRpc(listAttention);
|
|
407
262
|
const toast = useToast();
|
|
263
|
+
const waiting = useWaiting();
|
|
264
|
+
useWaitingNudges();
|
|
408
265
|
|
|
409
|
-
const
|
|
410
|
-
const
|
|
411
|
-
const
|
|
266
|
+
const rows = waiting.data?.rows ?? null;
|
|
267
|
+
const workspaceNames = useMemo(() => waiting.data?.workspaceNames ?? {}, [waiting.data]);
|
|
268
|
+
const error = waiting.error === null ? null : errorText(waiting.error);
|
|
412
269
|
const [muted, setMuted] = useState(isMutedHere());
|
|
413
270
|
const [testing, setTesting] = useState(false);
|
|
414
|
-
const busyRef = useRef(false);
|
|
415
271
|
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
});
|
|
430
|
-
cachedWorkspaceNames = names;
|
|
431
|
-
setWorkspaceNames(names);
|
|
432
|
-
const agents: FlaggedAgent[] = flagged.entries.map((item) => ({
|
|
433
|
-
id: item.agent.id,
|
|
434
|
-
title: item.agent.title ?? null,
|
|
435
|
-
workspaceId: item.agent.workspaceId ?? null,
|
|
436
|
-
cwd: item.agent.cwd,
|
|
437
|
-
status: item.agent.status,
|
|
438
|
-
attentionReason: item.agent.attentionReason ?? null,
|
|
439
|
-
at: item.agent.attentionTimestamp ?? item.agent.updatedAt,
|
|
440
|
-
}));
|
|
441
|
-
const next = joinRows(attention.entries, agents);
|
|
442
|
-
cachedRows = next;
|
|
443
|
-
setRows(next);
|
|
444
|
-
setError(null);
|
|
445
|
-
} catch (caught) {
|
|
446
|
-
setError(errorText(caught));
|
|
447
|
-
} finally {
|
|
448
|
-
busyRef.current = false;
|
|
449
|
-
}
|
|
272
|
+
// The agent the popover asked for: scrolled to once per request, when its
|
|
273
|
+
// card has been laid out, and outlined for as long as the param stands.
|
|
274
|
+
const focusId = focusedAgentId(props.params);
|
|
275
|
+
const scrollRef = useRef<ScrollView>(null);
|
|
276
|
+
const placed = useRef(new Map<string, number>());
|
|
277
|
+
const scrolledTo = useRef<string | null>(null);
|
|
278
|
+
const scrollToFocus = useCallback(
|
|
279
|
+
function scrollToFocus() {
|
|
280
|
+
if (focusId === null || scrolledTo.current === focusId) return;
|
|
281
|
+
const y = placed.current.get(focusId);
|
|
282
|
+
if (y === undefined) return;
|
|
283
|
+
scrolledTo.current = focusId;
|
|
284
|
+
scrollRef.current?.scrollTo({ y: Math.max(0, y - 8), animated: true });
|
|
450
285
|
},
|
|
451
|
-
[
|
|
286
|
+
[focusId],
|
|
452
287
|
);
|
|
453
|
-
|
|
454
|
-
// A poll, quickened while a summary is being written, plus a nudge from
|
|
455
|
-
// Paseo's own agent stream so a new arrival shows within a moment.
|
|
456
|
-
const pending = rows?.some((row) => row.entry?.summary.status === "pending") ?? false;
|
|
457
|
-
useEffect(() => {
|
|
458
|
-
void refresh();
|
|
459
|
-
const timer = setInterval(() => void refresh(), pending ? BUSY_REFRESH_MS : IDLE_REFRESH_MS);
|
|
460
|
-
return () => {
|
|
461
|
-
clearInterval(timer);
|
|
462
|
-
};
|
|
463
|
-
}, [refresh, pending]);
|
|
464
|
-
// Its own effect, so the observation is not closed and reopened every time
|
|
465
|
-
// `pending` flips the poll's pace.
|
|
466
288
|
useEffect(() => {
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
if (
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
289
|
+
if (focusId === null) scrolledTo.current = null;
|
|
290
|
+
scrollToFocus();
|
|
291
|
+
}, [focusId, scrollToFocus]);
|
|
292
|
+
const onPlaced = useCallback(
|
|
293
|
+
function onPlaced(agentId: string, y: number) {
|
|
294
|
+
placed.current.set(agentId, y);
|
|
295
|
+
if (agentId === focusId) scrollToFocus();
|
|
296
|
+
},
|
|
297
|
+
[focusId, scrollToFocus],
|
|
298
|
+
);
|
|
299
|
+
const focusGone = focusId !== null && rows !== null && !rows.some((row) => row.agentId === focusId);
|
|
477
300
|
|
|
478
301
|
const openAgent = props.navigation?.openAgent;
|
|
479
302
|
const onOpen = useMemo(
|
|
@@ -497,7 +320,7 @@ export function HeraldSurface(props: PluginSurfaceProps) {
|
|
|
497
320
|
toast.error(errorText(caught));
|
|
498
321
|
}
|
|
499
322
|
},
|
|
500
|
-
[toast],
|
|
323
|
+
[toast, workspaceNames],
|
|
501
324
|
);
|
|
502
325
|
|
|
503
326
|
const onTest = useCallback(
|
|
@@ -570,7 +393,7 @@ export function HeraldSurface(props: PluginSurfaceProps) {
|
|
|
570
393
|
<Pressable
|
|
571
394
|
accessibilityRole="button"
|
|
572
395
|
accessibilityLabel="Refresh"
|
|
573
|
-
onPress={() => void
|
|
396
|
+
onPress={() => void waiting.refetch()}
|
|
574
397
|
style={styles.toolButton}
|
|
575
398
|
>
|
|
576
399
|
<Icon name="RefreshCw" size={14} color={foreground} />
|
|
@@ -587,12 +410,13 @@ export function HeraldSurface(props: PluginSurfaceProps) {
|
|
|
587
410
|
)}
|
|
588
411
|
</View>
|
|
589
412
|
{hint === null ? null : <Text style={styles.hint}>{hint}</Text>}
|
|
413
|
+
{focusGone ? <Text style={styles.hint}>That agent is no longer waiting for you.</Text> : null}
|
|
590
414
|
{error === null ? null : (
|
|
591
415
|
<View style={styles.banner}>
|
|
592
416
|
<Text style={styles.bannerText}>{error}</Text>
|
|
593
417
|
</View>
|
|
594
418
|
)}
|
|
595
|
-
<ScrollView contentContainerStyle={styles.list}>
|
|
419
|
+
<ScrollView ref={scrollRef} contentContainerStyle={styles.list}>
|
|
596
420
|
{rows === null ? (
|
|
597
421
|
<View style={styles.empty}>
|
|
598
422
|
<ActivityIndicator color={props.theme.colors.foregroundMuted} />
|
|
@@ -610,11 +434,13 @@ export function HeraldSurface(props: PluginSurfaceProps) {
|
|
|
610
434
|
<RowCard
|
|
611
435
|
key={row.agentId}
|
|
612
436
|
row={row}
|
|
613
|
-
|
|
437
|
+
title={rowTitle(row, workspaceNames)}
|
|
438
|
+
focused={row.agentId === focusId}
|
|
614
439
|
props={props}
|
|
615
440
|
styles={styles}
|
|
616
441
|
onOpen={onOpen}
|
|
617
442
|
onSpeak={onSpeak}
|
|
443
|
+
onPlaced={onPlaced}
|
|
618
444
|
/>
|
|
619
445
|
))
|
|
620
446
|
)}
|
package/client/rows.ts
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Who is waiting, as rows: Paseo's attention list joined with Herald's
|
|
3
|
+
* entries, and how a row is named and drawn. Pure — the screen, the sidebar
|
|
4
|
+
* row's badge and its popover all read the same join, so they cannot disagree
|
|
5
|
+
* about the count.
|
|
6
|
+
*/
|
|
7
|
+
import type { PluginTheme } from "@getpaseo/plugin";
|
|
8
|
+
|
|
9
|
+
import type { AttentionEntry, AttentionReason } from "../shared/herald";
|
|
10
|
+
|
|
11
|
+
/** A row's reason: one of Herald's, or "attention" when only Paseo's flag is known. */
|
|
12
|
+
export type RowReason = AttentionReason | "attention";
|
|
13
|
+
|
|
14
|
+
export interface Row {
|
|
15
|
+
agentId: string;
|
|
16
|
+
title: string | null;
|
|
17
|
+
workspaceId: string | null;
|
|
18
|
+
cwd: string;
|
|
19
|
+
reason: RowReason;
|
|
20
|
+
/** ISO time the row sorts by: the event, or when Paseo flagged the agent. */
|
|
21
|
+
at: string;
|
|
22
|
+
entry: AttentionEntry | null;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** The fields the join reads off a Paseo agent snapshot. */
|
|
26
|
+
export interface FlaggedAgent {
|
|
27
|
+
id: string;
|
|
28
|
+
title: string | null;
|
|
29
|
+
workspaceId: string | null;
|
|
30
|
+
cwd: string;
|
|
31
|
+
status: string;
|
|
32
|
+
attentionReason: "finished" | "error" | "permission" | null;
|
|
33
|
+
at: string;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* A Paseo-flagged agent worth a row: one whose session is still open. Paseo
|
|
38
|
+
* keeps an agent flagged until the user's next message, however long ago the
|
|
39
|
+
* turn ended, and that is right — a question asked a week ago is still
|
|
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.
|
|
44
|
+
*/
|
|
45
|
+
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;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* 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`.
|
|
56
|
+
*/
|
|
57
|
+
export function joinRows(entries: AttentionEntry[], flagged: FlaggedAgent[]): Row[] {
|
|
58
|
+
const byAgent = new Map<string, Row>();
|
|
59
|
+
entries.forEach((entry) => {
|
|
60
|
+
byAgent.set(entry.agentId, {
|
|
61
|
+
agentId: entry.agentId,
|
|
62
|
+
title: entry.agentTitle,
|
|
63
|
+
workspaceId: entry.workspaceId,
|
|
64
|
+
cwd: entry.cwd,
|
|
65
|
+
reason: entry.reason,
|
|
66
|
+
at: entry.createdAt,
|
|
67
|
+
entry,
|
|
68
|
+
});
|
|
69
|
+
});
|
|
70
|
+
flagged.forEach((agent) => {
|
|
71
|
+
if (byAgent.has(agent.id) || !isCurrent(agent)) return;
|
|
72
|
+
byAgent.set(agent.id, {
|
|
73
|
+
agentId: agent.id,
|
|
74
|
+
title: agent.title,
|
|
75
|
+
workspaceId: agent.workspaceId,
|
|
76
|
+
cwd: agent.cwd,
|
|
77
|
+
reason: agent.attentionReason ?? "attention",
|
|
78
|
+
at: agent.at,
|
|
79
|
+
entry: null,
|
|
80
|
+
});
|
|
81
|
+
});
|
|
82
|
+
return [...byAgent.values()].sort((a, b) => b.at.localeCompare(a.at));
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
function basename(path: string): string {
|
|
86
|
+
const parts = path.split("/").filter((part) => part !== "");
|
|
87
|
+
return parts[parts.length - 1] ?? path;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* Agents are usually untitled; the workspace names the work. Paseo's current
|
|
92
|
+
* workspace title first, then the one Herald stored with the entry, then the
|
|
93
|
+
* folder.
|
|
94
|
+
*/
|
|
95
|
+
export function rowTitle(row: Row, workspaceNames: Record<string, string>): string {
|
|
96
|
+
const live = row.workspaceId === null ? undefined : workspaceNames[row.workspaceId];
|
|
97
|
+
return live ?? row.entry?.workspaceTitle ?? basename(row.cwd);
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* The line under the title: the agent's own title or, failing that, what it
|
|
102
|
+
* was last asked — which is what tells two untitled agents in one workspace
|
|
103
|
+
* apart.
|
|
104
|
+
*/
|
|
105
|
+
export function rowSubtitle(row: Row): string | null {
|
|
106
|
+
return row.title?.trim() || row.entry?.lastRequest || null;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
export interface ReasonLook {
|
|
110
|
+
icon: string;
|
|
111
|
+
label: string;
|
|
112
|
+
tone: "accent" | "success" | "warning" | "danger" | "muted";
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
export function lookOf(reason: RowReason): ReasonLook {
|
|
116
|
+
switch (reason) {
|
|
117
|
+
case "question":
|
|
118
|
+
return { icon: "MessageCircle", label: "Question", tone: "accent" };
|
|
119
|
+
case "plan":
|
|
120
|
+
return { icon: "ClipboardList", label: "Plan to approve", tone: "accent" };
|
|
121
|
+
case "permission":
|
|
122
|
+
return { icon: "Shield", label: "Permission", tone: "warning" };
|
|
123
|
+
case "finished":
|
|
124
|
+
return { icon: "Check", label: "Finished", tone: "success" };
|
|
125
|
+
case "error":
|
|
126
|
+
return { icon: "X", label: "Error", tone: "danger" };
|
|
127
|
+
case "canceled":
|
|
128
|
+
return { icon: "Ban", label: "Interrupted", tone: "muted" };
|
|
129
|
+
case "attention":
|
|
130
|
+
return { icon: "Megaphone", label: "Needs you", tone: "accent" };
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
export function toneColor(theme: PluginTheme, tone: ReasonLook["tone"]): string {
|
|
135
|
+
const { colors } = theme;
|
|
136
|
+
switch (tone) {
|
|
137
|
+
case "accent":
|
|
138
|
+
return colors.accent;
|
|
139
|
+
case "success":
|
|
140
|
+
return colors.statusSuccess;
|
|
141
|
+
case "warning":
|
|
142
|
+
return colors.statusWarning;
|
|
143
|
+
case "danger":
|
|
144
|
+
return colors.statusDanger;
|
|
145
|
+
case "muted":
|
|
146
|
+
return colors.foregroundMuted;
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/** `color` at `alpha` (two hex digits), or `fallback` when `color` is not `#rrggbb`. */
|
|
151
|
+
export function withAlpha(color: string, alpha: string, fallback = color): string {
|
|
152
|
+
return /^#[0-9a-fA-F]{6}$/.test(color) ? `${color}${alpha}` : fallback;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
export function relativeTime(iso: string, now = Date.now()): string {
|
|
156
|
+
const seconds = Math.round((now - new Date(iso).getTime()) / 1000);
|
|
157
|
+
if (!Number.isFinite(seconds)) return "";
|
|
158
|
+
if (seconds < 45) return "just now";
|
|
159
|
+
const minutes = Math.round(seconds / 60);
|
|
160
|
+
if (minutes < 60) return `${minutes} min ago`;
|
|
161
|
+
const hours = Math.round(minutes / 60);
|
|
162
|
+
if (hours < 24) return `${hours} h ago`;
|
|
163
|
+
const days = Math.round(hours / 24);
|
|
164
|
+
return days === 1 ? "yesterday" : `${days} days ago`;
|
|
165
|
+
}
|
package/client/screen.ts
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Herald screen's id and its one param. Pure.
|
|
3
|
+
*
|
|
4
|
+
* The id is the sidebar item's too, and is not a free choice: Settings ›
|
|
5
|
+
* Sidebar keys its ordering and hidden state on the item id, and a saved
|
|
6
|
+
* `/plugin/herald/sidebar/herald` link resolves to the screen of the same id,
|
|
7
|
+
* so renaming either loses both.
|
|
8
|
+
*/
|
|
9
|
+
import type { PluginOpenScreenInput, PluginScreenParams } from "@getpaseo/plugin/client";
|
|
10
|
+
|
|
11
|
+
export const HERALD_SCREEN_ID = "herald";
|
|
12
|
+
export const HERALD_TITLE = "Herald";
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* The screen param naming the agent to bring into view, set by the sidebar
|
|
16
|
+
* popover. A param rather than component state so it lives in the screen's URL.
|
|
17
|
+
*/
|
|
18
|
+
export const AGENT_PARAM = "agent";
|
|
19
|
+
|
|
20
|
+
/** The agent the screen's params ask it to focus, or null. */
|
|
21
|
+
export function focusedAgentId(params: PluginScreenParams): string | null {
|
|
22
|
+
const value = params[AGENT_PARAM];
|
|
23
|
+
return value === undefined || value === "" ? null : value;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** Opens the Herald screen, focused on `agentId` when one is given. */
|
|
27
|
+
export function heraldScreenInput(agentId: string | null = null): PluginOpenScreenInput {
|
|
28
|
+
return {
|
|
29
|
+
screenId: HERALD_SCREEN_ID,
|
|
30
|
+
params: agentId === null ? {} : { [AGENT_PARAM]: agentId },
|
|
31
|
+
};
|
|
32
|
+
}
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Herald's row in the sidebar header, and the popover behind its badge.
|
|
3
|
+
*
|
|
4
|
+
* The row opens the Herald screen, as it always has. While anyone is waiting
|
|
5
|
+
* it carries a count, and the count is a button of its own — `SidebarRow`
|
|
6
|
+
* draws `trailing` beside the row's pressable — that opens a list of who is
|
|
7
|
+
* waiting; picking one opens the screen focused on that agent. The popover is
|
|
8
|
+
* given no `navigation`, so it cannot open the agent itself.
|
|
9
|
+
*
|
|
10
|
+
* The count is the screen's own join (`client/waiting.ts`), so the two never
|
|
11
|
+
* disagree, and with both on show they poll once between them.
|
|
12
|
+
*/
|
|
13
|
+
import type { PluginPopoverProps, PluginSidebarItemProps } from "@getpaseo/plugin/client";
|
|
14
|
+
import { Icon } from "@getpaseo/plugin/client/react-native";
|
|
15
|
+
import { SidebarRow } from "@getpaseo/plugin/client/ui";
|
|
16
|
+
import { useMemo } from "react";
|
|
17
|
+
import { Pressable, Text, View } from "react-native";
|
|
18
|
+
|
|
19
|
+
import { lookOf, relativeTime, rowSubtitle, rowTitle, toneColor, withAlpha } from "./rows";
|
|
20
|
+
import { HERALD_SCREEN_ID, heraldScreenInput } from "./screen";
|
|
21
|
+
import { useWaiting, useWaitingNudges } from "./waiting";
|
|
22
|
+
|
|
23
|
+
function waitingLabel(count: number): string {
|
|
24
|
+
return `${count} ${count === 1 ? "agent" : "agents"} waiting for you`;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export function HeraldSidebarItem({ theme, currentScreen, openScreen, openPopover }: PluginSidebarItemProps) {
|
|
28
|
+
const waiting = useWaiting();
|
|
29
|
+
useWaitingNudges();
|
|
30
|
+
const count = waiting.data?.rows.length ?? 0;
|
|
31
|
+
|
|
32
|
+
const styles = useMemo(() => {
|
|
33
|
+
const warning = theme.colors.statusWarning;
|
|
34
|
+
return {
|
|
35
|
+
badge: {
|
|
36
|
+
minWidth: 18,
|
|
37
|
+
paddingHorizontal: 5,
|
|
38
|
+
paddingVertical: 1,
|
|
39
|
+
borderRadius: 9,
|
|
40
|
+
alignItems: "center" as const,
|
|
41
|
+
backgroundColor: withAlpha(warning, "26", theme.colors.surface2),
|
|
42
|
+
},
|
|
43
|
+
badgeText: { color: warning, fontSize: 11, fontWeight: "600" as const },
|
|
44
|
+
};
|
|
45
|
+
}, [theme]);
|
|
46
|
+
|
|
47
|
+
return (
|
|
48
|
+
<SidebarRow
|
|
49
|
+
icon="Megaphone"
|
|
50
|
+
active={currentScreen?.screenId === HERALD_SCREEN_ID}
|
|
51
|
+
trailing={
|
|
52
|
+
count === 0 ? undefined : (
|
|
53
|
+
<Pressable
|
|
54
|
+
accessibilityRole="button"
|
|
55
|
+
accessibilityLabel={`${waitingLabel(count)}. Show them`}
|
|
56
|
+
hitSlop={6}
|
|
57
|
+
onPress={() => openPopover(WaitingPopover)}
|
|
58
|
+
style={styles.badge}
|
|
59
|
+
>
|
|
60
|
+
<Text style={styles.badgeText}>{count}</Text>
|
|
61
|
+
</Pressable>
|
|
62
|
+
)
|
|
63
|
+
}
|
|
64
|
+
onPress={() => openScreen(heraldScreenInput())}
|
|
65
|
+
/>
|
|
66
|
+
);
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** Who is waiting, newest first; a press opens the Herald screen on that agent. */
|
|
70
|
+
function WaitingPopover({ theme, openScreen }: PluginPopoverProps) {
|
|
71
|
+
const waiting = useWaiting();
|
|
72
|
+
const rows = waiting.data?.rows ?? [];
|
|
73
|
+
const workspaceNames = waiting.data?.workspaceNames ?? {};
|
|
74
|
+
|
|
75
|
+
const styles = useMemo(() => {
|
|
76
|
+
const { colors } = theme;
|
|
77
|
+
return {
|
|
78
|
+
heading: { color: colors.foregroundMuted, fontSize: 12, fontWeight: "600" as const },
|
|
79
|
+
row: {
|
|
80
|
+
flexDirection: "row" as const,
|
|
81
|
+
alignItems: "center" as const,
|
|
82
|
+
gap: 10,
|
|
83
|
+
paddingHorizontal: 8,
|
|
84
|
+
paddingVertical: 6,
|
|
85
|
+
borderRadius: 6,
|
|
86
|
+
},
|
|
87
|
+
rowPressed: { backgroundColor: colors.surface2 },
|
|
88
|
+
rowText: { flex: 1, gap: 1 },
|
|
89
|
+
title: { color: colors.foreground, fontSize: 13, fontWeight: "600" as const },
|
|
90
|
+
meta: { color: colors.foregroundMuted, fontSize: 12 },
|
|
91
|
+
empty: { color: colors.foregroundMuted, fontSize: 13, paddingHorizontal: 8, paddingVertical: 6 },
|
|
92
|
+
footer: {
|
|
93
|
+
flexDirection: "row" as const,
|
|
94
|
+
alignItems: "center" as const,
|
|
95
|
+
gap: 8,
|
|
96
|
+
paddingHorizontal: 8,
|
|
97
|
+
paddingVertical: 6,
|
|
98
|
+
marginTop: 4,
|
|
99
|
+
borderTopWidth: 1,
|
|
100
|
+
borderTopColor: colors.border,
|
|
101
|
+
},
|
|
102
|
+
footerText: { color: colors.accent, fontSize: 13 },
|
|
103
|
+
};
|
|
104
|
+
}, [theme]);
|
|
105
|
+
|
|
106
|
+
return (
|
|
107
|
+
<View style={{ gap: 2 }}>
|
|
108
|
+
<Text style={styles.heading}>{rows.length === 0 ? "Herald" : waitingLabel(rows.length)}</Text>
|
|
109
|
+
{rows.length === 0 ? <Text style={styles.empty}>Nothing needs you right now.</Text> : null}
|
|
110
|
+
{rows.map((row) => {
|
|
111
|
+
const look = lookOf(row.reason);
|
|
112
|
+
const color = toneColor(theme, look.tone);
|
|
113
|
+
const title = rowTitle(row, workspaceNames);
|
|
114
|
+
const subtitle = rowSubtitle(row);
|
|
115
|
+
return (
|
|
116
|
+
<Pressable
|
|
117
|
+
key={row.agentId}
|
|
118
|
+
accessibilityRole="button"
|
|
119
|
+
accessibilityLabel={`${look.label}: ${title}`}
|
|
120
|
+
onPress={() => openScreen(heraldScreenInput(row.agentId))}
|
|
121
|
+
style={({ pressed }) => [styles.row, pressed ? styles.rowPressed : null]}
|
|
122
|
+
>
|
|
123
|
+
<Icon name={look.icon} size={14} color={color} />
|
|
124
|
+
<View style={styles.rowText}>
|
|
125
|
+
<Text style={styles.title} numberOfLines={1}>
|
|
126
|
+
{title}
|
|
127
|
+
</Text>
|
|
128
|
+
<Text style={styles.meta} numberOfLines={1}>
|
|
129
|
+
{subtitle === null ? look.label : `${look.label} · ${subtitle}`}
|
|
130
|
+
</Text>
|
|
131
|
+
</View>
|
|
132
|
+
<Text style={styles.meta}>{relativeTime(row.at)}</Text>
|
|
133
|
+
</Pressable>
|
|
134
|
+
);
|
|
135
|
+
})}
|
|
136
|
+
<Pressable
|
|
137
|
+
accessibilityRole="button"
|
|
138
|
+
onPress={() => openScreen(heraldScreenInput())}
|
|
139
|
+
style={({ pressed }) => [styles.footer, pressed ? styles.rowPressed : null]}
|
|
140
|
+
>
|
|
141
|
+
<Icon name="Megaphone" size={14} color={theme.colors.accent} />
|
|
142
|
+
<Text style={styles.footerText}>Open Herald</Text>
|
|
143
|
+
</Pressable>
|
|
144
|
+
</View>
|
|
145
|
+
);
|
|
146
|
+
}
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The waiting list, loaded once for everything that draws it: the screen, the
|
|
3
|
+
* sidebar row's badge and the row's popover. One query key, so with the
|
|
4
|
+
* screen open beside the sidebar they poll once between them.
|
|
5
|
+
*
|
|
6
|
+
* Async **function expressions**, never async arrows, and no closure in a
|
|
7
|
+
* `for…of` body: the app `eval`s the client bundle, and Hermes's eval compiler
|
|
8
|
+
* on iOS and Android gets both wrong.
|
|
9
|
+
*/
|
|
10
|
+
import { usePaseo, useRpc } from "@getpaseo/plugin/client";
|
|
11
|
+
import { useQuery, useQueryClient } from "@tanstack/react-query";
|
|
12
|
+
import { useEffect } from "react";
|
|
13
|
+
|
|
14
|
+
import { listAttention } from "../shared/herald";
|
|
15
|
+
import { watchAgents } from "./agents";
|
|
16
|
+
import { joinRows, type FlaggedAgent, type Row } from "./rows";
|
|
17
|
+
|
|
18
|
+
export interface Waiting {
|
|
19
|
+
rows: Row[];
|
|
20
|
+
/** Workspace id to its current title, for naming rows. */
|
|
21
|
+
workspaceNames: Record<string, string>;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
const WAITING_QUERY_KEY = ["herald", "waiting"] as const;
|
|
25
|
+
|
|
26
|
+
const IDLE_REFRESH_MS = 10_000;
|
|
27
|
+
const BUSY_REFRESH_MS = 2_500;
|
|
28
|
+
const NUDGE_DEBOUNCE_MS = 400;
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* The last list loaded, so a remount — the screen is unmounted whenever the
|
|
32
|
+
* user opens an agent from it — repaints before the first load answers.
|
|
33
|
+
*
|
|
34
|
+
* Workspace names come from the host API, not `useWorkspace`: the SDK's state
|
|
35
|
+
* hooks are for workspace and agent panels and throw in a screen or a sidebar
|
|
36
|
+
* item ("Plugin state hooks must run inside a workspace panel").
|
|
37
|
+
*/
|
|
38
|
+
let cachedWaiting: Waiting | null = null;
|
|
39
|
+
|
|
40
|
+
function hasPending(waiting: Waiting | undefined): boolean {
|
|
41
|
+
return waiting?.rows.some((row) => row.entry?.summary.status === "pending") ?? false;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Paseo's attention flag decides who is listed — it is what the sidebar
|
|
46
|
+
* badges already follow — and Herald's entries explain why, in a sentence.
|
|
47
|
+
* Polled, and quickened while a summary is being written.
|
|
48
|
+
*/
|
|
49
|
+
export function useWaiting() {
|
|
50
|
+
const paseo = usePaseo();
|
|
51
|
+
const list = useRpc(listAttention);
|
|
52
|
+
return useQuery({
|
|
53
|
+
queryKey: WAITING_QUERY_KEY,
|
|
54
|
+
queryFn: async function loadWaiting(): Promise<Waiting> {
|
|
55
|
+
const [attention, flagged, workspaces] = await Promise.all([
|
|
56
|
+
list({}),
|
|
57
|
+
paseo.agents.list({ filter: { requiresAttention: true }, page: { limit: 100 } }),
|
|
58
|
+
paseo.workspaces.list({ page: { limit: 200 } }),
|
|
59
|
+
]);
|
|
60
|
+
const workspaceNames: Record<string, string> = {};
|
|
61
|
+
workspaces.entries.forEach((workspace) => {
|
|
62
|
+
workspaceNames[workspace.id] = workspace.title ?? workspace.name;
|
|
63
|
+
});
|
|
64
|
+
const agents: FlaggedAgent[] = flagged.entries.map((item) => ({
|
|
65
|
+
id: item.agent.id,
|
|
66
|
+
title: item.agent.title ?? null,
|
|
67
|
+
workspaceId: item.agent.workspaceId ?? null,
|
|
68
|
+
cwd: item.agent.cwd,
|
|
69
|
+
status: item.agent.status,
|
|
70
|
+
attentionReason: item.agent.attentionReason ?? null,
|
|
71
|
+
at: item.agent.attentionTimestamp ?? item.agent.updatedAt,
|
|
72
|
+
}));
|
|
73
|
+
const waiting = { rows: joinRows(attention.entries, agents), workspaceNames };
|
|
74
|
+
cachedWaiting = waiting;
|
|
75
|
+
return waiting;
|
|
76
|
+
},
|
|
77
|
+
refetchInterval: (query) => (hasPending(query.state.data) ? BUSY_REFRESH_MS : IDLE_REFRESH_MS),
|
|
78
|
+
...(cachedWaiting === null ? {} : { placeholderData: cachedWaiting }),
|
|
79
|
+
});
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* Loads the list again within a moment of Paseo reporting any agent change,
|
|
84
|
+
* so a new arrival does not wait for the poll. Opens an agents observation —
|
|
85
|
+
* see `client/agents.ts` — and releases it on unmount.
|
|
86
|
+
*
|
|
87
|
+
* Kept apart from `useWaiting` so the popover, which lives only while it is
|
|
88
|
+
* open under a row that already listens, does not open a second one.
|
|
89
|
+
*/
|
|
90
|
+
export function useWaitingNudges(): void {
|
|
91
|
+
const paseo = usePaseo();
|
|
92
|
+
const queryClient = useQueryClient();
|
|
93
|
+
useEffect(() => {
|
|
94
|
+
let debounce: ReturnType<typeof setTimeout> | null = null;
|
|
95
|
+
const unwatch = watchAgents(paseo, () => {
|
|
96
|
+
if (debounce !== null) clearTimeout(debounce);
|
|
97
|
+
debounce = setTimeout(() => {
|
|
98
|
+
debounce = null;
|
|
99
|
+
// `cancelRefetch: false` joins a load already in flight — the screen
|
|
100
|
+
// and the sidebar row both listen — rather than restarting it.
|
|
101
|
+
void queryClient.invalidateQueries({ queryKey: WAITING_QUERY_KEY }, { cancelRefetch: false });
|
|
102
|
+
}, NUDGE_DEBOUNCE_MS);
|
|
103
|
+
});
|
|
104
|
+
return () => {
|
|
105
|
+
if (debounce !== null) clearTimeout(debounce);
|
|
106
|
+
unwatch();
|
|
107
|
+
};
|
|
108
|
+
}, [paseo, queryClient]);
|
|
109
|
+
}
|
package/index.client.tsx
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
import type { PluginClientContext } from "@getpaseo/plugin/client";
|
|
2
2
|
|
|
3
3
|
import { startAnnouncer } from "./client/announcer";
|
|
4
|
-
import {
|
|
4
|
+
import { HeraldScreen, bindSettingsOpener } from "./client/herald";
|
|
5
|
+
import { HERALD_SCREEN_ID, HERALD_TITLE, heraldScreenInput } from "./client/screen";
|
|
5
6
|
import { HeraldSettingsScreen } from "./client/settings-screen";
|
|
7
|
+
import { HeraldSidebarItem } from "./client/sidebar";
|
|
6
8
|
import { HeraldTimelineCard } from "./client/timeline-card";
|
|
7
9
|
import { HERALD_CARD_KIND, HERALD_CARD_VERSION, HeraldCardSchema } from "./shared/timeline";
|
|
8
10
|
|
|
@@ -11,8 +13,12 @@ export default function contribute(client: PluginClientContext) {
|
|
|
11
13
|
// what speaks. Everything below is how the user sees and tunes it.
|
|
12
14
|
const announcer = startAnnouncer(client);
|
|
13
15
|
|
|
14
|
-
|
|
15
|
-
//
|
|
16
|
+
// The screen and the sidebar row share the id the 0.10 sidebar item had, so
|
|
17
|
+
// Settings › Sidebar keeps the row's place and a saved
|
|
18
|
+
// `/plugin/herald/sidebar/herald` link still opens the screen.
|
|
19
|
+
client.addScreen({ id: HERALD_SCREEN_ID, title: HERALD_TITLE, Component: HeraldScreen });
|
|
20
|
+
client.addSidebarHeaderItem({ id: HERALD_SCREEN_ID, title: HERALD_TITLE, Component: HeraldSidebarItem });
|
|
21
|
+
// The screen's own settings button. A screen is given no way to open a
|
|
16
22
|
// settings screen, so the capability is lent to it from here.
|
|
17
23
|
bindSettingsOpener((id) => {
|
|
18
24
|
client.openSettings(id);
|
|
@@ -25,12 +31,6 @@ export default function contribute(client: PluginClientContext) {
|
|
|
25
31
|
schema: HeraldCardSchema,
|
|
26
32
|
Component: HeraldTimelineCard,
|
|
27
33
|
});
|
|
28
|
-
client.addSidebarItem({
|
|
29
|
-
id: "herald",
|
|
30
|
-
title: "Herald",
|
|
31
|
-
icon: "Megaphone",
|
|
32
|
-
surface: "herald",
|
|
33
|
-
});
|
|
34
34
|
client.addSettingsScreen({
|
|
35
35
|
id: "herald",
|
|
36
36
|
title: "Herald",
|
|
@@ -43,8 +43,8 @@ export default function contribute(client: PluginClientContext) {
|
|
|
43
43
|
icon: "Megaphone",
|
|
44
44
|
keywords: ["herald", "attention", "waiting", "needs you", "speak", "voice"],
|
|
45
45
|
context: "global",
|
|
46
|
-
onSelect({
|
|
47
|
-
|
|
46
|
+
onSelect({ openScreen }) {
|
|
47
|
+
openScreen(heraldScreenInput());
|
|
48
48
|
},
|
|
49
49
|
});
|
|
50
50
|
client.addCommandCenterItem({
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gpambrozio/paseo-herald",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.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",
|
|
@@ -29,9 +29,10 @@
|
|
|
29
29
|
"test": "vitest run --passWithNoTests"
|
|
30
30
|
},
|
|
31
31
|
"devDependencies": {
|
|
32
|
-
"@getpaseo/client": "0.
|
|
33
|
-
"@getpaseo/plugin": "0.
|
|
34
|
-
"@getpaseo/protocol": "0.
|
|
32
|
+
"@getpaseo/client": "0.11.0",
|
|
33
|
+
"@getpaseo/plugin": "0.11.0",
|
|
34
|
+
"@getpaseo/protocol": "0.11.0",
|
|
35
|
+
"@tanstack/react-query": "^5.104.1",
|
|
35
36
|
"@types/node": "^26.5.0",
|
|
36
37
|
"@types/react": "~19.2.0",
|
|
37
38
|
"react": "19.1.0",
|