@xiangyixie/dsh-superagent 0.9.2 → 0.10.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/lib/notify.js ADDED
@@ -0,0 +1,257 @@
1
+ /**
2
+ * Proactive-notification policy: quiet unless the user needs to hear it.
3
+ *
4
+ * A long-horizon run is allowed to interrupt the session only when it finished
5
+ * work (delivered), failed, or stopped half-way (partial/interrupted). A run the
6
+ * user cancelled is never announced — the caller already knows. Progress is not
7
+ * announced at all: it lives in the run record, `superagent_status`, the watch
8
+ * panel, and the report page.
9
+ *
10
+ * A fixed hourly window caps how many messages can be sent. Runs that arrive
11
+ * after the cap are buffered and folded into the next message as one summary,
12
+ * so a burst of six failures does not become six wake-ups.
13
+ *
14
+ * The counter is a small JSON file under the state directory, changed under a
15
+ * file lock and written through a temp file. Two hosts sharing a state
16
+ * directory therefore count into the same bucket. If the lock cannot be taken
17
+ * the decision is still made without it: a duplicated message is preferable to
18
+ * silently dropping the only notification.
19
+ *
20
+ * @module dsh-superagent/notify
21
+ */
22
+ import fsp from 'node:fs/promises'
23
+ import path from 'node:path'
24
+ import { acquireFileLock } from './lock.js'
25
+
26
+ /** Statuses worth waking a session for. `cancelled` is deliberately absent. */
27
+ export const NOTIFY_STATUSES = new Set(['completed', 'failed', 'partial', 'interrupted'])
28
+
29
+ const WINDOW_MS = 60 * 60 * 1000
30
+ const MAX_PENDING = 20
31
+ /** A buffered run is dropped after this many failed deliveries, never sooner. */
32
+ const MAX_FOLD_ATTEMPTS = 3
33
+ const RETRY_CAP_MS = 60 * 1000
34
+
35
+ /**
36
+ * A tiny per-key outbox: one task at a time, in order, with bounded retries.
37
+ *
38
+ * The plugin sends exactly one message per finished run, so "ordering" here
39
+ * means a message for a run cannot overtake an earlier message for the same
40
+ * session while that one is still being retried. Tasks for different keys are
41
+ * independent. This is deliberately not a durable queue: the run record is the
42
+ * source of truth, and an undelivered message is reported on the run, not
43
+ * replayed after a restart.
44
+ *
45
+ * @param {object} [options] - retry policy.
46
+ * @param {number} [options.retries] - extra attempts after the first; 0 means one attempt.
47
+ * @param {number} [options.delayMs] - first delay; it doubles per attempt.
48
+ * @param {(ms: number) => Promise<void>} [options.sleep] - clock, injectable for tests.
49
+ */
50
+ export function createOutbox({
51
+ retries = 2,
52
+ delayMs = 2000,
53
+ sleep = ms => new Promise(resolve => setTimeout(resolve, ms)),
54
+ } = {}) {
55
+ const tails = new Map()
56
+
57
+ function backoff(attempt) {
58
+ const base = Number.isFinite(delayMs) ? Math.max(0, delayMs) : 0
59
+ return Math.min(RETRY_CAP_MS, base * 2 ** Math.max(0, attempt - 1))
60
+ }
61
+
62
+ return {
63
+ /**
64
+ * Run `task` after every earlier task for `key` has settled.
65
+ *
66
+ * @template T
67
+ * @param {string} key - ordering key, normally the parent session id.
68
+ * @param {() => Promise<T>} task - delivery attempt.
69
+ * @returns {Promise<T>} the task result, or the last error after retries.
70
+ */
71
+ enqueue(key, task) {
72
+ const previous = tails.get(key) ?? Promise.resolve()
73
+ const run = previous.catch(() => {}).then(async () => {
74
+ let lastError
75
+ for (let attempt = 1; attempt <= retries + 1; attempt++) {
76
+ try {
77
+ return await task()
78
+ } catch (error) {
79
+ lastError = error
80
+ if (attempt <= retries) await sleep(backoff(attempt))
81
+ }
82
+ }
83
+ throw lastError
84
+ })
85
+ const tail = run.catch(() => {})
86
+ tails.set(key, tail)
87
+ // Drop the chain once it is the newest one, so the map tracks in-flight
88
+ // keys only instead of every session the host ever served.
89
+ tail.then(() => {
90
+ if (tails.get(key) === tail) tails.delete(key)
91
+ })
92
+ return run
93
+ },
94
+ }
95
+ }
96
+
97
+
98
+ function emptyState(now) {
99
+ return { windowStart: new Date(now).toISOString(), count: 0, pending: [] }
100
+ }
101
+
102
+ /**
103
+ * One-line description kept for a buffered run. Bounded so the state file
104
+ * cannot grow with the goal text of every run.
105
+ * @param {object} run - finished run.
106
+ */
107
+ function summaryOf(run) {
108
+ const goal = String(run.goal ?? '').replace(/\s+/g, ' ').trim()
109
+ return {
110
+ id: run.id,
111
+ status: run.status,
112
+ goal: [...goal].slice(0, 80).join(''),
113
+ finishedAt: run.finishedAt ?? null,
114
+ }
115
+ }
116
+
117
+ /**
118
+ * Build the policy bound to one state directory.
119
+ *
120
+ * @param {object} options - configuration.
121
+ * @param {string} options.stateFile - path of the counter file.
122
+ * @param {number} [options.maxPerHour] - cap per hourly window; 0 disables it.
123
+ * @param {() => number} [options.now] - clock, injectable for tests.
124
+ * @param {(message: string) => void} [options.warn] - diagnostic sink.
125
+ */
126
+ export function createNotifyPolicy({ stateFile, maxPerHour = 3, now = () => Date.now(), warn = () => {} }) {
127
+ async function readState() {
128
+ try {
129
+ const parsed = JSON.parse(await fsp.readFile(stateFile, 'utf8'))
130
+ if (!parsed || typeof parsed !== 'object') return emptyState(now())
131
+ return {
132
+ windowStart: typeof parsed.windowStart === 'string' ? parsed.windowStart : new Date(now()).toISOString(),
133
+ count: Number.isFinite(parsed.count) ? parsed.count : 0,
134
+ pending: Array.isArray(parsed.pending) ? parsed.pending.filter(item => item && typeof item.id === 'string') : [],
135
+ }
136
+ } catch {
137
+ return emptyState(now())
138
+ }
139
+ }
140
+
141
+ async function writeState(state) {
142
+ const tmp = `${stateFile}.${process.pid}.${Date.now()}.tmp`
143
+ try {
144
+ await fsp.mkdir(path.dirname(stateFile), { recursive: true })
145
+ await fsp.writeFile(tmp, `${JSON.stringify(state, null, 2)}\n`, 'utf8')
146
+ await fsp.rename(tmp, stateFile)
147
+ } catch (error) {
148
+ warn(`cannot persist the notification counter ${stateFile}: ${error?.message ?? error}`)
149
+ try {
150
+ await fsp.unlink(tmp)
151
+ } catch {
152
+ // Nothing to remove.
153
+ }
154
+ }
155
+ }
156
+
157
+ return {
158
+ stateFile,
159
+
160
+ /**
161
+ * Decide whether this run may wake the session, and reserve the slot if so.
162
+ *
163
+ * Reserving before the send means a failed send still consumes budget: the
164
+ * policy errs toward fewer interruptions, never toward a retry storm.
165
+ *
166
+ * @param {object} run - terminal run.
167
+ * @returns {Promise<{ allowed: boolean, reason: string | null, batch: object[] }>}
168
+ */
169
+ async reserve(run) {
170
+ if (!NOTIFY_STATUSES.has(run.status)) {
171
+ return {
172
+ allowed: false,
173
+ reason: `suppressed: a ${run.status} run is not announced; read it with superagent_status or superagent_list`,
174
+ batch: [],
175
+ }
176
+ }
177
+ const release = await acquireFileLock(`${stateFile}.lock`, { now })
178
+ try {
179
+ const state = await readState()
180
+ const started = Date.parse(state.windowStart)
181
+ if (!Number.isFinite(started) || now() - started >= WINDOW_MS) {
182
+ state.windowStart = new Date(now()).toISOString()
183
+ state.count = 0
184
+ }
185
+ if (maxPerHour > 0 && state.count >= maxPerHour) {
186
+ state.pending = [...state.pending, summaryOf(run)].slice(-MAX_PENDING)
187
+ await writeState(state)
188
+ return {
189
+ allowed: false,
190
+ reason: `batched: the limit of ${maxPerHour} proactive message(s) per hour is reached; `
191
+ + `${state.pending.length} run(s) will be folded into the next summary`,
192
+ batch: [],
193
+ }
194
+ }
195
+ state.count += 1
196
+ const batch = state.pending
197
+ state.pending = []
198
+ await writeState(state)
199
+ return { allowed: true, reason: null, batch }
200
+ } finally {
201
+ if (release) await release()
202
+ }
203
+ },
204
+
205
+ /**
206
+ * Put a folded batch back after the message carrying it could not be sent.
207
+ *
208
+ * `reserve` clears the buffer before the send; without this a failed send
209
+ * would drop those runs forever. The batch is deduplicated by run id,
210
+ * bounded by `MAX_PENDING`, and dropped only after `MAX_FOLD_ATTEMPTS`
211
+ * failed deliveries, so a permanently broken session cannot grow the file.
212
+ *
213
+ * @param {object[]} batch - `verdict.batch` from a failed delivery.
214
+ * @returns {Promise<{ restored: number, dropped: number }>}
215
+ */
216
+ async restore(batch) {
217
+ const items = Array.isArray(batch) ? batch.filter(item => item && typeof item.id === 'string') : []
218
+ if (items.length === 0) return { restored: 0, dropped: 0 }
219
+ const release = await acquireFileLock(`${stateFile}.lock`, { now })
220
+ try {
221
+ const state = await readState()
222
+ const present = new Set(state.pending.map(item => item.id))
223
+ let restored = 0
224
+ let dropped = 0
225
+ for (const item of items) {
226
+ if (present.has(item.id)) continue
227
+ const attempts = (Number(item.attempts) || 0) + 1
228
+ if (attempts > MAX_FOLD_ATTEMPTS) {
229
+ dropped++
230
+ continue
231
+ }
232
+ state.pending.push({ ...item, attempts })
233
+ present.add(item.id)
234
+ restored++
235
+ }
236
+ state.pending = state.pending.slice(-MAX_PENDING)
237
+ await writeState(state)
238
+ return { restored, dropped }
239
+ } finally {
240
+ if (release) await release()
241
+ }
242
+ },
243
+
244
+ /**
245
+ * Buffered runs, for `superagent_list`. Reads without reserving anything.
246
+ * @returns {Promise<{ count: number, pending: object[] }>}
247
+ */
248
+ async summary() {
249
+ const state = await readState()
250
+ const started = Date.parse(state.windowStart)
251
+ return {
252
+ count: Number.isFinite(started) && now() - started < WINDOW_MS ? state.count : 0,
253
+ pending: state.pending,
254
+ }
255
+ },
256
+ }
257
+ }