Open History to see the last commit
1export type ThreadNotificationKind = "input" | "completion";
2
3export interface ThreadNotificationObservation {
4 /** Status and request key, or status and run without a request, while the thread needs attention. */
5 readonly attention: string | null;
6 /** The pending request's id, when it has one; null whenever attention is. */
7 readonly requestId: string | null;
8 /** The thread is idle and its latest run completed. */
9 readonly settled: boolean;
10 /** When the latest run completed, if it did. */
11 readonly completedAt: number | null;
12 /** The latest run answers a background-work progress wake, like a Monitor line. */
13 readonly backgroundWake: boolean;
14}
15
16/** Matches the push relay's completion confirmation: a final wake can start right after a progress wake. */
17export const RELEASED_COMPLETION_GRACE_MS = 5_000;
18
19export function createThreadNotificationGate<Key>(
20 notify: (key: Key, kind: ThreadNotificationKind) => void,
21) {
22 // The newest completion already notified, or deliberately skipped.
23 const handled = new Map<Key, number>();
24 // Wake completions waiting out the grace, by completion time; no timer while paused.
25 const releases = new Map<
26 Key,
27 { readonly at: number; readonly timer: ReturnType<typeof setTimeout> | undefined }
28 >();
29 const release = (key: Key, at: number) => {
30 const timer = setTimeout(() => {
31 releases.delete(key);
32 handled.set(key, at);
33 notify(key, "completion");
34 }, RELEASED_COMPLETION_GRACE_MS);
35 releases.set(key, { at, timer });
36 };
37 const skip = (key: Key, at: number | null) => {
38 if (at !== null && at > (handled.get(key) ?? -Infinity)) handled.set(key, at);
39 };
40 const cancel = (key: Key) => {
41 clearTimeout(releases.get(key)?.timer);
42 releases.delete(key);
43 };
44 // Attention keys with a request id seen since the thread last stopped needing attention.
45 const attended = new Map<Key, Set<string>>();
46 const attend = (
47 key: Key,
48 prior: ThreadNotificationObservation | undefined,
49 next: ThreadNotificationObservation,
50 ): boolean => {
51 if (next.attention === null) {
52 attended.delete(key);
53 return false;
54 }
55 if (next.requestId === null) return next.attention !== prior?.attention;
56 const seen = attended.get(key);
57 if (seen?.has(next.attention)) return false;
58 if (seen) seen.add(next.attention);
59 else attended.set(key, new Set([next.attention]));
60 return true;
61 };
62 return {
63 observe(
64 key: Key,
65 prior: ThreadNotificationObservation | undefined,
66 next: ThreadNotificationObservation,
67 options: { readonly archived: boolean; readonly quiet: boolean },
68 ): void {
69 // The grace survives updates that keep the wake's completion; anything else cancels it.
70 const pending = releases.get(key);
71 if (pending?.at === next.completedAt && !options.archived && !options.quiet) {
72 if (pending.timer === undefined) release(key, pending.at);
73 return;
74 }
75 cancel(key);
76 // The first sighting, archived threads, and stopped or silent runs never notify completion.
77 if (!prior || options.archived || options.quiet) skip(key, next.completedAt);
78 const fresh = attend(key, prior, next);
79 if (!prior || options.archived) return;
80 if (fresh) {
81 notify(key, "input");
82 return;
83 }
84 const at = next.completedAt;
85 if (!next.settled || at === null || at <= (handled.get(key) ?? -Infinity)) return;
86 if (next.backgroundWake) {
87 release(key, at);
88 return;
89 }
90 handled.set(key, at);
91 notify(key, "completion");
92 },
93 /** Stops grace timers while the snapshot is stale; the next observation restarts or drops them. */
94 pause(): void {
95 for (const [key, { at, timer }] of releases) {
96 clearTimeout(timer);
97 releases.set(key, { at, timer: undefined });
98 }
99 },
100 /** Forgets threads that left the snapshot. */
101 retain(keys: ReadonlySet<Key>): void {
102 for (const key of handled.keys()) if (!keys.has(key)) handled.delete(key);
103 for (const key of releases.keys()) if (!keys.has(key)) cancel(key);
104 for (const key of attended.keys()) if (!keys.has(key)) attended.delete(key);
105 },
106 clear(): void {
107 for (const key of releases.keys()) cancel(key);
108 handled.clear();
109 attended.clear();
110 },
111 };
112}