@gpambrozio/paseo-herald 0.2.1
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 +50 -0
- package/LICENSE +21 -0
- package/README.md +102 -0
- package/client/announcer.ts +285 -0
- package/client/herald.tsx +617 -0
- package/client/option-picker.tsx +171 -0
- package/client/prompt-editor.tsx +185 -0
- package/client/settings-screen.tsx +407 -0
- package/client/timeline-card.tsx +146 -0
- package/client/web.ts +255 -0
- package/index.client.tsx +65 -0
- package/index.server.ts +55 -0
- package/package.json +43 -0
- package/paseo-plugin.json +7 -0
- package/server/card.ts +75 -0
- package/server/config.ts +62 -0
- package/server/hooks.ts +372 -0
- package/server/liveness.ts +159 -0
- package/server/say.ts +132 -0
- package/server/sdk-types.ts +24 -0
- package/server/store.ts +194 -0
- package/server/summarize.ts +223 -0
- package/server/timeline.ts +194 -0
- package/server/workspaces.ts +33 -0
- package/shared/herald.ts +234 -0
- package/shared/settings.ts +60 -0
- package/shared/timeline.ts +32 -0
package/server/hooks.ts
ADDED
|
@@ -0,0 +1,372 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where events become entries. Four things every handler here has to get right:
|
|
3
|
+
*
|
|
4
|
+
* 1. **Return fast.** Paseo gives a hook 30 seconds and logs an error past
|
|
5
|
+
* that. A summary can take longer, so it is detached — the handler records
|
|
6
|
+
* a `pending` entry and returns; the summary lands later through the store.
|
|
7
|
+
* 2. **Ignore our own helpers.** The summariser is a visible agent and fires
|
|
8
|
+
* these same hooks. It is known by the id `summarize` reports and by its
|
|
9
|
+
* title, either of which is enough — the id can be missed when `created`
|
|
10
|
+
* fires before `create()` resolves, and the title survives a plugin reload.
|
|
11
|
+
* 3. **Dedupe `turn_ended`.** The docs say a turn id can repeat, and the `top`
|
|
12
|
+
* plugin has seen it fire twice for one turn; a repeat inside the window
|
|
13
|
+
* is dropped rather than summarised twice.
|
|
14
|
+
* 4. **Follow the agent, not the plugin.** An entry lives until the hooks see
|
|
15
|
+
* the agent move on: a new turn, the permission answered, the agent
|
|
16
|
+
* archived. Paseo's own attention flag decides what the panel *lists*.
|
|
17
|
+
*/
|
|
18
|
+
import type { PaseoApi } from "@getpaseo/client";
|
|
19
|
+
import type {
|
|
20
|
+
PluginHookAgent,
|
|
21
|
+
PluginHookContext,
|
|
22
|
+
PluginLifecycleRegistration,
|
|
23
|
+
} from "@getpaseo/plugin/server";
|
|
24
|
+
|
|
25
|
+
import {
|
|
26
|
+
announceKeyFor,
|
|
27
|
+
type AttentionEntry,
|
|
28
|
+
type AttentionReason,
|
|
29
|
+
type HeraldConfig,
|
|
30
|
+
} from "../shared/herald";
|
|
31
|
+
import { publishCard } from "./card";
|
|
32
|
+
import { isAgentRunning } from "./liveness";
|
|
33
|
+
import type { AttentionStore } from "./store";
|
|
34
|
+
import { HELPER_TITLE, type Summary, type SummaryRequest, type SummarizerDeps } from "./summarize";
|
|
35
|
+
import { createWorkspaceTitleLookup, type WorkspaceTitleLookup } from "./workspaces";
|
|
36
|
+
import {
|
|
37
|
+
describePermission,
|
|
38
|
+
fallbackSpeech,
|
|
39
|
+
firstWords,
|
|
40
|
+
lastUserMessage,
|
|
41
|
+
latestOutputText,
|
|
42
|
+
preview,
|
|
43
|
+
} from "./timeline";
|
|
44
|
+
|
|
45
|
+
export interface HookDeps {
|
|
46
|
+
store: AttentionStore;
|
|
47
|
+
readConfig: () => Promise<HeraldConfig>;
|
|
48
|
+
summarize: (request: SummaryRequest, deps: SummarizerDeps) => Promise<Summary>;
|
|
49
|
+
/** The workspace's title, for naming the work; agents are usually untitled. */
|
|
50
|
+
workspaceTitle?: WorkspaceTitleLookup;
|
|
51
|
+
/** Puts the summary card in the agent's transcript; once pending, again when the summary lands. */
|
|
52
|
+
publish?: (paseo: PaseoApi, entry: AttentionEntry, options?: { superseded?: boolean }) => Promise<void>;
|
|
53
|
+
/** Whether a turn is in flight right now; a summary the agent outran is dropped. */
|
|
54
|
+
isRunning?: (paseo: PaseoApi, agentId: string) => Promise<boolean>;
|
|
55
|
+
now?: () => Date;
|
|
56
|
+
/** How many helpers may be writing at once; more agents than this wait their turn. */
|
|
57
|
+
maxConcurrent?: number;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** A second `turn_ended` for the same turn inside this window is a repeat, not a new turn. */
|
|
61
|
+
export const TURN_REPEAT_WINDOW_MS = 15_000;
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* A turn that fails this soon after the user denied a permission *with
|
|
65
|
+
* interrupt* failed because the user stopped it. Claude reports that as an
|
|
66
|
+
* error with a diagnostic for a message; it is not news to announce.
|
|
67
|
+
*/
|
|
68
|
+
export const INTERRUPT_GRACE_MS = 10_000;
|
|
69
|
+
|
|
70
|
+
export function registerHooks(server: PluginLifecycleRegistration, deps: HookDeps): () => void {
|
|
71
|
+
const now = deps.now ?? (() => new Date());
|
|
72
|
+
const maxConcurrent = deps.maxConcurrent ?? 2;
|
|
73
|
+
const workspaceTitle = deps.workspaceTitle ?? createWorkspaceTitleLookup();
|
|
74
|
+
const publish = deps.publish ?? publishCard;
|
|
75
|
+
const isRunning = deps.isRunning ?? isAgentRunning;
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* Whether the agent has carried on since the summary was commissioned, in
|
|
79
|
+
* which case there is nothing to announce.
|
|
80
|
+
*
|
|
81
|
+
* The generation — a turn we saw start — applies to every event. Asking the
|
|
82
|
+
* daemon whether a turn is in flight applies to a *finish* only: an agent
|
|
83
|
+
* waiting on a question, a plan or a permission reports `status: "running"`
|
|
84
|
+
* with the request pending, so asking it here would suppress every one of
|
|
85
|
+
* them, which is the whole point of the plugin.
|
|
86
|
+
*/
|
|
87
|
+
async function outran(
|
|
88
|
+
agentId: string,
|
|
89
|
+
generation: number,
|
|
90
|
+
paseo: PaseoApi,
|
|
91
|
+
askDaemon: boolean,
|
|
92
|
+
): Promise<boolean> {
|
|
93
|
+
if (generationOf(agentId) !== generation) return true;
|
|
94
|
+
if (!askDaemon) return false;
|
|
95
|
+
const running = await isRunning(paseo, agentId);
|
|
96
|
+
// A turn can start while that round trip is in flight, and the snapshot it
|
|
97
|
+
// answers with may predate it.
|
|
98
|
+
return generationOf(agentId) !== generation ? true : running;
|
|
99
|
+
}
|
|
100
|
+
const helpers = new Set<string>();
|
|
101
|
+
const recentTurns = new Map<string, number>();
|
|
102
|
+
const interruptedAt = new Map<string, number>();
|
|
103
|
+
/**
|
|
104
|
+
* Both recording handlers await — the config file, the workspace title — and
|
|
105
|
+
* the agent can move on while they do. Whatever they learned is then about a
|
|
106
|
+
* question already answered or a turn already replied to, and recording it
|
|
107
|
+
* would put a resolved event back on the panel. So each handler takes the
|
|
108
|
+
* agent's generation before its first await and drops out if it moved.
|
|
109
|
+
*/
|
|
110
|
+
const generations = new Map<string, number>();
|
|
111
|
+
/** `${agentId}:${requestId}`, for permissions answered during that window. */
|
|
112
|
+
const resolvedRequests = new Set<string>();
|
|
113
|
+
let running = 0;
|
|
114
|
+
const queue: Array<() => void> = [];
|
|
115
|
+
|
|
116
|
+
function isHelper(agent: PluginHookAgent): boolean {
|
|
117
|
+
return helpers.has(agent.id) || agent.title === HELPER_TITLE;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
function generationOf(agentId: string): number {
|
|
121
|
+
return generations.get(agentId) ?? 0;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/** The agent unmistakably moved on: a new turn, or gone for good. */
|
|
125
|
+
function movedOn(agentId: string): void {
|
|
126
|
+
generations.set(agentId, generationOf(agentId) + 1);
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
function markResolved(key: string): void {
|
|
130
|
+
resolvedRequests.add(key);
|
|
131
|
+
if (resolvedRequests.size > 1000) {
|
|
132
|
+
const oldest = resolvedRequests.values().next();
|
|
133
|
+
if (!oldest.done) resolvedRequests.delete(oldest.value);
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
function isRepeatTurn(agentId: string, turnId: string | null): boolean {
|
|
138
|
+
if (turnId === null) return false;
|
|
139
|
+
const key = `${agentId}:${turnId}`;
|
|
140
|
+
const at = now().getTime();
|
|
141
|
+
for (const [seenKey, seenAt] of recentTurns) {
|
|
142
|
+
if (at - seenAt > TURN_REPEAT_WINDOW_MS) recentTurns.delete(seenKey);
|
|
143
|
+
}
|
|
144
|
+
if (recentTurns.has(key)) return true;
|
|
145
|
+
recentTurns.set(key, at);
|
|
146
|
+
return false;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
/** Runs `task` when a slot is free; the order agents finished in is kept. */
|
|
150
|
+
function schedule(task: () => Promise<void>): void {
|
|
151
|
+
const start = () => {
|
|
152
|
+
running += 1;
|
|
153
|
+
void task().finally(() => {
|
|
154
|
+
running -= 1;
|
|
155
|
+
queue.shift()?.();
|
|
156
|
+
});
|
|
157
|
+
};
|
|
158
|
+
if (running < maxConcurrent) start();
|
|
159
|
+
else queue.push(start);
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
function record(
|
|
163
|
+
agent: PluginHookAgent,
|
|
164
|
+
title: string | null,
|
|
165
|
+
reason: AttentionReason,
|
|
166
|
+
eventId: string,
|
|
167
|
+
requestId: string | null,
|
|
168
|
+
headline: string,
|
|
169
|
+
detail: string | null,
|
|
170
|
+
config: HeraldConfig,
|
|
171
|
+
context: PluginHookContext,
|
|
172
|
+
text: { output: string; lastUser: string | null },
|
|
173
|
+
): void {
|
|
174
|
+
const base: Omit<AttentionEntry, "summary"> = {
|
|
175
|
+
agentId: agent.id,
|
|
176
|
+
workspaceId: agent.workspaceId,
|
|
177
|
+
workspaceTitle: title,
|
|
178
|
+
agentTitle: agent.title,
|
|
179
|
+
lastRequest: text.lastUser === null ? null : preview(text.lastUser),
|
|
180
|
+
cwd: agent.cwd,
|
|
181
|
+
reason,
|
|
182
|
+
eventId,
|
|
183
|
+
requestId,
|
|
184
|
+
createdAt: now().toISOString(),
|
|
185
|
+
headline,
|
|
186
|
+
detail,
|
|
187
|
+
};
|
|
188
|
+
if (!config.announce[announceKeyFor(reason)]) {
|
|
189
|
+
// Switched off: listed in the panel, no summary, no card in the transcript.
|
|
190
|
+
deps.store.upsert({ ...base, summary: { status: "off", fallback: fallbackSpeech(base) } });
|
|
191
|
+
return;
|
|
192
|
+
}
|
|
193
|
+
const paseo: PaseoApi = context.paseo;
|
|
194
|
+
const pending: AttentionEntry = { ...base, summary: { status: "pending" } };
|
|
195
|
+
deps.store.upsert(pending);
|
|
196
|
+
void publish(paseo, pending);
|
|
197
|
+
schedule(async () => {
|
|
198
|
+
// The user may have answered while this waited in the queue. The card
|
|
199
|
+
// was published as pending before queuing, so it has to be completed
|
|
200
|
+
// here or it reads "Writing the summary…" for ever.
|
|
201
|
+
if (deps.store.get(agent.id)?.eventId !== eventId) {
|
|
202
|
+
void publish(paseo, { ...base, summary: { status: "off", fallback: fallbackSpeech(base) } });
|
|
203
|
+
return;
|
|
204
|
+
}
|
|
205
|
+
const generation = generationOf(agent.id);
|
|
206
|
+
let summary: Summary | null = null;
|
|
207
|
+
let failure: string | null = null;
|
|
208
|
+
try {
|
|
209
|
+
summary = await deps.summarize(
|
|
210
|
+
{
|
|
211
|
+
agent: {
|
|
212
|
+
id: agent.id,
|
|
213
|
+
workspaceId: agent.workspaceId,
|
|
214
|
+
workspaceTitle: title,
|
|
215
|
+
cwd: agent.cwd,
|
|
216
|
+
title: agent.title,
|
|
217
|
+
},
|
|
218
|
+
reason,
|
|
219
|
+
headline,
|
|
220
|
+
detail,
|
|
221
|
+
output: text.output,
|
|
222
|
+
lastUser: text.lastUser,
|
|
223
|
+
},
|
|
224
|
+
{
|
|
225
|
+
paseo,
|
|
226
|
+
provider: config.summarizer.provider,
|
|
227
|
+
timeoutMs: config.summarizer.timeoutMs,
|
|
228
|
+
prompt: config.summarizer.prompt,
|
|
229
|
+
onHelperCreated: (helperId) => helpers.add(helperId),
|
|
230
|
+
},
|
|
231
|
+
);
|
|
232
|
+
} catch (error) {
|
|
233
|
+
failure = error instanceof Error ? error.message : String(error);
|
|
234
|
+
console.error(`[herald] summary for agent ${agent.id} failed: ${failure}`);
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
// Checked after the summary rather than before it: writing one takes
|
|
238
|
+
// seconds, and that is the window in which a completion turns out not to
|
|
239
|
+
// have been one. Nothing is said and the card is taken back.
|
|
240
|
+
if (await outran(agent.id, generation, paseo, reason === "finished")) {
|
|
241
|
+
deps.store.removeIf(agent.id, (entry) => entry.eventId === eventId);
|
|
242
|
+
// A complete entry even though it draws nothing: the client validates
|
|
243
|
+
// every card against its schema and would show a placeholder for one
|
|
244
|
+
// missing a summary.
|
|
245
|
+
void publish(paseo, { ...base, summary: { status: "off", fallback: fallbackSpeech(base) } }, {
|
|
246
|
+
superseded: true,
|
|
247
|
+
});
|
|
248
|
+
return;
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
const settled: AttentionEntry =
|
|
252
|
+
summary !== null
|
|
253
|
+
? { ...base, summary: { status: "ready", ...summary } }
|
|
254
|
+
: {
|
|
255
|
+
...base,
|
|
256
|
+
summary: {
|
|
257
|
+
status: "failed",
|
|
258
|
+
error: failure ?? "The summary agent returned nothing.",
|
|
259
|
+
fallback: fallbackSpeech(base),
|
|
260
|
+
},
|
|
261
|
+
};
|
|
262
|
+
deps.store.updateSummary(agent.id, eventId, settled.summary);
|
|
263
|
+
// The card is history and belongs to this event, so it is completed even
|
|
264
|
+
// when the user has already moved on and the store refused.
|
|
265
|
+
void publish(paseo, settled);
|
|
266
|
+
});
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
const unsubscribers = [
|
|
270
|
+
server.on("agent.created", (event) => {
|
|
271
|
+
if (event.agent.title === HELPER_TITLE) helpers.add(event.agent.id);
|
|
272
|
+
}),
|
|
273
|
+
|
|
274
|
+
server.on("agent.permission_requested", async (event, context) => {
|
|
275
|
+
if (isHelper(event.agent)) return;
|
|
276
|
+
const described = describePermission(event.request);
|
|
277
|
+
const generation = generationOf(event.agent.id);
|
|
278
|
+
const key = `${event.agent.id}:${event.request.id}`;
|
|
279
|
+
const [config, title] = await Promise.all([
|
|
280
|
+
deps.readConfig(),
|
|
281
|
+
workspaceTitle(event.agent.workspaceId, context.paseo),
|
|
282
|
+
]);
|
|
283
|
+
if (generationOf(event.agent.id) !== generation || resolvedRequests.has(key)) return;
|
|
284
|
+
record(
|
|
285
|
+
event.agent,
|
|
286
|
+
title,
|
|
287
|
+
described.reason,
|
|
288
|
+
`${event.agent.id}:permission:${event.request.id}`,
|
|
289
|
+
event.request.id,
|
|
290
|
+
described.headline,
|
|
291
|
+
described.detail,
|
|
292
|
+
config,
|
|
293
|
+
context,
|
|
294
|
+
{ output: "", lastUser: null },
|
|
295
|
+
);
|
|
296
|
+
}),
|
|
297
|
+
|
|
298
|
+
server.on("agent.permission_resolved", (event) => {
|
|
299
|
+
if (isHelper(event.agent)) return;
|
|
300
|
+
deps.store.removeIf(event.agent.id, (entry) => entry.requestId === event.requestId);
|
|
301
|
+
markResolved(`${event.agent.id}:${event.requestId}`);
|
|
302
|
+
if (event.resolution.behavior === "deny" && event.resolution.interrupt === true) {
|
|
303
|
+
interruptedAt.set(event.agent.id, now().getTime());
|
|
304
|
+
}
|
|
305
|
+
}),
|
|
306
|
+
|
|
307
|
+
server.on("agent.turn_started", (event) => {
|
|
308
|
+
if (isHelper(event.agent)) return;
|
|
309
|
+
movedOn(event.agent.id);
|
|
310
|
+
deps.store.remove(event.agent.id);
|
|
311
|
+
}),
|
|
312
|
+
|
|
313
|
+
server.on("agent.turn_ended", async (event, context) => {
|
|
314
|
+
if (isHelper(event.agent)) return;
|
|
315
|
+
if (isRepeatTurn(event.agent.id, event.turnId)) return;
|
|
316
|
+
const generation = generationOf(event.agent.id);
|
|
317
|
+
const output = latestOutputText(event.timeline);
|
|
318
|
+
let reason: AttentionReason;
|
|
319
|
+
let headline: string;
|
|
320
|
+
switch (event.outcome.kind) {
|
|
321
|
+
case "completed":
|
|
322
|
+
// A turn that produced no words — a compaction, a bare tool run —
|
|
323
|
+
// gives the user nothing to hear.
|
|
324
|
+
if (output === "") return;
|
|
325
|
+
reason = "finished";
|
|
326
|
+
headline = "Finished";
|
|
327
|
+
break;
|
|
328
|
+
case "failed": {
|
|
329
|
+
const stoppedAt = interruptedAt.get(event.agent.id);
|
|
330
|
+
interruptedAt.delete(event.agent.id);
|
|
331
|
+
if (stoppedAt !== undefined && now().getTime() - stoppedAt < INTERRUPT_GRACE_MS) return;
|
|
332
|
+
reason = "error";
|
|
333
|
+
headline = event.outcome.error.message.trim() || "The turn failed";
|
|
334
|
+
break;
|
|
335
|
+
}
|
|
336
|
+
case "canceled":
|
|
337
|
+
reason = "canceled";
|
|
338
|
+
headline = event.outcome.reason.trim() || "The turn was canceled";
|
|
339
|
+
break;
|
|
340
|
+
}
|
|
341
|
+
const [config, title] = await Promise.all([
|
|
342
|
+
deps.readConfig(),
|
|
343
|
+
workspaceTitle(event.agent.workspaceId, context.paseo),
|
|
344
|
+
]);
|
|
345
|
+
if (generationOf(event.agent.id) !== generation) return;
|
|
346
|
+
record(
|
|
347
|
+
event.agent,
|
|
348
|
+
title,
|
|
349
|
+
reason,
|
|
350
|
+
`${event.agent.id}:turn:${event.turnId ?? now().getTime()}`,
|
|
351
|
+
null,
|
|
352
|
+
headline,
|
|
353
|
+
output === "" ? null : firstWords(output, 60),
|
|
354
|
+
config,
|
|
355
|
+
context,
|
|
356
|
+
{ output, lastUser: lastUserMessage(event.timeline) },
|
|
357
|
+
);
|
|
358
|
+
}),
|
|
359
|
+
|
|
360
|
+
server.on("agent.archived", (event) => {
|
|
361
|
+
helpers.delete(event.agent.id);
|
|
362
|
+
interruptedAt.delete(event.agent.id);
|
|
363
|
+
movedOn(event.agent.id);
|
|
364
|
+
deps.store.remove(event.agent.id);
|
|
365
|
+
}),
|
|
366
|
+
];
|
|
367
|
+
|
|
368
|
+
return () => {
|
|
369
|
+
for (const unsubscribe of unsubscribers) unsubscribe();
|
|
370
|
+
queue.length = 0;
|
|
371
|
+
};
|
|
372
|
+
}
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Whether the agent behind an entry is still waiting on the user. The hooks
|
|
3
|
+
* learn that an agent moved on from its own events, but two things fire
|
|
4
|
+
* nothing: a session *closing* (the daemon restarted, the provider went
|
|
5
|
+
* away), and the user *looking* — Paseo clears its `requiresAttention` flag
|
|
6
|
+
* when the agent is viewed or its tab is closed, and that is the signal the
|
|
7
|
+
* panel should follow. So the list RPC asks the daemon about each entry's
|
|
8
|
+
* agent before handing the list out:
|
|
9
|
+
*
|
|
10
|
+
* - **closed** sessions are hidden but kept, because opening the agent again
|
|
11
|
+
* resumes the session and the summary is still the right thing to show;
|
|
12
|
+
* - **seen** agents — no attention flag, no pending permission, and the entry
|
|
13
|
+
* old enough that Paseo has had time to set the flag — are removed; the
|
|
14
|
+
* user has been there;
|
|
15
|
+
* - a **finish** on an agent that is working again is hidden but kept: some
|
|
16
|
+
* providers report a turn as finished and carry on, and the hooks take the
|
|
17
|
+
* entry back for good when its summary lands;
|
|
18
|
+
* - **archived** or **missing** agents are removed, because they never come back.
|
|
19
|
+
*
|
|
20
|
+
* Answers are cached for a short while so the clients' polling does not turn
|
|
21
|
+
* into one daemon fetch per entry per poll.
|
|
22
|
+
*/
|
|
23
|
+
import type { PaseoApi } from "@getpaseo/client";
|
|
24
|
+
|
|
25
|
+
import type { AttentionEntry } from "../shared/herald";
|
|
26
|
+
import type { AttentionStore } from "./store";
|
|
27
|
+
|
|
28
|
+
export const LIVENESS_TTL_MS = 30_000;
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* Paseo sets its flag within milliseconds of the event Herald recorded, but
|
|
32
|
+
* not before; an entry younger than this is never judged "seen".
|
|
33
|
+
*/
|
|
34
|
+
export const SEEN_GRACE_MS = 15_000;
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* How stale a snapshot may be when the question is "is it working right now?".
|
|
38
|
+
* Short, because that is the one fact here that turns over in seconds: a
|
|
39
|
+
* provider can report a turn as finished and carry on.
|
|
40
|
+
*/
|
|
41
|
+
export const RUNNING_TTL_MS = 5_000;
|
|
42
|
+
|
|
43
|
+
type Facts =
|
|
44
|
+
| { kind: "gone" }
|
|
45
|
+
| { kind: "closed" }
|
|
46
|
+
| { kind: "open"; requiresAttention: boolean; pendingPermissions: number; running: boolean };
|
|
47
|
+
|
|
48
|
+
type Verdict = "live" | "closed" | "gone" | "seen" | "working";
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Whether a turn is in flight right now. Uncached and deliberately so: it
|
|
52
|
+
* decides whether a summary just written is still worth saying, and a cached
|
|
53
|
+
* answer from half a minute ago cannot.
|
|
54
|
+
*
|
|
55
|
+
* An agent that cannot be read is reported as not running, so a transport
|
|
56
|
+
* hiccup loses no summary.
|
|
57
|
+
*/
|
|
58
|
+
export async function isAgentRunning(paseo: PaseoApi, agentId: string): Promise<boolean> {
|
|
59
|
+
try {
|
|
60
|
+
const result = await paseo.agents.ref(agentId).refresh();
|
|
61
|
+
if (result === null) return false;
|
|
62
|
+
return result.agent.status === "running" || (result.agent.activeTurn ?? null) !== null;
|
|
63
|
+
} catch (error) {
|
|
64
|
+
console.warn(
|
|
65
|
+
`[herald] could not check whether agent ${agentId} is running:`,
|
|
66
|
+
error instanceof Error ? error.message : error,
|
|
67
|
+
);
|
|
68
|
+
return false;
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
export class Liveness {
|
|
73
|
+
private readonly checked = new Map<string, { at: number; facts: Facts }>();
|
|
74
|
+
|
|
75
|
+
constructor(private readonly now: () => number = Date.now) {}
|
|
76
|
+
|
|
77
|
+
/** The entries a client should see; removes the ones whose agent is gone or has been seen. */
|
|
78
|
+
async visible(store: AttentionStore, paseo: PaseoApi): Promise<AttentionEntry[]> {
|
|
79
|
+
const entries = store.list();
|
|
80
|
+
const verdicts = await Promise.all(entries.map((entry) => this.verdictFor(entry, paseo)));
|
|
81
|
+
const result: AttentionEntry[] = [];
|
|
82
|
+
entries.forEach((entry, index) => {
|
|
83
|
+
switch (verdicts[index]) {
|
|
84
|
+
case "live":
|
|
85
|
+
result.push(entry);
|
|
86
|
+
break;
|
|
87
|
+
case "closed":
|
|
88
|
+
case "working":
|
|
89
|
+
break;
|
|
90
|
+
case "gone":
|
|
91
|
+
case "seen":
|
|
92
|
+
// By event, not by agent: the entries were snapshotted before the
|
|
93
|
+
// daemon checks, and a newer one may have been recorded since.
|
|
94
|
+
store.removeIf(entry.agentId, (current) => current.eventId === entry.eventId);
|
|
95
|
+
break;
|
|
96
|
+
case undefined:
|
|
97
|
+
break;
|
|
98
|
+
}
|
|
99
|
+
});
|
|
100
|
+
return result;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
private async verdictFor(entry: AttentionEntry, paseo: PaseoApi): Promise<Verdict> {
|
|
104
|
+
const createdAt = new Date(entry.createdAt).getTime();
|
|
105
|
+
/**
|
|
106
|
+
* A snapshot older than this — the event, plus the grace Paseo needs to
|
|
107
|
+
* raise its flag — cannot speak for this entry however fresh the cache is.
|
|
108
|
+
*/
|
|
109
|
+
const judgeableFrom = (Number.isFinite(createdAt) ? createdAt : 0) + SEEN_GRACE_MS;
|
|
110
|
+
|
|
111
|
+
// A finish is judged on a snapshot no older than `RUNNING_TTL_MS`: whether
|
|
112
|
+
// the agent is working is the one fact here that turns over in seconds.
|
|
113
|
+
// Every other reason keeps the long cache — an agent waiting on a question
|
|
114
|
+
// or a permission is *running* too, and that is the row worth showing.
|
|
115
|
+
const finished = entry.reason === "finished";
|
|
116
|
+
const cached = await this.factsFor(entry.agentId, paseo, finished ? this.now() - RUNNING_TTL_MS : 0);
|
|
117
|
+
if (cached.kind !== "open") return cached.kind;
|
|
118
|
+
if (finished && cached.running) return "working";
|
|
119
|
+
if (cached.requiresAttention || cached.pendingPermissions > 0) return "live";
|
|
120
|
+
if (this.now() < judgeableFrom) return "live";
|
|
121
|
+
|
|
122
|
+
// About to delete on the strength of a flag that is *absent*, so the
|
|
123
|
+
// snapshot has to be new enough to have carried it. Re-reads only when the
|
|
124
|
+
// cached one predates the event; usually this is the same answer again.
|
|
125
|
+
const facts = await this.factsFor(entry.agentId, paseo, judgeableFrom);
|
|
126
|
+
if (facts.kind !== "open") return facts.kind;
|
|
127
|
+
if (facts.requiresAttention || facts.pendingPermissions > 0) return "live";
|
|
128
|
+
return "seen";
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
private async factsFor(agentId: string, paseo: PaseoApi, notBefore: number): Promise<Facts> {
|
|
132
|
+
const at = this.now();
|
|
133
|
+
const cached = this.checked.get(agentId);
|
|
134
|
+
if (cached !== undefined && at - cached.at < LIVENESS_TTL_MS && cached.at >= notBefore) {
|
|
135
|
+
return cached.facts;
|
|
136
|
+
}
|
|
137
|
+
let facts: Facts;
|
|
138
|
+
try {
|
|
139
|
+
const result = await paseo.agents.ref(agentId).refresh();
|
|
140
|
+
if (result === null || (result.agent.archivedAt ?? null) !== null) facts = { kind: "gone" };
|
|
141
|
+
else if (result.agent.status === "closed") facts = { kind: "closed" };
|
|
142
|
+
else {
|
|
143
|
+
facts = {
|
|
144
|
+
kind: "open",
|
|
145
|
+
requiresAttention: result.agent.requiresAttention === true,
|
|
146
|
+
pendingPermissions: result.agent.pendingPermissions?.length ?? 0,
|
|
147
|
+
running: result.agent.status === "running" || (result.agent.activeTurn ?? null) !== null,
|
|
148
|
+
};
|
|
149
|
+
}
|
|
150
|
+
} catch (error) {
|
|
151
|
+
// Cannot tell right now — a transport hiccup, most likely. Showing an
|
|
152
|
+
// entry that may be stale beats losing one that is not.
|
|
153
|
+
console.warn(`[herald] could not check agent ${agentId}:`, error instanceof Error ? error.message : error);
|
|
154
|
+
facts = { kind: "open", requiresAttention: true, pendingPermissions: 0, running: false };
|
|
155
|
+
}
|
|
156
|
+
this.checked.set(agentId, { at, facts });
|
|
157
|
+
return facts;
|
|
158
|
+
}
|
|
159
|
+
}
|
package/server/say.ts
ADDED
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The daemon Mac's `say`, driven for its voices rather than its speaker: the
|
|
3
|
+
* sentence goes in on stdin, a WAV comes out to a temporary file, and the bytes
|
|
4
|
+
* go back to the app to play. Nothing here plays audio on the daemon.
|
|
5
|
+
*
|
|
6
|
+
* `-f -` reads the text from stdin so it never touches argv, and `[[ … ]]` is
|
|
7
|
+
* stripped first because `say` reads that as embedded speech commands.
|
|
8
|
+
*/
|
|
9
|
+
import { spawn } from "node:child_process";
|
|
10
|
+
import { randomUUID } from "node:crypto";
|
|
11
|
+
import { access, readFile, unlink } from "node:fs/promises";
|
|
12
|
+
import { tmpdir } from "node:os";
|
|
13
|
+
import { join } from "node:path";
|
|
14
|
+
|
|
15
|
+
import type { SpeechVoice } from "../shared/herald";
|
|
16
|
+
|
|
17
|
+
export const SAY_PATH = "/usr/bin/say";
|
|
18
|
+
|
|
19
|
+
/** `say -r` is words per minute; this is roughly what the default voices do unasked. */
|
|
20
|
+
export const DEFAULT_WPM = 175;
|
|
21
|
+
|
|
22
|
+
/** 16 kHz mono 16-bit: clear enough for speech, ~32 KB per second on the wire before base64. */
|
|
23
|
+
const DATA_FORMAT = "LEI16@16000";
|
|
24
|
+
|
|
25
|
+
const RENDER_TIMEOUT_MS = 30_000;
|
|
26
|
+
|
|
27
|
+
export async function sayAvailable(): Promise<boolean> {
|
|
28
|
+
if (process.platform !== "darwin") return false;
|
|
29
|
+
try {
|
|
30
|
+
await access(SAY_PATH);
|
|
31
|
+
return true;
|
|
32
|
+
} catch {
|
|
33
|
+
return false;
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* One voice per line: a name that may hold spaces and parentheses, whitespace,
|
|
39
|
+
* a locale such as `en_US` or `en-scotland`, then `# ` and a sample sentence.
|
|
40
|
+
* The name column is padded to a fixed width, so a long name is followed by a
|
|
41
|
+
* single space — the locale's shape is what marks the boundary, not the gap.
|
|
42
|
+
*/
|
|
43
|
+
export function parseVoiceList(output: string): SpeechVoice[] {
|
|
44
|
+
const voices: SpeechVoice[] = [];
|
|
45
|
+
for (const line of output.split("\n")) {
|
|
46
|
+
const match = /^(\S.*?)\s+([a-z]{2,3}[_-][A-Za-z0-9_-]+)\s+#/.exec(line);
|
|
47
|
+
if (match?.[1] !== undefined && match[2] !== undefined) {
|
|
48
|
+
voices.push({ name: match[1].trim(), lang: match[2] });
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
return voices;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
export interface RenderOptions {
|
|
55
|
+
voice: string;
|
|
56
|
+
rate: number;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
export function sayArguments(options: RenderOptions, outFile: string): string[] {
|
|
60
|
+
const args = ["-o", outFile, "--file-format=WAVE", `--data-format=${DATA_FORMAT}`, "-f", "-"];
|
|
61
|
+
if (options.voice.trim() !== "") args.push("-v", options.voice.trim());
|
|
62
|
+
if (options.rate !== 1) args.push("-r", String(Math.round(DEFAULT_WPM * options.rate)));
|
|
63
|
+
return args;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** Text as `say` should read it: no embedded-command brackets, one line. */
|
|
67
|
+
export function speakable(text: string): string {
|
|
68
|
+
return text.replace(/\[\[|\]\]/g, " ").replace(/\s+/g, " ").trim();
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
interface RunResult {
|
|
72
|
+
code: number | null;
|
|
73
|
+
stdout: string;
|
|
74
|
+
stderr: string;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
function run(args: string[], input: string | null): Promise<RunResult> {
|
|
78
|
+
return new Promise((resolve, reject) => {
|
|
79
|
+
const child = spawn(SAY_PATH, args, { stdio: ["pipe", "pipe", "pipe"] });
|
|
80
|
+
let stdout = "";
|
|
81
|
+
let stderr = "";
|
|
82
|
+
const timer = setTimeout(() => {
|
|
83
|
+
child.kill("SIGKILL");
|
|
84
|
+
reject(new Error(`say did not finish within ${RENDER_TIMEOUT_MS / 1000} seconds`));
|
|
85
|
+
}, RENDER_TIMEOUT_MS);
|
|
86
|
+
child.stdout.setEncoding("utf8").on("data", (chunk: string) => (stdout += chunk));
|
|
87
|
+
child.stderr.setEncoding("utf8").on("data", (chunk: string) => (stderr += chunk));
|
|
88
|
+
child.on("error", (error) => {
|
|
89
|
+
clearTimeout(timer);
|
|
90
|
+
reject(error);
|
|
91
|
+
});
|
|
92
|
+
child.on("close", (code) => {
|
|
93
|
+
clearTimeout(timer);
|
|
94
|
+
resolve({ code, stdout, stderr });
|
|
95
|
+
});
|
|
96
|
+
if (input === null) child.stdin.end();
|
|
97
|
+
else child.stdin.end(input, "utf8");
|
|
98
|
+
});
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
export async function listSayVoices(): Promise<SpeechVoice[]> {
|
|
102
|
+
const result = await run(["-v", "?"], null);
|
|
103
|
+
if (result.code !== 0) throw new Error(`say -v ? failed: ${result.stderr.trim() || `exit ${result.code}`}`);
|
|
104
|
+
return parseVoiceList(result.stdout);
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
export interface RenderedSpeech {
|
|
108
|
+
mimeType: string;
|
|
109
|
+
base64: string;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/**
|
|
113
|
+
* A voice `say` does not know is not an error: it prints a complaint and
|
|
114
|
+
* renders with the Mac's default voice, exit code 0. That is left alone — a
|
|
115
|
+
* voice removed from the daemon should not silence the plugin — and the
|
|
116
|
+
* settings screen marks such a voice as not installed.
|
|
117
|
+
*/
|
|
118
|
+
export async function renderWithSay(text: string, options: RenderOptions): Promise<RenderedSpeech> {
|
|
119
|
+
const spoken = speakable(text);
|
|
120
|
+
if (spoken === "") throw new Error("There is nothing to say.");
|
|
121
|
+
const outFile = join(tmpdir(), `herald-${randomUUID()}.wav`);
|
|
122
|
+
try {
|
|
123
|
+
const result = await run(sayArguments(options, outFile), `${spoken}\n`);
|
|
124
|
+
if (result.code !== 0) {
|
|
125
|
+
throw new Error(`say failed: ${result.stderr.trim() || `exit ${result.code}`}`);
|
|
126
|
+
}
|
|
127
|
+
const bytes = await readFile(outFile);
|
|
128
|
+
return { mimeType: "audio/wav", base64: bytes.toString("base64") };
|
|
129
|
+
} finally {
|
|
130
|
+
await unlink(outFile).catch(() => {});
|
|
131
|
+
}
|
|
132
|
+
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A tripwire for the one hazard `skipLibCheck: true` hides.
|
|
3
|
+
*
|
|
4
|
+
* When `@getpaseo/client` fails to resolve, TypeScript does not complain: every
|
|
5
|
+
* Paseo API type silently degrades to `any` and `tsc` still exits 0, so a clean
|
|
6
|
+
* typecheck stops proving that any host call in this plugin is type-checked at
|
|
7
|
+
* all. `noImplicitAny` catches part of it — but only where our code destructures
|
|
8
|
+
* an SDK value. A handler that merely passes `paseo` through type-checks just as
|
|
9
|
+
* happily against `any`.
|
|
10
|
+
*
|
|
11
|
+
* The directive below is the check, and it fails in both directions:
|
|
12
|
+
*
|
|
13
|
+
* - types resolved → the indexed access errors → the directive is used → pass
|
|
14
|
+
* - types degraded → the access is `any`, no error → TS2578 "Unused
|
|
15
|
+
* '@ts-expect-error' directive" → fail
|
|
16
|
+
*
|
|
17
|
+
* This replaces the throwaway file the root CLAUDE.md used to ask contributors
|
|
18
|
+
* to write by hand. It is type-only, so it contributes nothing to either bundle.
|
|
19
|
+
*/
|
|
20
|
+
import type { PaseoAgentHandle } from "@getpaseo/client";
|
|
21
|
+
|
|
22
|
+
// @ts-expect-error - Must stay an error. See above: if this member ever stops
|
|
23
|
+
// erroring, the SDK types are `any` and nothing here is really being checked.
|
|
24
|
+
export type SdkTypesResolved = PaseoAgentHandle["thisMemberDoesNotExist"];
|