@xiangyixie/dsh-superagent 0.9.3 → 0.11.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 +210 -0
- package/LICENSE +21 -21
- package/README.md +422 -42
- package/bin/archive.js +185 -0
- package/bin/doctor.js +84 -0
- package/bin/report.js +79 -79
- package/bin/watch.js +57 -57
- package/cordis.patch.yml +9 -9
- package/lib/control.js +495 -494
- package/lib/cost.js +267 -0
- package/lib/doctor.js +876 -0
- package/lib/errors.js +205 -199
- package/lib/index.js +767 -42
- package/lib/ledger.js +270 -0
- package/lib/lock.js +107 -0
- package/lib/memory.js +736 -0
- package/lib/notify.js +257 -0
- package/lib/orchestrator.js +1975 -127
- package/lib/report.js +350 -15
- package/lib/store.js +503 -15
- package/lib/templates.js +690 -0
- package/lib/usage.js +152 -152
- package/lib/watch.js +422 -70
- package/lib/workspace.js +433 -0
- package/package.json +16 -3
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
|
+
}
|