@gpambrozio/paseo-herald 0.5.0 → 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 CHANGED
@@ -7,6 +7,46 @@ 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
+
30
+ ## [0.5.1] — 2026-09-27
31
+
32
+ ### Changed
33
+
34
+ - **Removing Herald no longer deletes its settings and its list.** They used to sit inside the folder
35
+ Paseo installs the plugin into, which Paseo deletes when you remove the plugin. They now live in
36
+ `~/.paseo/plugin-data/herald/`, and Herald moves them there the first time it starts.
37
+
38
+ ### Fixed
39
+
40
+ - **Herald cleans up its summary helpers again on a password-protected Paseo.** Herald removes the
41
+ helper agents it uses to write each announcement, and it did that with whichever `paseo` command
42
+ it found first, which could be an older copy unable to reach Paseo 0.10. The helpers then piled
43
+ up in your agent list. Herald now uses the command that came with the running Paseo first.
44
+ - **Herald notices an agent waiting for you within a moment again.** Since Paseo 0.9, Herald had
45
+ stopped hearing Paseo's live agent updates, so it only found out on its regular check every ten
46
+ seconds: announcements came up to ten seconds late, and the Herald panel was just as slow to add
47
+ or clear an agent. Nothing was missed, only delayed. Herald now listens to Paseo's agent updates
48
+ again, on both the announcements and the panel.
49
+
10
50
  ## [0.5.0] — 2026-09-23
11
51
 
12
52
  ### 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
  ![The Herald panel: three finished agents, each headed by its workspace title with a speaker icon
12
13
  beside it and how long ago it finished, then what the agent was last asked, its own last line, and
@@ -25,7 +26,7 @@ composer sits below it.](docs/timeline-card.png)
25
26
 
26
27
  ## What you need
27
28
 
28
- - Paseo **0.9.0 or newer**, on the daemon and on the device running the app.
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.9 or newer**, which installs plugins straight from npm; add
49
- `@<version>` to pin one. On 0.8, install the last release that supported it from this repository instead:
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
@@ -0,0 +1,85 @@
1
+ /**
2
+ * Hearing Paseo's agent stream at all.
3
+ *
4
+ * Since Paseo 0.9, `paseo.agents.subscribe()` only adds a local listener to
5
+ * observations the same API instance opened with `agents.list({ subscribe })`,
6
+ * and the app's own observations live on another instance — so a bare
7
+ * `subscribe()` hears nothing, ever. This opens that observation.
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
+ *
13
+ * Herald only takes the stream as a nudge to poll sooner; what is listed comes
14
+ * from its own polls. So the snapshot is ignored and asked for one agent long:
15
+ * the daemon filters an observation's updates by its `filter`, not by the page,
16
+ * so every agent's changes still arrive.
17
+ *
18
+ * Paseo re-requests an observation after a reconnect on its own, but releases
19
+ * one whose request fails, silently; that is caught through `error` and the
20
+ * observation is reopened with backoff rather than left deaf.
21
+ */
22
+ import type { PluginClientContext } from "@getpaseo/plugin/client";
23
+
24
+ type Paseo = PluginClientContext["paseo"];
25
+ export type AgentUpdate = Parameters<Parameters<Paseo["agents"]["subscribe"]>[0]>[0];
26
+ type AgentObservation = Awaited<ReturnType<typeof openObservation>>["subscription"];
27
+
28
+ const RETRY_MIN_MS = 2_000;
29
+ const RETRY_MAX_MS = 60_000;
30
+
31
+ function openObservation(paseo: Paseo, signal: AbortSignal) {
32
+ return paseo.agents.list({ subscribe: {}, page: { limit: 1 }, signal });
33
+ }
34
+
35
+ /**
36
+ * Calls `onUpdate` for every agent update the daemon sends, for as long as the
37
+ * returned cleanup has not run. The cleanup releases the observation.
38
+ */
39
+ export function watchAgents(paseo: Paseo, onUpdate: (update: AgentUpdate) => void): () => void {
40
+ const lifetime = new AbortController();
41
+ let observation: AgentObservation | null = null;
42
+ let retry: ReturnType<typeof setTimeout> | null = null;
43
+ let retryDelay = RETRY_MIN_MS;
44
+
45
+ function reopen(error: unknown): void {
46
+ observation = null;
47
+ if (lifetime.signal.aborted || retry !== null) return;
48
+ console.warn("[herald] the agent stream failed; reopening", error);
49
+ retry = setTimeout(() => {
50
+ retry = null;
51
+ open();
52
+ }, retryDelay);
53
+ retryDelay = Math.min(retryDelay * 2, RETRY_MAX_MS);
54
+ }
55
+
56
+ function open(): void {
57
+ openObservation(paseo, lifetime.signal)
58
+ .then(({ subscription }) => {
59
+ if (lifetime.signal.aborted) {
60
+ void subscription.release().catch(() => undefined);
61
+ return;
62
+ }
63
+ observation = subscription;
64
+ subscription.subscribe({
65
+ snapshot() {
66
+ retryDelay = RETRY_MIN_MS;
67
+ },
68
+ update(message) {
69
+ if (message.type === "agent_update") onUpdate(message.payload as AgentUpdate);
70
+ },
71
+ error: reopen,
72
+ });
73
+ })
74
+ .catch(reopen);
75
+ }
76
+
77
+ open();
78
+ return () => {
79
+ lifetime.abort();
80
+ if (retry !== null) clearTimeout(retry);
81
+ retry = null;
82
+ void observation?.release().catch(() => undefined);
83
+ observation = null;
84
+ };
85
+ }
@@ -17,6 +17,7 @@ import type { PluginClientContext } from "@getpaseo/plugin/client";
17
17
 
18
18
  import { listAttention, renderSpeech, type AttentionEntry } from "../shared/herald";
19
19
  import { DEFAULT_SPEECH, speechSettings, type SpeechSettings } from "../shared/settings";
20
+ import { watchAgents } from "./agents";
20
21
  import {
21
22
  canPlayAudio,
22
23
  canSpeak,
@@ -236,7 +237,7 @@ export function startAnnouncer(client: PluginClientContext): Announcer {
236
237
 
237
238
  // Paseo's own stream says an agent needs attention before the summary is
238
239
  // ready; use it to start polling quickly rather than waiting for the tick.
239
- const unsubscribe = client.paseo.agents.subscribe((update) => {
240
+ const unwatch = watchAgents(client.paseo, (update) => {
240
241
  if (update.kind === "upsert" && update.agent.requiresAttention) schedule(BUSY_POLL_MS / 2);
241
242
  });
242
243
 
@@ -244,7 +245,7 @@ export function startAnnouncer(client: PluginClientContext): Announcer {
244
245
  stop() {
245
246
  stopped = true;
246
247
  if (timer !== null) clearTimeout(timer);
247
- unsubscribe();
248
+ unwatch();
248
249
  // A plugin reload starts the replacement announcer at once, so whatever
249
250
  // this one was saying has to stop or the two talk over each other.
250
251
  stopSpeaking();
package/client/herald.tsx CHANGED
@@ -1,32 +1,35 @@
1
1
  /**
2
- * The surface: every agent waiting on the user, each with the sentence Herald
3
- * wrote for it, a button to open the session, and a button to hear it again.
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. Paseo's own attention flag decides who is
6
- * listed — it is what the sidebar badges already follow — and Herald's entries
7
- * explain why, in a sentence. An agent Paseo flags that Herald has no entry
8
- * for (an event before the plugin loaded, say) is still listed, with what Paseo
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 { type PluginSurfaceProps, usePaseo, useRpc } from "@getpaseo/plugin/client";
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
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";
23
26
  import { canPlaySpeech, speechPlatform } from "./web";
24
27
 
25
28
  /**
26
29
  * Opening the settings screen is a `PluginClientContext` capability:
27
- * `PluginSurfaceProps` carries no `openSettings`, so the surface cannot reach
30
+ * `PluginScreenProps` carries no `openSettings`, so the screen cannot reach
28
31
  * its own settings on its own. `index.client.tsx` has the context and hands the
29
- * opener down here at contribution time — which happens before any surface can
32
+ * opener down here at contribution time — which happens before any screen can
30
33
  * mount — and the header button calls it. Module scope belongs to this client's
31
34
  * bundle eval, the same place the other plugins here keep their surface caches.
32
35
  */
@@ -36,151 +39,16 @@ export function bindSettingsOpener(open: ((id: string) => void) | null): void {
36
39
  openSettingsScreen = open;
37
40
  }
38
41
 
39
- /** A row's reason: one of Herald's, or "attention" when only Paseo's flag is known. */
40
- type RowReason = AttentionReason | "attention";
41
-
42
- interface Row {
43
- agentId: string;
44
- title: string | null;
45
- workspaceId: string | null;
46
- cwd: string;
47
- reason: RowReason;
48
- /** ISO time the row sorts by: the event, or when Paseo flagged the agent. */
49
- at: string;
50
- entry: AttentionEntry | null;
51
- }
52
-
53
- /** The fields this surface reads off a Paseo agent snapshot. */
54
- interface FlaggedAgent {
55
- id: string;
56
- title: string | null;
57
- workspaceId: string | null;
58
- cwd: string;
59
- status: string;
60
- attentionReason: "finished" | "error" | "permission" | null;
61
- at: string;
62
- }
63
-
64
- /**
65
- * A Paseo-flagged agent worth a row: one whose session is still open. Paseo
66
- * keeps an agent flagged until the user's next message, however long ago the
67
- * turn ended, and that is right — a question asked a week ago is still
68
- * unanswered. A *closed* session is not waiting on anyone until it is opened
69
- * again, and a turn reported as finished on an agent that is *running* was
70
- * not the end of anything — some providers say a turn is done and carry on.
71
- * Those two are the cases dropped here.
72
- */
73
- function isCurrent(agent: FlaggedAgent): boolean {
74
- if (agent.status === "closed") return false;
75
- if (agent.attentionReason === "finished" && agent.status === "running") return false;
76
- return true;
77
- }
78
-
79
- /**
80
- * Module-scope caches, because the surface is unmounted whenever the user
81
- * navigates to an agent — which the Open button does — and mounted fresh on
82
- * the way back. The list repaints before the first load answers.
83
- *
84
- * Workspace names come from the host API, not `useWorkspace`: the SDK's state
85
- * hooks are for workspace and agent panels and throw in a sidebar surface
86
- * ("Plugin state hooks must run inside a workspace panel").
87
- */
88
- let cachedRows: Row[] | null = null;
89
- let cachedWorkspaceNames: Record<string, string> = {};
90
-
91
- const IDLE_REFRESH_MS = 10_000;
92
- const BUSY_REFRESH_MS = 2_500;
93
-
94
42
  const TEST_SENTENCE = "This is Herald. Your agents will be announced like this.";
95
43
 
96
- function withAlpha(color: string, alpha: string): string {
97
- return /^#[0-9a-fA-F]{6}$/.test(color) ? `${color}${alpha}` : color;
98
- }
99
-
100
- function relativeTime(iso: string): string {
101
- const seconds = Math.round((Date.now() - new Date(iso).getTime()) / 1000);
102
- if (!Number.isFinite(seconds)) return "";
103
- if (seconds < 45) return "just now";
104
- const minutes = Math.round(seconds / 60);
105
- if (minutes < 60) return `${minutes} min ago`;
106
- const hours = Math.round(minutes / 60);
107
- if (hours < 24) return `${hours} h ago`;
108
- const days = Math.round(hours / 24);
109
- return days === 1 ? "yesterday" : `${days} days ago`;
110
- }
111
-
112
- function basename(path: string): string {
113
- const parts = path.split("/").filter((part) => part !== "");
114
- return parts[parts.length - 1] ?? path;
115
- }
116
-
117
44
  function errorText(error: unknown): string {
118
45
  return error instanceof Error ? error.message : String(error);
119
46
  }
120
47
 
121
- interface ReasonLook {
122
- icon: string;
123
- label: string;
124
- tone: "accent" | "success" | "warning" | "danger" | "muted";
125
- }
126
-
127
- function lookOf(reason: RowReason): ReasonLook {
128
- switch (reason) {
129
- case "question":
130
- return { icon: "MessageCircle", label: "Question", tone: "accent" };
131
- case "plan":
132
- return { icon: "ClipboardList", label: "Plan to approve", tone: "accent" };
133
- case "permission":
134
- return { icon: "Shield", label: "Permission", tone: "warning" };
135
- case "finished":
136
- return { icon: "Check", label: "Finished", tone: "success" };
137
- case "error":
138
- return { icon: "X", label: "Error", tone: "danger" };
139
- case "canceled":
140
- return { icon: "Ban", label: "Interrupted", tone: "muted" };
141
- case "attention":
142
- return { icon: "Megaphone", label: "Needs you", tone: "accent" };
143
- }
144
- }
145
-
146
- /**
147
- * Herald's entries win over Paseo's flags for the same agent, since they carry
148
- * the reason and the sentence. A *finished* entry on an agent that is working
149
- * again is already withheld by the daemon, which knows each entry's agent
150
- * without having to enumerate every running one — see `Liveness`.
151
- */
152
- function joinRows(entries: AttentionEntry[], flagged: FlaggedAgent[]): Row[] {
153
- const byAgent = new Map<string, Row>();
154
- entries.forEach((entry) => {
155
- byAgent.set(entry.agentId, {
156
- agentId: entry.agentId,
157
- title: entry.agentTitle,
158
- workspaceId: entry.workspaceId,
159
- cwd: entry.cwd,
160
- reason: entry.reason,
161
- at: entry.createdAt,
162
- entry,
163
- });
164
- });
165
- flagged.forEach((agent) => {
166
- if (byAgent.has(agent.id) || !isCurrent(agent)) return;
167
- byAgent.set(agent.id, {
168
- agentId: agent.id,
169
- title: agent.title,
170
- workspaceId: agent.workspaceId,
171
- cwd: agent.cwd,
172
- reason: agent.attentionReason ?? "attention",
173
- at: agent.at,
174
- entry: null,
175
- });
176
- });
177
- return [...byAgent.values()].sort((a, b) => b.at.localeCompare(a.at));
178
- }
179
-
180
48
  // ---------------------------------------------------------------------------
181
49
  // Styles
182
50
 
183
- function useStyles({ theme, layout }: PluginSurfaceProps) {
51
+ function useStyles({ theme, layout }: PluginScreenProps) {
184
52
  return useMemo(() => {
185
53
  const { colors } = theme;
186
54
  const separator = withAlpha(colors.foregroundMuted, "33");
@@ -264,6 +132,7 @@ function useStyles({ theme, layout }: PluginSurfaceProps) {
264
132
  pending: { flexDirection: "row" as const, alignItems: "center" as const, gap: 8 },
265
133
  pendingText: { color: colors.foregroundMuted, fontSize: 13 },
266
134
  cardPressed: { backgroundColor: colors.surface2 },
135
+ cardFocused: { borderColor: colors.accent },
267
136
  speaker: { padding: 4 },
268
137
  };
269
138
  }, [theme, layout.compact]);
@@ -271,32 +140,20 @@ function useStyles({ theme, layout }: PluginSurfaceProps) {
271
140
 
272
141
  type Styles = ReturnType<typeof useStyles>;
273
142
 
274
- function toneColor(theme: PluginSurfaceProps["theme"], tone: ReasonLook["tone"]): string {
275
- const { colors } = theme;
276
- switch (tone) {
277
- case "accent":
278
- return colors.accent;
279
- case "success":
280
- return colors.statusSuccess;
281
- case "warning":
282
- return colors.statusWarning;
283
- case "danger":
284
- return colors.statusDanger;
285
- case "muted":
286
- return colors.foregroundMuted;
287
- }
288
- }
289
-
290
143
  // ---------------------------------------------------------------------------
291
144
  // Rows
292
145
 
293
146
  interface RowCardProps {
294
147
  row: Row;
295
- workspaceName: string | null;
296
- props: PluginSurfaceProps;
148
+ title: string;
149
+ /** The agent the screen was opened on, from the sidebar popover. */
150
+ focused: boolean;
151
+ props: PluginScreenProps;
297
152
  styles: Styles;
298
153
  onOpen: ((agentId: string) => void) | null;
299
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;
300
157
  }
301
158
 
302
159
  /**
@@ -304,16 +161,12 @@ interface RowCardProps {
304
161
  * the sentence again — beside the title, not at the card's edge, so it is seen. Nested pressables: the speaker takes the touch
305
162
  * and the card does not also open.
306
163
  */
307
- function RowCard({ row, workspaceName, props, styles, onOpen, onSpeak }: RowCardProps) {
164
+ function RowCard({ row, title, focused, props, styles, onOpen, onSpeak, onPlaced }: RowCardProps) {
308
165
  const look = lookOf(row.reason);
309
166
  const color = toneColor(props.theme, look.tone);
310
167
  const muted = props.theme.colors.foregroundMuted;
311
168
  const entry = row.entry;
312
- // Agents are usually untitled; the workspace names the work. Under it, the
313
- // agent's own title or, failing that, what it was last asked — which is
314
- // what tells two untitled agents in one workspace apart.
315
- const title = workspaceName ?? entry?.workspaceTitle ?? basename(row.cwd);
316
- const subtitle = row.title?.trim() || entry?.lastRequest || null;
169
+ const subtitle = rowSubtitle(row);
317
170
  const spoken = entry === null ? null : speechText(entry);
318
171
  // Hidden outright where nothing can play it, rather than offered and failing.
319
172
  const canSpeakRow = canPlaySpeech() && (entry === null || spoken !== null);
@@ -347,7 +200,12 @@ function RowCard({ row, workspaceName, props, styles, onOpen, onSpeak }: RowCard
347
200
  accessibilityLabel={`Open ${title}`}
348
201
  disabled={onOpen === null}
349
202
  onPress={onOpen === null ? undefined : () => onOpen(row.agentId)}
350
- style={({ pressed }) => [styles.card, pressed ? styles.cardPressed : null]}
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
+ ]}
351
209
  >
352
210
  <View style={styles.cardTop}>
353
211
  <View style={[styles.reasonPill, { backgroundColor: withAlpha(color, "22") }]}>
@@ -397,76 +255,48 @@ function RowCard({ row, workspaceName, props, styles, onOpen, onSpeak }: RowCard
397
255
  }
398
256
 
399
257
  // ---------------------------------------------------------------------------
400
- // Surface
258
+ // Screen
401
259
 
402
- export function HeraldSurface(props: PluginSurfaceProps) {
260
+ export function HeraldScreen(props: PluginScreenProps) {
403
261
  const styles = useStyles(props);
404
- const paseo = usePaseo();
405
- const list = useRpc(listAttention);
406
262
  const toast = useToast();
263
+ const waiting = useWaiting();
264
+ useWaitingNudges();
407
265
 
408
- const [rows, setRows] = useState<Row[] | null>(cachedRows);
409
- const [workspaceNames, setWorkspaceNames] = useState<Record<string, string>>(cachedWorkspaceNames);
410
- const [error, setError] = useState<string | null>(null);
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);
411
269
  const [muted, setMuted] = useState(isMutedHere());
412
270
  const [testing, setTesting] = useState(false);
413
- const busyRef = useRef(false);
414
271
 
415
- const refresh = useCallback(
416
- async function refresh() {
417
- if (busyRef.current) return;
418
- busyRef.current = true;
419
- try {
420
- const [attention, flagged, workspaces] = await Promise.all([
421
- list({}),
422
- paseo.agents.list({ filter: { requiresAttention: true }, page: { limit: 100 } }),
423
- paseo.workspaces.list({ page: { limit: 200 } }),
424
- ]);
425
- const names: Record<string, string> = {};
426
- workspaces.entries.forEach((workspace) => {
427
- names[workspace.id] = workspace.title ?? workspace.name;
428
- });
429
- cachedWorkspaceNames = names;
430
- setWorkspaceNames(names);
431
- const agents: FlaggedAgent[] = flagged.entries.map((item) => ({
432
- id: item.agent.id,
433
- title: item.agent.title ?? null,
434
- workspaceId: item.agent.workspaceId ?? null,
435
- cwd: item.agent.cwd,
436
- status: item.agent.status,
437
- attentionReason: item.agent.attentionReason ?? null,
438
- at: item.agent.attentionTimestamp ?? item.agent.updatedAt,
439
- }));
440
- const next = joinRows(attention.entries, agents);
441
- cachedRows = next;
442
- setRows(next);
443
- setError(null);
444
- } catch (caught) {
445
- setError(errorText(caught));
446
- } finally {
447
- busyRef.current = false;
448
- }
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 });
449
285
  },
450
- [list, paseo],
286
+ [focusId],
451
287
  );
452
-
453
- // A poll, quickened while a summary is being written, plus a nudge from
454
- // Paseo's own agent stream so a new arrival shows within a moment.
455
- const pending = rows?.some((row) => row.entry?.summary.status === "pending") ?? false;
456
288
  useEffect(() => {
457
- void refresh();
458
- const timer = setInterval(() => void refresh(), pending ? BUSY_REFRESH_MS : IDLE_REFRESH_MS);
459
- let debounce: ReturnType<typeof setTimeout> | null = null;
460
- const unsubscribe = paseo.agents.subscribe(() => {
461
- if (debounce !== null) clearTimeout(debounce);
462
- debounce = setTimeout(() => void refresh(), 400);
463
- });
464
- return () => {
465
- clearInterval(timer);
466
- if (debounce !== null) clearTimeout(debounce);
467
- unsubscribe();
468
- };
469
- }, [refresh, pending, paseo]);
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);
470
300
 
471
301
  const openAgent = props.navigation?.openAgent;
472
302
  const onOpen = useMemo(
@@ -490,7 +320,7 @@ export function HeraldSurface(props: PluginSurfaceProps) {
490
320
  toast.error(errorText(caught));
491
321
  }
492
322
  },
493
- [toast],
323
+ [toast, workspaceNames],
494
324
  );
495
325
 
496
326
  const onTest = useCallback(
@@ -563,7 +393,7 @@ export function HeraldSurface(props: PluginSurfaceProps) {
563
393
  <Pressable
564
394
  accessibilityRole="button"
565
395
  accessibilityLabel="Refresh"
566
- onPress={() => void refresh()}
396
+ onPress={() => void waiting.refetch()}
567
397
  style={styles.toolButton}
568
398
  >
569
399
  <Icon name="RefreshCw" size={14} color={foreground} />
@@ -580,12 +410,13 @@ export function HeraldSurface(props: PluginSurfaceProps) {
580
410
  )}
581
411
  </View>
582
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}
583
414
  {error === null ? null : (
584
415
  <View style={styles.banner}>
585
416
  <Text style={styles.bannerText}>{error}</Text>
586
417
  </View>
587
418
  )}
588
- <ScrollView contentContainerStyle={styles.list}>
419
+ <ScrollView ref={scrollRef} contentContainerStyle={styles.list}>
589
420
  {rows === null ? (
590
421
  <View style={styles.empty}>
591
422
  <ActivityIndicator color={props.theme.colors.foregroundMuted} />
@@ -603,11 +434,13 @@ export function HeraldSurface(props: PluginSurfaceProps) {
603
434
  <RowCard
604
435
  key={row.agentId}
605
436
  row={row}
606
- workspaceName={row.workspaceId === null ? null : workspaceNames[row.workspaceId] ?? null}
437
+ title={rowTitle(row, workspaceNames)}
438
+ focused={row.agentId === focusId}
607
439
  props={props}
608
440
  styles={styles}
609
441
  onOpen={onOpen}
610
442
  onSpeak={onSpeak}
443
+ onPlaced={onPlaced}
611
444
  />
612
445
  ))
613
446
  )}