@soffits/dsh-cron-jobs 0.7.0 → 0.7.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/README.md CHANGED
@@ -125,7 +125,7 @@ Next to `jobs`, the row also takes:
125
125
 
126
126
  - One run of a job at a time: if a tick arrives while the previous run is still going, the tick is skipped and logged.
127
127
  - Start, exit status, duration and a short tail of stdout and stderr go to the DSH log under `cron-jobs`. Sending the result anywhere else is what [Result delivery](#result-delivery) is for.
128
- - Set `runLog` (next to `jobs`) to a file path to also keep that record as JSON Lines: one `start` line per run, one `end` line with `status`, `outcome`, `exitCode`, `durationMs`, the output tails and the delivery state, a `delivery` line when a woken agent's answer has been delivered (or not), a `skipped` line for a skipped tick, an `overdue` line (with `dueAt` and `lateMs`) when a tick did not start on time and the watchdog ran it late, and `scheduler-start` / `scheduler-stop` lines (with `job: null`) when the scheduler starts or stops, so a gap in the log can be told apart from a lost tick. A `start` with no `end` means DSH stopped during the run. The file is only appended to; rotate it yourself if it grows.
128
+ - Set `runLog` (next to `jobs`) to a file path to also keep that record as JSON Lines: one `start` line per run, one `end` line with `status`, `outcome`, `exitCode`, `durationMs`, the output tails and the delivery state, a `delivery` line when a result waits for its channel (`waiting`), is left for the next start (`pending`), or has been delivered or not (`sent`, `silent`, `failed`), a `skipped` line for a skipped tick, an `overdue` line (with `dueAt` and `lateMs`) when a tick did not start on time and the watchdog ran it late, and `scheduler-start` / `scheduler-stop` lines (with `job: null`) when the scheduler starts or stops, so a gap in the log can be told apart from a lost tick. A `start` with no `end` means DSH stopped during the run. The file is only appended to; rotate it yourself if it grows.
129
129
  - Ticks of config jobs missed while DSH is down are not caught up; the next tick runs normally. While DSH runs, a watchdog checks every minute that each job's next run is not more than a minute in the past; a tick whose timer was lost runs late instead of being missed. (Jobs created from a conversation catch up once, see below.)
130
130
  - Unloading the plugin (stopping DSH or changing its config) stops the timers and terminates running commands.
131
131
 
@@ -161,7 +161,7 @@ A job with a delivery target sends its result when a run is over:
161
161
 
162
162
  Where results go is decided per job: its own `deliver` (or `false`), otherwise nothing for jobs that post into an existing session (`agent.sessionId`, or the tools' `this_session` / `sessionId`), since the answer is already in that conversation, otherwise the row's `deliver`. A run stopped because DSH is shutting down delivers nothing.
163
163
 
164
- Each run's delivery shows on the Cron tasks page and in the run log: waiting for the answer, sent, nothing to send, or not sent with the reason. The answer of a turn still running when DSH stops is picked up and delivered after the next start.
164
+ Each run's delivery shows on the Cron tasks page and in the run log: not sent yet (waiting for the answer or for the channel), sent, nothing to send, or not sent with the reason. A delivery still waiting when DSH stops or the plugin reloads, whether for a turn that is still running or for a channel that is not there, is picked up and delivered after the next start.
165
165
 
166
166
  ### Answer checks
167
167
 
@@ -187,7 +187,7 @@ await service.send({
187
187
  })
188
188
  ```
189
189
 
190
- The promise resolves when the message is sent and rejects with an `Error` when it is not. A rejected send is tried again twice (after 5 and 30 seconds), as is a service that is not running at that moment (for example while its plugin reloads). Set `retryable: false` on the error to stop the retries for a failure that will not go away, such as an unknown address. The return value is ignored. A send that still fails is recorded in the run's history and the run log; the job itself carries on.
190
+ The promise resolves when the message is sent and rejects with an `Error` when it is not. A rejected send is tried again twice (after 5 and 30 seconds). A service that is not running (for example while its plugin reloads or is stuck unloading) is not a failed try: the delivery waits for it, looking again every 10 seconds for up to an hour, and a restart in that time leaves it pending for the next start, which waits again. Set `retryable: false` on the error to stop the retries for a failure that will not go away, such as an unknown address. The return value is ignored. A send that still fails is recorded in the run's history and the run log; the job itself carries on.
191
191
 
192
192
  To make a plugin a delivery channel, provide a service with that method:
193
193
 
package/client.js CHANGED
@@ -10,7 +10,7 @@
10
10
  * tokens (--dsw-*). Icon paths are copied from DSH's icon set (MIT).
11
11
  */
12
12
  window.__ModuleLoader__.load({
13
- id: 'dsh-cron-jobs',
13
+ id: '@soffits/dsh-cron-jobs',
14
14
  factory(require) {
15
15
  const React = require('react')
16
16
  const h = React.createElement
@@ -128,7 +128,7 @@ window.__ModuleLoader__.load({
128
128
  'field.deliverOff': 'Nothing: turned off for this job',
129
129
  'field.deliverSession': 'Nothing: the answer stays in its session',
130
130
  'field.deliverUnset': 'Nothing',
131
- 'delivery.pending': 'result: waiting for the answer',
131
+ 'delivery.pending': 'result: not sent yet',
132
132
  'delivery.sent': 'result sent',
133
133
  'delivery.silent': 'nothing to send',
134
134
  'delivery.failed': 'result not sent',
@@ -259,7 +259,7 @@ window.__ModuleLoader__.load({
259
259
  'field.deliverOff': '不发送:此任务已关闭',
260
260
  'field.deliverSession': '不发送:回答留在它的会话里',
261
261
  'field.deliverUnset': '不发送',
262
- 'delivery.pending': '结果:等待回答',
262
+ 'delivery.pending': '结果:尚未发送',
263
263
  'delivery.sent': '结果已发送',
264
264
  'delivery.silent': '无需发送',
265
265
  'delivery.failed': '结果未发送',
package/index.js CHANGED
@@ -58,8 +58,8 @@ export function apply(ctx, config) {
58
58
  reuse: request => deliverToSession(ctx, request),
59
59
  settle: (sessionId, options) => archiveWhenIdle(ctx, sessionId, options),
60
60
  // The channel is found by name at send time, so it may load after
61
- // this plugin, reload, or be missing (the run records the failure).
62
- send: (target, message, from) => sendMessage({ lookup: name => ctx.get(name), target, message, from, signal: controller.signal }),
61
+ // this plugin, reload, or be missing for a while (the delivery waits).
62
+ send: (target, message, from, options) => sendMessage({ lookup: name => ctx.get(name), target, message, from, signal: controller.signal, ...options }),
63
63
  answer: (sessionId, messageId, options) => waitForAnswer(ctx, sessionId, messageId, options),
64
64
  checks,
65
65
  defaults: {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@soffits/dsh-cron-jobs",
3
- "version": "0.7.0",
3
+ "version": "0.7.1",
4
4
  "description": "Scheduled jobs for DeepSeek Harness: shell commands and agent prompts on cron, RRULE or one-time schedules, a gate that wakes an agent only when there is something to do, result delivery through any plugin that can send messages, tools to manage jobs from a conversation, and a Cron tasks page in the Web GUI.",
5
5
  "type": "module",
6
6
  "main": "./index.js",
package/src/deliver.js CHANGED
@@ -21,6 +21,15 @@ export const DELIVERY_ATTEMPTS = 3
21
21
  /** Wait before each retry, in milliseconds. */
22
22
  export const DELIVERY_RETRY_MS = [5_000, 30_000]
23
23
 
24
+ /**
25
+ * How long a delivery waits for its service to be running again (a plugin
26
+ * reload, a stuck unload) before it fails. A restart in between leaves the
27
+ * delivery pending, and the next start waits again.
28
+ */
29
+ export const SERVICE_WAIT_MS = 60 * 60_000
30
+ /** How often a waiting delivery looks for its service. */
31
+ export const SERVICE_POLL_MS = 10_000
32
+
24
33
  /** Lines of stderr shown in a failure note. */
25
34
  export const FAILURE_STDERR_LINES = 15
26
35
 
@@ -167,44 +176,77 @@ function permanent(error) {
167
176
 
168
177
  /**
169
178
  * Hand one message to the target's service, retrying transient failures.
170
- * Never rejects.
179
+ * A service that is not running is waited for (looked up every `pollMs`, up
180
+ * to `waitMs` in all) instead of counting as a failed attempt. Never rejects.
181
+ *
182
+ * Results: `sent`; `failed` (the service threw on every attempt, or a
183
+ * permanent error); `unavailable` (the service was still not running after
184
+ * `waitMs`); `stopped` (the signal fired before the message was sent). The
185
+ * last two are not final: the caller decides whether to keep the message
186
+ * pending.
171
187
  * @param {object} options
172
188
  * @param {(name: string) => any} options.lookup - Finds a service by name.
173
189
  * @param {DeliveryTarget} options.target
174
190
  * @param {{ text: string, files: string[] }} options.message
175
191
  * @param {{ job: string, sessionId?: string }} options.from
176
- * @param {AbortSignal} [options.signal] - Stops waiting between attempts.
192
+ * @param {AbortSignal} [options.signal] - Stops waiting.
177
193
  * @param {number} [options.attempts]
178
194
  * @param {number[]} [options.retryMs]
179
- * @returns {Promise<{ status: 'sent' | 'failed', attempts: number, error?: string }>}
195
+ * @param {number} [options.waitMs] - Longest wait for a missing service; 0 gives up at once.
196
+ * @param {number} [options.pollMs]
197
+ * @param {(error: string) => void} [options.onWait] - Called once, when the wait for a missing service starts.
198
+ * @returns {Promise<{ status: 'sent' | 'failed' | 'unavailable' | 'stopped', attempts: number, error?: string }>}
180
199
  */
181
- export async function sendMessage({ lookup, target, message, from, signal, attempts = DELIVERY_ATTEMPTS, retryMs = DELIVERY_RETRY_MS }) {
200
+ export async function sendMessage({
201
+ lookup, target, message, from, signal, attempts = DELIVERY_ATTEMPTS, retryMs = DELIVERY_RETRY_MS,
202
+ waitMs = SERVICE_WAIT_MS, pollMs = SERVICE_POLL_MS, onWait,
203
+ }) {
204
+ const deadline = Date.now() + waitMs
205
+ const missing = `no service named ${target.via} is running`
206
+ let waiting = false
182
207
  let error
183
- for (let attempt = 1; attempt <= attempts; attempt++) {
184
- let retry = true
208
+ let tried = 0
209
+ while (tried < attempts) {
210
+ if (signal?.aborted) return { status: 'stopped', attempts: tried, error: error ?? 'stopped before sending' }
211
+ let service
185
212
  try {
186
- const service = lookup(target.via)
187
- if (service === undefined || service === null) {
188
- throw new Error(`no service named ${target.via} is running`)
213
+ service = lookup(target.via)
214
+ } catch {
215
+ service = undefined
216
+ }
217
+ if (service === undefined || service === null) {
218
+ error = missing
219
+ if (Date.now() >= deadline) {
220
+ return { status: 'unavailable', attempts: tried, error: waitMs > 0 ? `${error} (waited ${minutes(waitMs)})` : error }
189
221
  }
190
- if (typeof service.send !== 'function') {
191
- retry = false
192
- throw new Error(`service ${target.via} has no send method`)
222
+ if (!waiting) {
223
+ waiting = true
224
+ onWait?.(error)
193
225
  }
226
+ await sleep(Math.min(pollMs, Math.max(0, deadline - Date.now())), signal)
227
+ continue
228
+ }
229
+ if (typeof service.send !== 'function') {
230
+ return { status: 'failed', attempts: tried + 1, error: `service ${target.via} has no send method` }
231
+ }
232
+ tried++
233
+ try {
194
234
  await service.send({ to: target.to, text: message.text, files: [...message.files], from: { ...from } })
195
- return { status: 'sent', attempts: attempt }
235
+ return { status: 'sent', attempts: tried }
196
236
  } catch (caught) {
197
237
  error = describe(caught)
198
- if (!retry || permanent(caught)) return { status: 'failed', attempts: attempt, error }
199
- }
200
- if (attempt < attempts) {
201
- await sleep(retryMs[Math.min(attempt - 1, retryMs.length - 1)] ?? 0, signal)
202
- if (signal?.aborted) return { status: 'failed', attempts: attempt, error: `${error} (stopped before retrying)` }
238
+ if (permanent(caught)) return { status: 'failed', attempts: tried, error }
203
239
  }
240
+ if (tried < attempts) await sleep(retryMs[Math.min(tried - 1, retryMs.length - 1)] ?? 0, signal)
204
241
  }
205
242
  return { status: 'failed', attempts, error }
206
243
  }
207
244
 
245
+ function minutes(ms) {
246
+ const count = Math.round(ms / 60_000)
247
+ return count >= 1 ? `${count} min` : `${Math.round(ms / 1000)} s`
248
+ }
249
+
208
250
  function sleep(ms, signal) {
209
251
  return new Promise((done) => {
210
252
  const timer = setTimeout(finish, ms)
package/src/history.js CHANGED
@@ -34,14 +34,18 @@ const runSchema = z.object({
34
34
  // archived, kept (see archiveNote), or superseded (a later run reused it).
35
35
  archive: z.enum(['pending', 'archived', 'kept', 'superseded']).optional(),
36
36
  archiveNote: z.string().optional(),
37
- // Result delivery: pending until the woken agent's turn ends, then sent,
38
- // silent (nothing to send) or failed (see error).
37
+ // Result delivery: pending until the woken agent's turn ends or the
38
+ // delivery service is running, then sent, silent (nothing to send) or
39
+ // failed (see error).
39
40
  delivery: z.object({
40
41
  status: z.enum(['pending', 'sent', 'silent', 'failed']),
41
42
  via: z.string(),
42
43
  to: z.string(),
43
44
  // The prompt whose answer is delivered; kept while pending, for a restart.
44
45
  messageId: z.string().optional(),
46
+ // A result ready before its service was running (a command's output, a
47
+ // failure note); kept while pending, for a restart.
48
+ message: z.object({ text: z.string(), files: z.array(z.string()) }).optional(),
45
49
  attempts: z.number().optional(),
46
50
  at: z.string().optional(),
47
51
  error: z.string().optional(),
package/src/job.js CHANGED
@@ -102,7 +102,7 @@ export class JobRunner {
102
102
  * @param {(request: { sessionId: string, text: string, mayUnarchive: boolean, ignoreHold?: boolean }) => Promise<{ queued?: boolean }>} [deps.reuse] - Sends the prompt into an existing session (see session.js deliverToSession); without it every wake opens a new session.
103
103
  * @param {(sessionId: string) => Promise<void>} [deps.keepSession] - Saves the session a new_once job opened, so later runs go to it.
104
104
  * @param {(sessionId: string, options: { signal?: AbortSignal, isLatest: () => boolean, lock: Function }) => Promise<{ archive: string, note?: string }>} [deps.settle] - Archives a session after its turn (see session.js archiveWhenIdle); without it nothing is archived.
105
- * @param {(target: { via: string, to: string }, message: { text: string, files: string[] }, from: { job: string, sessionId?: string }) => Promise<{ status: 'sent' | 'failed', attempts: number, error?: string }>} [deps.send] - Hands a result to its delivery service (see deliver.js sendMessage); without it nothing is delivered.
105
+ * @param {(target: { via: string, to: string }, message: { text: string, files: string[] }, from: { job: string, sessionId?: string }, options: { waitMs?: number, onWait?: Function }) => Promise<{ status: 'sent' | 'failed' | 'unavailable' | 'stopped', attempts: number, error?: string }>} [deps.send] - Hands a result to its delivery service (see deliver.js sendMessage); without it nothing is delivered.
106
106
  * @param {(sessionId: string, messageId: string, options: { signal?: AbortSignal }) => Promise<{ pending: true } | { text: string, reason?: string } | { error: string }>} [deps.answer] - Waits for the final answer to a prompt (see session.js waitForAnswer).
107
107
  * @param {ReturnType<typeof import('./answer-check.js').createAnswerChecks>} [deps.checks] - Answer checks (see answer-check.js); without it a job's answerCheck is ignored.
108
108
  * @param {{ agentCwd?: string, autoArchive?: boolean, reuseWithinHours?: number, deliver?: object }} [deps.defaults] - Plugin-level agent settings and the default delivery target.
@@ -245,59 +245,96 @@ export class JobRunner {
245
245
  else return outcome
246
246
  const message = messageFromText(text, job.cwd || undefined)
247
247
  if (message === undefined) return { ...outcome, delivery: { status: 'silent', ...where } }
248
- return { ...outcome, delivery: await this.deliverMessage(target, message, {}) }
248
+ // No waiting inside the run: a missing service is waited for in the
249
+ // background (see watchDelivery), with the message kept for a restart.
250
+ const delivery = await this.deliverMessage(target, message, { waitMs: 0 })
251
+ return { ...outcome, delivery: delivery.status === 'pending' ? { ...delivery, message } : delivery }
249
252
  }
250
253
 
251
- /** Send one message and log the result; resolves the run's delivery record. */
252
- async deliverMessage(target, message, { sessionId }) {
254
+ /**
255
+ * Send one message and log the result; resolves the run's delivery record.
256
+ * Not sent because the plugin is stopping, or (with `waitMs` 0) because
257
+ * the service is not running: `pending`. Still not running after a longer
258
+ * wait: `failed`.
259
+ * @param {{ via: string, to: string }} target
260
+ * @param {{ text: string, files: string[] }} message
261
+ * @param {{ sessionId?: string, waitMs?: number, onWait?: (error: string) => void }} options
262
+ */
263
+ async deliverMessage(target, message, { sessionId, waitMs, onWait }) {
253
264
  const { job, logger } = this
254
- const sent = await this.send(target, message, { job: job.name, ...(sessionId ? { sessionId } : {}) })
265
+ const sent = await this.send(target, message, { job: job.name, ...(sessionId ? { sessionId } : {}) }, {
266
+ ...(waitMs !== undefined ? { waitMs } : {}), ...(onWait ? { onWait } : {}),
267
+ })
255
268
  const where = describeTarget(target)
256
- if (sent.status === 'sent') logger.info('[%s] delivered the result to %s', job.name, where)
269
+ const pending = sent.status === 'stopped' || (sent.status === 'unavailable' && waitMs === 0)
270
+ const status = sent.status === 'sent' ? 'sent' : pending ? 'pending' : 'failed'
271
+ if (status === 'sent') logger.info('[%s] delivered the result to %s', job.name, where)
272
+ else if (status === 'pending') logger.info('[%s] result for %s not sent yet: %s', job.name, where, sent.error)
257
273
  else logger.warn('[%s] result not delivered to %s after %s attempt(s): %s', job.name, where, sent.attempts, sent.error)
258
274
  return {
259
- status: sent.status,
275
+ status,
260
276
  via: target.via,
261
277
  to: target.to,
262
- attempts: sent.attempts,
263
- at: this.now().toISOString(),
278
+ ...(status === 'pending' ? {} : { attempts: sent.attempts, at: this.now().toISOString() }),
264
279
  ...(sent.error ? { error: sent.error } : {}),
265
280
  }
266
281
  }
267
282
 
268
283
  /**
269
- * Wait for the woken agent's final answer in the background, deliver it,
270
- * and save the result in the run's history. An empty answer or exactly
271
- * [SILENT] sends nothing. Left pending when the plugin unloads, for the next
272
- * copy to finish (see resumeDeliveries).
284
+ * Deliver a pending result in the background and save the outcome in the
285
+ * run's history: a message kept with the delivery (a command's output, a
286
+ * failure note), or else the woken agent's final answer once its turn
287
+ * ends. An empty answer or exactly [SILENT] sends nothing. A service that
288
+ * is not running is waited for (see deliver.js sendMessage). Left pending
289
+ * when the plugin unloads, for the next copy to finish (see
290
+ * resumeDeliveries).
273
291
  */
274
292
  watchDelivery(sessionId, runId, pending) {
275
293
  const { job, logger } = this
276
294
  const target = { via: pending.via, to: pending.to ?? '' }
277
295
  const save = delivery => this.history.update(jobKey(job), runId, { delivery })
278
296
  const logEntry = delivery => this.record({
279
- time: this.now().toISOString(), job: job.name, event: 'delivery', sessionId,
297
+ time: this.now().toISOString(), job: job.name, event: 'delivery', ...(sessionId ? { sessionId } : {}),
280
298
  status: delivery.status, via: target.via, to: target.to, ...(delivery.error ? { error: delivery.error } : {}),
281
299
  })
300
+ // Shown on the page and in the run log while the service is missing.
301
+ const onWait = (error) => {
302
+ logger.warn('[%s] %s; waiting for it to deliver the result', job.name, error)
303
+ save({ ...pending, error }).then(() => logEntry({ status: 'waiting', error })).catch(() => {})
304
+ }
305
+ const send = async (message) => {
306
+ const delivery = await this.deliverMessage(target, message, { sessionId, onWait })
307
+ // Unloading: the next copy of the plugin sends it.
308
+ if (delivery.status === 'pending') {
309
+ await logEntry({ status: 'pending', error: `${delivery.error}; left for the next start` })
310
+ return undefined
311
+ }
312
+ return delivery
313
+ }
282
314
  const watch = (async () => {
283
- if (this.answer === undefined) return
284
- const answer = await this.answer(sessionId, pending.messageId, { signal: this.signal })
285
- if ('pending' in answer || this.signal?.aborted) return
286
- if ('text' in answer) await this.checks?.recheck(pending.messageId, answer.text, { sessionId, signal: this.signal })
287
- this.checks?.forget(pending.messageId)
288
315
  let delivery
289
- if ('error' in answer) {
290
- delivery = { status: 'failed', ...target, at: this.now().toISOString(), error: answer.error }
291
- logger.warn('[%s] no answer to deliver from session %s: %s', job.name, sessionId, answer.error)
316
+ if (pending.message !== undefined) {
317
+ delivery = await send(pending.message)
292
318
  } else {
293
- const message = messageFromText(answer.text, agentSettings(job, this.defaults).cwd)
294
- if (message === undefined) {
295
- delivery = { status: 'silent', ...target, at: this.now().toISOString(), ...(answer.reason && answer.reason !== 'completed' ? { error: `turn ended: ${answer.reason}` } : {}) }
296
- logger.info('[%s] nothing to deliver from session %s', job.name, sessionId)
319
+ if (this.answer === undefined) return
320
+ const answer = await this.answer(sessionId, pending.messageId, { signal: this.signal })
321
+ if ('pending' in answer || this.signal?.aborted) return
322
+ if ('text' in answer) await this.checks?.recheck(pending.messageId, answer.text, { sessionId, signal: this.signal })
323
+ this.checks?.forget(pending.messageId)
324
+ if ('error' in answer) {
325
+ delivery = { status: 'failed', ...target, at: this.now().toISOString(), error: answer.error }
326
+ logger.warn('[%s] no answer to deliver from session %s: %s', job.name, sessionId, answer.error)
297
327
  } else {
298
- delivery = await this.deliverMessage(target, message, { sessionId })
328
+ const message = messageFromText(answer.text, agentSettings(job, this.defaults).cwd)
329
+ if (message === undefined) {
330
+ delivery = { status: 'silent', ...target, at: this.now().toISOString(), ...(answer.reason && answer.reason !== 'completed' ? { error: `turn ended: ${answer.reason}` } : {}) }
331
+ logger.info('[%s] nothing to deliver from session %s', job.name, sessionId)
332
+ } else {
333
+ delivery = await send(message)
334
+ }
299
335
  }
300
336
  }
337
+ if (delivery === undefined) return
301
338
  await save(delivery)
302
339
  await logEntry(delivery)
303
340
  })().catch((error) => {
@@ -311,7 +348,10 @@ export class JobRunner {
311
348
  /** After a restart or reload: finish deliveries an earlier copy of the plugin left pending. */
312
349
  async resumeDeliveries() {
313
350
  for (const run of this.history.runs(jobKey(this.job))) {
314
- if (run.delivery?.status === 'pending' && run.sessionId && run.delivery.messageId) {
351
+ if (run.delivery?.status !== 'pending') continue
352
+ if (run.delivery.message !== undefined) {
353
+ this.watchDelivery(run.sessionId, run.id, run.delivery)
354
+ } else if (run.sessionId && run.delivery.messageId) {
315
355
  // The turn may still be running (a plugin reload, a turn that outlived a restart).
316
356
  this.expectCheck(run.delivery.messageId)
317
357
  this.watchDelivery(run.sessionId, run.id, run.delivery)