@soffits/dsh-cron-jobs 0.11.0 → 0.13.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/README.md CHANGED
@@ -93,6 +93,7 @@ Config jobs live in the config of the `cron-jobs` row. Add an override to your p
93
93
  | `name` | Job name, used in logs and session titles. Must be unique. |
94
94
  | `cron` | Cron expression: 5 fields, or 6 with seconds first. Parsed by [croner](https://github.com/hexagon/croner), which handles daylight-saving changes like Vixie cron: a fixed time skipped by a spring forward runs at the first valid time after the gap, a fixed time repeated by a fall back runs once, and patterns with several hours, minutes or seconds run on both repeated occurrences. Set exactly one of `cron`, `rrule` and `at`, or none when the job has `on`. |
95
95
  | `on` | Event channel patterns that start a run, such as `[mail.inbox, alerts.*]`. See [Events](#events). |
96
+ | `coalesceSeconds` | How long this job's events gather before it runs once. `0` runs at once. The row's `events.coalesceSeconds` when unset. |
96
97
  | `rrule` | RFC 5545 schedule: a `DTSTART` line and an `RRULE` line. The time zone comes from `DTSTART` (`TZID=...`, or `Z` for UTC). See [Schedules](#schedules). |
97
98
  | `at` | Run once at this time: ISO 8601 with an offset, or a local date-time read in `timeZone`. |
98
99
  | `timeZone` | IANA time zone for the cron expression or an `at` without offset. The Host's zone when empty. |
@@ -122,7 +123,7 @@ Next to `jobs`, the row also takes:
122
123
  | `historyRecords` | Runs kept per job for the Cron tasks page. Default 50, at most 1000. |
123
124
  | `runLog` | Optional JSON Lines file of run starts and ends, see below. |
124
125
  | `watchers` | Long-running commands whose output lines are events: `[{ id, channel, command, cwd, enabled }]`. See [Watchers](#watchers). |
125
- | `events.coalesceSeconds` | Events for one job that arrive within this many seconds of the first start one run. Default 30. |
126
+ | `events.coalesceSeconds` | Events for one job that arrive within this many seconds of the first start one run. Default 30; a job's own `coalesceSeconds` replaces it. |
126
127
  | `events.maxRunsPerHour` | Most event-started runs of one job in any hour; past that, events wait and run together. Default 6; `0` means no cap. |
127
128
 
128
129
  ## How runs work
@@ -169,7 +170,7 @@ Each run's delivery shows on the Cron tasks page and in the run log: not sent ye
169
170
 
170
171
  ### Runs cut off by a restart
171
172
 
172
- A woken turn that DSH itself stops before it finishes (a restart, or a reload that disposes the session's agent) is run again once. A turn a person stopped, or one that failed, is not. The cut-off turn delivers nothing; 30 seconds after DSH is back (or after the plugin notices, if it was running all along), the plugin sends a short follow-up into the same session saying the earlier turn was cut off and asking the agent to finish the job without repeating what is done. The session already holds the job's prompt, command output and events, and whatever the cut-off turn did. The rerun's answer is delivered like any other.
173
+ A woken turn that a DSH restart cuts off before it finishes is run again once. A turn a person stopped, or one that failed, is not. Finding the cut turns is left to [dsh-restart-resume](https://github.com/soffits/dsh-restart-resume) (0.4.0 or later), which reads every cut turn from DSH's log after a restart and hands the ones a job started back to this plugin; without it, a cut-off run is recorded but not run again. The cut-off turn delivers nothing; when it is handed back, the plugin sends a short follow-up into the same session saying the earlier turn was cut off and asking the agent to finish the job without repeating what is done. The session already holds the job's prompt, command output and events, and whatever the cut-off turn did. The rerun's answer is delivered like any other.
173
174
 
174
175
  The rerun is skipped, with the reason in the run history and a `rerun-skipped` run-log line, when the cut-off run started more than 2 hours ago, a later run of the job has woken the agent since, the job's next run is less than 15 minutes away, or the job is paused, disabled or deleted. A session the job opened for itself that a person has since taken over is left alone: the rerun fails with a note to the delivery target. A rerun that is cut off too is not run again. The run log marks the cut-off with a `cut-off` line, and the rerun's `start` line carries `rerunOf`.
175
176
 
@@ -257,7 +258,7 @@ echo '{"subject": "hi"}' | dsh-cron-event mail.me --data -
257
258
 
258
259
  It writes one file into the plugin's inbox, `$DSH_HOME/cron-jobs/events/` (mode 700), and waits up to ten seconds for DSH to take it, printing the ids of the jobs it matched. No port, token or network path into DSH is needed, and an event written while DSH is down waits there and is taken at the next start. `--id <key>` drops a second event with the same channel and key within an hour; `--no-wait` returns at once; `--text` sends plain text instead of JSON. Exit code 3 means DSH did not take it in time (it stays queued). The CLI is in the profile's `node_modules/.bin`; link it somewhere on `PATH` to call it by name.
259
260
 
260
- **What a run sees.** Events for one job that arrive within `events.coalesceSeconds` (30 s) of the first one are gathered, and the job runs once with all of them:
261
+ **What a run sees.** Events for one job that arrive within its window, counted from the first one, are gathered, and the job runs once with all of them. The window is the job's own `coalesceSeconds` (set it to 900 for a mailbox that is fine to read every quarter of an hour, or 0 to run at once), or `events.coalesceSeconds` (30 s) for a job without one:
261
262
 
262
263
  - The command gets them on stdin as one JSON document, `{"trigger": "event", "events": [{"channel", "at", "data" or "text", "key", "source"}], "dropped": 0}`, and every command gets `DSH_CRON_TRIGGER` (`schedule`, `manual` or `event`) and `DSH_CRON_JOB` in its environment. A gate still decides whether to wake the agent.
263
264
  - The agent prompt gets the events appended, one JSON line each, in a block marked as untrusted data from outside DSH. An event is a hint: the job should read the truth from its source (the mailbox, the CI run), so a forged or garbled event costs one wasted run, and a message's subject never reaches the agent as an instruction.
@@ -300,8 +301,8 @@ The `cron-jobs-tools` row registers five tools. Their names start with `cron_job
300
301
 
301
302
  | Tool | What it does |
302
303
  |---|---|
303
- | `cron_job_create` | Create a job: a title, a prompt and/or a command, one of `cron`, `rrule` and `at` (with `timeZone` where needed) and/or `on` (event channels), where the prompt goes, and optionally `once`, where the result is delivered and which model its sessions use. |
304
- | `cron_job_edit` | `update` the given fields, `pause`, `resume` (continues from now), or `delete` a job by id. An empty `cron`, `rrule` or `at` removes the schedule of a job with `on`; an empty `on` removes its subscriptions. `prompt_replace` and `command_replace` change the text in place; see below. |
304
+ | `cron_job_create` | Create a job: a title, a prompt and/or a command, one of `cron`, `rrule` and `at` (with `timeZone` where needed) and/or `on` (event channels), where the prompt goes, and optionally `once`, `coalesceSeconds` (the event window), where the result is delivered and which model its sessions use. |
305
+ | `cron_job_edit` | `update` the given fields, `pause`, `resume` (continues from now), or `delete` a job by id. An empty `cron`, `rrule` or `at` removes the schedule of a job with `on`; an empty `on` removes its subscriptions. `coalesceSeconds` sets the event window; a negative number removes it, so the row's setting applies again. `prompt_replace` and `command_replace` change the text in place; see below. |
305
306
  | `cron_job_list` | Every job, from the config and from tools, with its id, state, schedule, next run, target and last run. |
306
307
  | `cron_job_view` | One job's full definition and its five latest runs. |
307
308
  | `cron_job_watch` | `create`, `delete` or `list` [watchers](#watchers). |
@@ -361,7 +362,7 @@ All three are kept in DSH's storage domain service under the domain `cron_jobs`
361
362
  }
362
363
  ```
363
364
 
364
- `schedule` is `{ "kind": "cron", "expression", "timeZone" }`, `{ "kind": "rrule", "rrule" }` or `{ "kind": "at", "at" }` (a UTC instant); `target` is `{ "kind": "new" }`, `{ "kind": "new_once", "sessionId"? }` or `{ "kind": "session", "sessionId" }`; `status` is `active`, `paused` or `ended`; `command`, `timeoutSeconds`, `model` (`{ "provider", "model", "reasoningEffort"? }`) and `deliver` (`{ "via", "to" }` or `false`; the default when missing) are optional. `scheduledAt` is the next run.
365
+ `schedule` is `{ "kind": "cron", "expression", "timeZone" }`, `{ "kind": "rrule", "rrule" }` or `{ "kind": "at", "at" }` (a UTC instant); `target` is `{ "kind": "new" }`, `{ "kind": "new_once", "sessionId"? }` or `{ "kind": "session", "sessionId" }`; `status` is `active`, `paused` or `ended`; `command`, `timeoutSeconds`, `coalesceSeconds`, `model` (`{ "provider", "model", "reasoningEffort"? }`) and `deliver` (`{ "via", "to" }` or `false`; the default when missing) are optional. `scheduledAt` is the next run.
365
366
 
366
367
  For run history and pausing:
367
368
 
package/client.js CHANGED
@@ -85,6 +85,9 @@ window.__ModuleLoader__.load({
85
85
  'field.on': 'Runs on events',
86
86
  'field.once': 'Runs once',
87
87
  'field.onceValue': 'Ends after its first run that was not started by hand',
88
+ 'field.coalesce': 'Event window',
89
+ 'field.coalesceValue': 'Events gather for {seconds} s before one run',
90
+ 'field.coalesceDefault': 'Events gather for {seconds} s before one run (plugin default)',
88
91
  'field.pendingEvents': 'Waiting events',
89
92
  'field.pendingEventsValue': '{count}, run at {time}',
90
93
  'field.timeZone': 'Time zone',
@@ -225,6 +228,9 @@ window.__ModuleLoader__.load({
225
228
  'field.on': '事件触发',
226
229
  'field.once': '只运行一次',
227
230
  'field.onceValue': '第一次非手动运行后结束',
231
+ 'field.coalesce': '事件窗口',
232
+ 'field.coalesceValue': '事件汇集 {seconds} 秒后运行一次',
233
+ 'field.coalesceDefault': '事件汇集 {seconds} 秒后运行一次(插件默认)',
228
234
  'field.pendingEvents': '等待中的事件',
229
235
  'field.pendingEventsValue': '{count} 个,{time} 运行',
230
236
  'field.timeZone': '时区',
@@ -602,6 +608,7 @@ window.__ModuleLoader__.load({
602
608
  : t('field.scheduleNone')),
603
609
  (job.schedule || job.cron) && h(RuleRow, { key: 'zone', label: t('field.timeZone') }, job.timeZone || t('field.timeZoneHost')),
604
610
  job.on?.length > 0 && h(RuleRow, { key: 'on', label: t('field.on') }, h('span', { className: 'dcj-code' }, job.on.join(', '))),
611
+ job.coalesceEffectiveSeconds != null && h(RuleRow, { key: 'coalesce', label: t('field.coalesce') }, t(job.coalesceSeconds == null ? 'field.coalesceDefault' : 'field.coalesceValue', { seconds: job.coalesceEffectiveSeconds })),
605
612
  job.once && h(RuleRow, { key: 'once', label: t('field.once') }, t('field.onceValue')),
606
613
  job.pendingEvents && h(RuleRow, { key: 'pending', label: t('field.pendingEvents') }, t('field.pendingEventsValue', { count: job.pendingEvents.count, time: formatAbsolute(job.pendingEvents.dueAt, t('time.locale')) })),
607
614
  h(RuleRow, { key: 'kind', label: t('field.kind') }, t(kindLabel)),
package/index.js CHANGED
@@ -42,6 +42,19 @@ export function apply(ctx, config) {
42
42
  // The tools plugin looks this up at call time; `controller()` is undefined
43
43
  // while the jobs start or stop.
44
44
  ctx.provide?.('cronJobs', Object.freeze({ controller: () => current }))
45
+ // Resolves once the jobs of the current effect have started (or failed to).
46
+ let started = Promise.resolve()
47
+
48
+ // dsh-restart-resume finds every turn a DSH restart cut off, in DSH's log,
49
+ // and hands back the ones a job started: rerun policy and delivery are ours.
50
+ // Only this claim depends on it, so the scheduler runs with or without it.
51
+ ctx.inject?.(['restartResume'], (sub) => {
52
+ const drop = sub.restartResume?.claim('cron-job', async (turn) => {
53
+ await started
54
+ return current ? current.continueCut(turn) : { continued: false, why: 'the scheduler is not running' }
55
+ })
56
+ if (drop) sub.effect(() => drop)
57
+ })
45
58
 
46
59
  ctx.effect(() => {
47
60
  // Aborting stops commands still running when the plugin unloads.
@@ -98,6 +111,7 @@ export function apply(ctx, config) {
98
111
  })
99
112
  await spool.start()
100
113
  })().catch(error => logger.error('cron jobs not started: %s', error instanceof Error ? error.message : String(error)))
114
+ started = ready
101
115
  return async () => {
102
116
  current = undefined
103
117
  stopTurnHook?.()
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@soffits/dsh-cron-jobs",
3
- "version": "0.11.0",
3
+ "version": "0.13.0",
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/config.js CHANGED
@@ -35,6 +35,7 @@ const Job = z.object({
35
35
  at: z.string().description('Run once at this time: ISO 8601 with an offset, or a local date-time read in timeZone.'),
36
36
  timeZone: z.string().description('IANA time zone for the cron expression or an at without offset, such as Europe/Berlin. The host zone when empty (an at without offset needs it).'),
37
37
  on: z.array(z.string()).default([]).description('Event channels that start a run, such as mail.inbox or alerts.* (* matches any characters). Events arriving close together run the job once; the gate command gets them as JSON on stdin and the prompt gets them appended. Keep a slower schedule as a safety net.'),
38
+ coalesceSeconds: z.natural().description('Events for this job that arrive within this many seconds of the first one start a single run. 0 runs at once. The events.coalesceSeconds setting when unset.'),
38
39
  command: z.string().role('textarea').description('Shell command, run with bash (or sh when bash is missing). Leave empty for an agent-only job, which sends agent.prompt at every run.'),
39
40
  cwd: z.string().description('Working directory of the command. The host process directory when empty.'),
40
41
  timeoutSeconds: z.natural().default(DEFAULT_TIMEOUT_SECONDS)
package/src/controller.js CHANGED
@@ -11,9 +11,6 @@ export const WATCHDOG_MS = 60_000
11
11
  /** How late a tick must be before the watchdog treats its timer as lost. */
12
12
  export const OVERDUE_MS = 60_000
13
13
 
14
- /** Wait after a cut-off turn is found before it runs again, so DSH has finished starting (or stopping). */
15
- export const RERUN_DELAY_MS = 30_000
16
-
17
14
  /** A cut-off run older than this is not rerun: its moment has passed. */
18
15
  export const RERUN_MAX_AGE_MS = 2 * 3600_000
19
16
 
@@ -86,7 +83,7 @@ export class CronJobs {
86
83
  * @param {{ set: typeof setTimeout, clear: typeof clearTimeout }} [options.timers] - Event batch timers; replaceable for tests.
87
84
  * @param {object[]} [options.watchers] - Watchers from the plugin config.
88
85
  * @param {object} [options.watcherOptions] - Passed to {@link WatcherSupervisor} (stateRoot, limits, spawn).
89
- * @param {{ delayMs?: number, maxAgeMs?: number, minLeadMs?: number }} [options.rerun] - Limits for rerunning cut-off runs (see planRerun).
86
+ * @param {{ maxAgeMs?: number, minLeadMs?: number }} [options.rerun] - Limits for rerunning cut-off runs (see continueCut).
90
87
  */
91
88
  constructor({ jobs, logger, run, wake, reuse, settle, send, answer, checks, defaults = {}, signal, record, history, CronClass = CronTimer, TimerClass = ScheduleTimer, now = () => new Date(), watchdogMs = WATCHDOG_MS, overdueMs = OVERDUE_MS, events = {}, timers, watchers = [], watcherOptions = {}, rerun = {} }) {
92
89
  this.logger = logger
@@ -106,12 +103,9 @@ export class CronJobs {
106
103
  ...(timers ? { timers } : {}),
107
104
  }
108
105
  this.rerunLimits = {
109
- delayMs: rerun.delayMs ?? RERUN_DELAY_MS,
110
106
  maxAgeMs: rerun.maxAgeMs ?? RERUN_MAX_AGE_MS,
111
107
  minLeadMs: rerun.minLeadMs ?? RERUN_MIN_LEAD_MS,
112
108
  }
113
- /** Reruns waiting for their delay. */
114
- this.rerunTimers = new Set()
115
109
  this.deduper = new Deduper({ now: () => this.now().getTime() })
116
110
  this.configWatchers = []
117
111
  for (const def of watchers) {
@@ -151,7 +145,6 @@ export class CronJobs {
151
145
  entry.runner = new JobRunner(entry.job, {
152
146
  ...this.deps,
153
147
  ...(entry.record ? { keepSession: sessionId => this.keepSession(entry, sessionId) } : {}),
154
- onCutOff: runId => this.planRerun(entry, runId),
155
148
  })
156
149
  this.entries.set(entry.job.id, entry)
157
150
  this.subscribe(entry)
@@ -166,6 +159,7 @@ export class CronJobs {
166
159
  if (!(entry.job.on?.length > 0)) return
167
160
  entry.batcher = new EventBatcher({
168
161
  ...this.eventSettings,
162
+ ...(entry.job.coalesceSeconds !== undefined ? { coalesceMs: entry.job.coalesceSeconds * 1000 } : {}),
169
163
  now: () => this.now().getTime(),
170
164
  busy: () => entry.runner.running,
171
165
  start: batch => this.runEvents(entry, batch),
@@ -427,37 +421,48 @@ export class CronJobs {
427
421
  }
428
422
 
429
423
  /**
430
- * A run's turn was cut off by DSH (a restart or reload disposed it): rerun
431
- * it once, after a short delay so a stopping DSH does not start it and a
432
- * starting one has settled. A stop cancels the wait and the rerun stays
433
- * pending in the run's history for the next start.
424
+ * A turn of one of this scheduler's runs that a DSH restart cut off, handed
425
+ * over by dsh-restart-resume (which finds every cut turn in DSH's log and
426
+ * asks the plugin that started it): rerun it once, as a follow-up in its own
427
+ * session, unless the limits say its moment has passed.
428
+ * @param {{ sessionId: string, principal: { id?: string } }} turn
429
+ * @returns {Promise<{ continued: boolean, why?: string }>}
434
430
  */
435
- planRerun(entry, runId) {
436
- if (this.stopped) return
437
- const timer = setTimeout(() => {
438
- this.rerunTimers.delete(timer)
439
- this.rerun(entry, runId).catch(error => this.logger.warn('[%s] rerun not started: %s', entry.job.name, String(error)))
440
- }, this.rerunLimits.delayMs)
441
- timer.unref?.()
442
- this.rerunTimers.add(timer)
431
+ async continueCut({ sessionId, principal }) {
432
+ const entry = this.entries.get(principal?.id)
433
+ if (entry === undefined) return { continued: false, why: 'no such job' }
434
+ if (this.history === undefined) return { continued: false, why: 'no run history' }
435
+ const run = this.history.runs(entry.job.id).find(saved => saved.sessionId === sessionId)
436
+ if (run === undefined) return { continued: false, why: 'no run of the job in that session' }
437
+ if (run.rerun !== undefined && run.rerun.status !== 'pending') return { continued: false, why: run.rerun.note ?? `its rerun is already ${run.rerun.status}` }
438
+ if (run.rerunOf !== undefined) {
439
+ await this.skipRerun(entry, run, 'a rerun is not run again')
440
+ return { continued: false, why: 'a rerun is not run again' }
441
+ }
442
+ if (run.rerun === undefined) await this.history.update(entry.job.id, run.id, { rerun: { status: 'pending' } })
443
+ return this.rerun(entry, run.id)
443
444
  }
444
445
 
445
446
  /** Start a pending rerun, or record why it is skipped. */
446
447
  async rerun(entry, runId) {
447
- if (this.stopped || this.entries.get(entry.job.id) !== entry || this.history === undefined) return
448
+ if (this.stopped || this.entries.get(entry.job.id) !== entry) return { continued: false, why: 'the scheduler is stopping' }
448
449
  const runs = this.history.runs(entry.job.id)
449
450
  const run = runs.find(saved => saved.id === runId)
450
- if (run?.rerun?.status !== 'pending') return
451
451
  const note = this.rerunSkipReason(entry, run, runs)
452
452
  if (note !== undefined) {
453
- const time = this.now().toISOString()
454
- await this.history.update(entry.job.id, runId, { rerun: { status: 'skipped', at: time, note } })
455
- await this.record({ time, job: entry.job.name, event: 'rerun-skipped', runId, note })
456
- this.logger.info('[%s] cut-off run not rerun: %s', entry.job.name, note)
457
- return
453
+ await this.skipRerun(entry, run, note)
454
+ return { continued: false, why: note }
458
455
  }
459
456
  // Not a scheduled run: it neither moves the schedule nor ends a once job.
460
457
  this.runTracked(entry, entry.runner.tick({ trigger: run.trigger, rerunOf: run }))
458
+ return { continued: true }
459
+ }
460
+
461
+ async skipRerun(entry, run, note) {
462
+ const time = this.now().toISOString()
463
+ await this.history.update(entry.job.id, run.id, { rerun: { status: 'skipped', at: time, note } })
464
+ await this.record({ time, job: entry.job.name, event: 'rerun-skipped', runId: run.id, note })
465
+ this.logger.info('[%s] cut-off run not rerun: %s', entry.job.name, note)
461
466
  }
462
467
 
463
468
  /** Why a cut-off run should not run again now, or undefined. */
@@ -505,8 +510,6 @@ export class CronJobs {
505
510
  if (this.stopped) return Promise.allSettled([...this.inflight])
506
511
  this.stopped = true
507
512
  clearInterval(this.watchdog)
508
- for (const timer of this.rerunTimers) clearTimeout(timer)
509
- this.rerunTimers.clear()
510
513
  for (const entry of this.entries.values()) {
511
514
  entry.timer?.stop()
512
515
  entry.batcher?.stop()
@@ -624,6 +627,7 @@ export class CronJobs {
624
627
  ...(spec ? { schedule: spec } : {}),
625
628
  ...(on.length > 0 ? { on } : {}),
626
629
  ...(input.once === true ? { once: true } : {}),
630
+ ...(input.coalesceSeconds !== undefined ? { coalesceSeconds: coalesceSeconds(input.coalesceSeconds) } : {}),
627
631
  ...(input.cwd ? { cwd: input.cwd } : {}),
628
632
  ...(input.preset ? { preset: input.preset } : {}),
629
633
  target: input.target ?? { kind: 'new' },
@@ -678,6 +682,10 @@ export class CronJobs {
678
682
  if (patch.once) next.once = true
679
683
  else delete next.once
680
684
  }
685
+ if (patch.coalesceSeconds !== undefined) {
686
+ if (patch.coalesceSeconds === null) delete next.coalesceSeconds
687
+ else next.coalesceSeconds = coalesceSeconds(patch.coalesceSeconds)
688
+ }
681
689
  if (patch.schedule !== undefined) {
682
690
  const schedule = changedSchedule(current.schedule, patch.schedule)
683
691
  if (schedule === null) {
@@ -751,6 +759,8 @@ export class CronJobs {
751
759
  schedule: spec ? { ...spec, text: describeSchedule(spec) } : null,
752
760
  on: job.on?.length > 0 ? job.on : null,
753
761
  once: job.once === true,
762
+ coalesceSeconds: job.coalesceSeconds ?? null,
763
+ coalesceEffectiveSeconds: job.on?.length > 0 ? (job.coalesceSeconds ?? this.eventSettings.coalesceMs / 1000) : null,
754
764
  pendingEvents: entry.batcher?.size > 0 ? { count: entry.batcher.size, dueAt: new Date(entry.batcher.dueAt).toISOString() } : null,
755
765
  cron: spec?.kind === 'cron' ? spec.expression : null,
756
766
  timeZone: scheduleZone(spec) ?? null,
@@ -845,6 +855,7 @@ function fromStored(record) {
845
855
  spec: record.schedule,
846
856
  on: record.on ?? [],
847
857
  ...(record.once ? { once: true } : {}),
858
+ ...(record.coalesceSeconds !== undefined ? { coalesceSeconds: record.coalesceSeconds } : {}),
848
859
  }
849
860
  }
850
861
 
@@ -882,6 +893,11 @@ function hasSchedule(input) {
882
893
  return input !== undefined && ['cron', 'rrule', 'at'].some(key => typeof input[key] === 'string' && input[key].trim() !== '')
883
894
  }
884
895
 
896
+ function coalesceSeconds(value) {
897
+ if (!Number.isInteger(value) || value < 0) throw new JobInputError('invalid_job', 'coalesceSeconds must be a whole number of seconds, 0 or more')
898
+ return value
899
+ }
900
+
885
901
  function patterns(list) {
886
902
  try {
887
903
  return checkPatterns(list)
package/src/job.js CHANGED
@@ -106,7 +106,6 @@ export class JobRunner {
106
106
  * @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.
107
107
  * @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).
108
108
  * @param {ReturnType<typeof import('./answer-check.js').createAnswerChecks>} [deps.checks] - Answer checks (see answer-check.js); without it a job's answerCheck is ignored.
109
- * @param {(runId: string) => void} [deps.onCutOff] - Told about a run whose turn DSH cut off and that waits for its rerun (see CronJobs.planRerun); without it the rerun stays pending.
110
109
  * @param {{ agentCwd?: string, autoArchive?: boolean, reuseWithinHours?: number, deliver?: object }} [deps.defaults] - Plugin-level agent settings and the default delivery target.
111
110
  * @param {{ info: Function, warn: Function }} deps.logger
112
111
  * @param {AbortSignal} [deps.signal] - Stops a running command when aborted.
@@ -114,12 +113,11 @@ export class JobRunner {
114
113
  * @param {{ begin: Function, finish: Function }} [deps.history] - Saved run history (see history.js).
115
114
  * @param {() => Date} [deps.now]
116
115
  */
117
- constructor(job, { run, wake, reuse, keepSession, settle, send, answer, checks, onCutOff, defaults = {}, logger, signal, record = async () => {}, history = NO_HISTORY, now = () => new Date() }) {
116
+ constructor(job, { run, wake, reuse, keepSession, settle, send, answer, checks, defaults = {}, logger, signal, record = async () => {}, history = NO_HISTORY, now = () => new Date() }) {
118
117
  this.job = job
119
118
  this.send = send
120
119
  this.answer = answer
121
120
  this.checks = checks
122
- this.onCutOff = onCutOff
123
121
  this.reuse = reuse
124
122
  this.keepSession = keepSession
125
123
  this.settle = settle
@@ -411,14 +409,17 @@ export class JobRunner {
411
409
  }
412
410
 
413
411
  /**
414
- * A run's turn was cut off: save that its rerun is pending and tell the
415
- * controller, which reruns it once DSH is back. A rerun is never rerun
416
- * again, so a turn that keeps getting cut off does not loop.
412
+ * A run's turn was cut off: save that its rerun is pending. The rerun
413
+ * starts when dsh-restart-resume hands the cut turn back after the restart
414
+ * (CronJobs.continueCut); a rerun the handover already started or skipped
415
+ * keeps its record. A rerun is never rerun again, so a turn that keeps
416
+ * getting cut off does not loop.
417
417
  */
418
418
  async markCutOff(sessionId, runId) {
419
419
  const { job, logger } = this
420
420
  const run = this.history.runs(jobKey(job)).find(saved => saved.id === runId)
421
421
  const time = this.now().toISOString()
422
+ if (run?.rerun !== undefined) return
422
423
  if (run?.rerunOf !== undefined) {
423
424
  const note = 'a rerun is not run again'
424
425
  await this.history.update(jobKey(job), runId, { rerun: { status: 'skipped', at: time, note } })
@@ -429,15 +430,13 @@ export class JobRunner {
429
430
  await this.history.update(jobKey(job), runId, { rerun: { status: 'pending' } })
430
431
  await this.record({ time, job: job.name, event: 'cut-off', runId, sessionId })
431
432
  logger.warn('[%s] the turn in session %s was cut off before it finished; it runs again once DSH is back', job.name, sessionId)
432
- this.onCutOff?.(runId)
433
433
  }
434
434
 
435
435
  /**
436
436
  * After a restart or reload: pick up what an earlier copy of the plugin
437
437
  * left pending. Turns are watched again (they may still be running, after
438
- * a plugin reload or on a provider that outlives a restart), kept
439
- * deliveries are sent, and cut-off runs go back to the controller for
440
- * their rerun.
438
+ * a plugin reload or on a provider that outlives a restart), and kept
439
+ * deliveries are sent.
441
440
  */
442
441
  async resumeRuns() {
443
442
  for (const run of this.history.runs(jobKey(this.job))) {
@@ -450,7 +449,6 @@ export class JobRunner {
450
449
  this.expectCheck(messageId)
451
450
  this.watchTurn(run.sessionId, run.id, messageId, delivery)
452
451
  }
453
- if (run.rerun?.status === 'pending') this.onCutOff?.(run.id)
454
452
  }
455
453
  }
456
454
 
package/src/store.js CHANGED
@@ -40,6 +40,8 @@ export const storedJobSchema = z.object({
40
40
  on: z.array(z.string().min(1)).optional(),
41
41
  // End the job after its first run that was not started by hand.
42
42
  once: z.boolean().optional(),
43
+ // Seconds events gather before a run; the plugin's events.coalesceSeconds when omitted.
44
+ coalesceSeconds: z.number().int().min(0).optional(),
43
45
  // Directory of the command and of new sessions.
44
46
  cwd: z.string().optional(),
45
47
  preset: z.string().optional(),
package/tools.js CHANGED
@@ -52,6 +52,7 @@ export function toolSchemas(prefix) {
52
52
  description: `Event channels that start a run, with * for any characters (mail.inbox, ci.*, dsh.started). Events come from \`dsh-cron-event <channel>\` (any script or hook), from watchers (${prefix}_watch), and dsh.started once after each DSH start. Events within about 30 s run the job once; the command gets them as JSON on stdin and the prompt gets them appended as untrusted data. A job with on may leave out the schedule; keep a slower one as a safety net when events can be missed.`,
53
53
  },
54
54
  once: { type: 'boolean', description: 'End the job after its first run that was not started by hand (an event or a scheduled run). With on: dsh.started, it waits for the next DSH start.' },
55
+ coalesceSeconds: { type: 'number', description: 'How long events for this job gather, counted from the first one, before it runs once with all of them (for example 900 for a quarter of an hour). 0 runs at once. Left out, the plugin\'s events.coalesceSeconds (30 by default) applies. Only matters with on.' },
55
56
  }
56
57
  const model = {
57
58
  type: 'object',
@@ -118,6 +119,7 @@ export function toolSchemas(prefix) {
118
119
  model: { ...model, description: `New model, as in ${prefix}_create. An empty object ({}) returns to the preset's or host default.` },
119
120
  on: { ...fields.on, description: `New event channels, as in ${prefix}_create; an empty list removes them.` },
120
121
  once: fields.once,
122
+ coalesceSeconds: { ...fields.coalesceSeconds, description: `New event gathering time in seconds, as in ${prefix}_create. A negative number (-1) removes the job's own setting, so the plugin's default applies again.` },
121
123
  }, ['id', 'action']),
122
124
  list: object({}, []),
123
125
  view: object({ id: { type: 'string', description: 'Job id.' } }, ['id']),
@@ -165,6 +167,7 @@ export function createTools({ prefix = 'cron_job', getJobs, ctx }) {
165
167
  schedule: { cron: args.cron, rrule: args.rrule, at: args.at, timeZone: args.timeZone },
166
168
  ...(args.on !== undefined ? { on: args.on } : {}),
167
169
  ...(args.once !== undefined ? { once: args.once } : {}),
170
+ ...(args.coalesceSeconds !== undefined ? { coalesceSeconds: args.coalesceSeconds } : {}),
168
171
  cwd: args.cwd || callerCwd(agent),
169
172
  preset: callerPreset(agent),
170
173
  ...(toModel(args.model) ? { model: toModel(args.model) } : {}),
@@ -177,7 +180,7 @@ export function createTools({ prefix = 'cron_job', getJobs, ctx }) {
177
180
  `Update, pause, resume or delete one job created with ${prefix}_create, by id. Jobs from the plugin config are read-only.`,
178
181
  async (args, jobs, agent) => {
179
182
  const { id, action } = args
180
- const changes = ['title', 'prompt', 'command', 'prompt_replace', 'command_replace', 'answerCheck', 'cron', 'rrule', 'at', 'timeZone', 'target', 'sessionId', 'cwd', 'deliver', 'model', 'on', 'once'].filter(key => args[key] !== undefined)
183
+ const changes = ['title', 'prompt', 'command', 'prompt_replace', 'command_replace', 'answerCheck', 'cron', 'rrule', 'at', 'timeZone', 'target', 'sessionId', 'cwd', 'deliver', 'model', 'on', 'once', 'coalesceSeconds'].filter(key => args[key] !== undefined)
181
184
  if (action !== 'update' && changes.length > 0) return failure('invalid_arguments', `${action} takes only id and action.`)
182
185
  if (action === 'delete') return await jobs.remove(id)
183
186
  if (action === 'pause' || action === 'resume') {
@@ -207,6 +210,7 @@ export function createTools({ prefix = 'cron_job', getJobs, ctx }) {
207
210
  cwd: args.cwd,
208
211
  on: args.on,
209
212
  once: args.once,
213
+ ...(args.coalesceSeconds !== undefined ? { coalesceSeconds: args.coalesceSeconds < 0 ? null : args.coalesceSeconds } : {}),
210
214
  ...(args.model !== undefined ? { model: toModel(args.model) ?? null } : {}),
211
215
  ...(scheduleGiven ? { schedule: { cron: args.cron, rrule: args.rrule, at: args.at, timeZone: args.timeZone } } : {}),
212
216
  ...(targetGiven ? { target: await resolveTarget(ctx, agent, args.target ?? 'new', args.sessionId) } : {}),
@@ -354,6 +358,7 @@ export function modelJob(job, { brief = false } = {}) {
354
358
  ...(job.nextRunAt ? { nextRunAt: job.nextRunAt, nextRunAtLocal: `${formatLocalTime(new Date(job.nextRunAt), zone)}${zone ? ` ${zone}` : ''}` } : { nextRunAt: null }),
355
359
  ...(job.on ? { on: job.on } : {}),
356
360
  ...(job.once ? { once: true } : {}),
361
+ ...(job.coalesceEffectiveSeconds !== null && job.coalesceEffectiveSeconds !== undefined ? { coalesceSeconds: job.coalesceEffectiveSeconds, ...(job.coalesceSeconds === null ? { coalesceIsDefault: true } : {}) } : {}),
357
362
  ...(job.pendingEvents ? { pendingEvents: job.pendingEvents } : {}),
358
363
  ...(job.target ? { target: job.target.sessionId ? `${job.target.kind} ${job.target.sessionId}` : job.target.kind } : {}),
359
364
  ...(job.agent?.model ? { model: job.agent.model } : {}),